> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/it/sicurezza/app-tokens.md). # Token dell'app Può utilizzare i token dell'app di PowerShell Universal sia con gli [endpoint API personalizzati](https://github.com/Devolutions/docs/tree/master/translations/it/powershell-universal/config/security/broken-reference/README.md) sia con l'[API di gestione](/powershell-universal/it/config/management-api.md). L'API di gestione utilizza i ruoli standard Administrator, Operator e Reader. I token dell'app per le API personalizzate possono utilizzare ruoli personalizzati oltre a quelli integrati. Può concedere i token dell'app utilizzando la Admin Console oppure può utilizzare direttamente l'API di gestione. ## Admin Console Per concedere un token nella Admin Console, vada a Security \ Tokens. Faccia clic sul pulsante Create App Token per concedere un token dell'app.
Quando fa clic su Create App Token, una finestra di dialogo le consente di specificare l'identità, il ruolo e la scadenza del token.

Finestra di dialogo del token dell'app

## API di gestione Può inoltre concedere token dell'app agli utenti dall'API di gestione. Per concedere un token dell'app a livello di codice tramite l'API, può procedere come segue: ``` PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/api/v1/signin -Method POST -Body (@{ username = 'admin'; password = 'test' } | ConvertTo-Json) -SessionVariable Session -ContentType 'application/json' PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/api/v1/apptoken/grant -WebSession $Session id : 3 token : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2Ns YWltcy9uYW1lIjoiYWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoI joiYjJlOGM4MDktMjE0NS00NjhhLWI4NTEtYjU0MjVhZDgzOTQ2Iiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2 hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6WyJBZG1pbmlzdHJhdG9yIiwiT3BlcmF0b3I iLCJSZWFkZXIiXSwibmJmIjoxNTkzMTkyMjY1LCJleHAiOjE2MjQ3MjgyNjUsImlzcyI6Iklyb25tYW5Tb2Z0d2FyZSIsImF1ZCI6IlBv d2VyU2hlbGxVbml2ZXJzYWwifQ.hnKyXe8C4kbrmkeeUFr-LUDjVr-xP7fRWwgClcrnxfc identity : @{id=3; name=admin; source=0; role=} revoked : False role : Administrator, Operator, Reader created : 26/06/2020 17:24:25 expiration : 26/06/2021 17:24:25 revokedDate : 01/01/0001 00:00:00 ``` Gli amministratori possono concedere token dell'app a qualsiasi utente specificando l'ID identità dell'utente. Per concedere un token dell'app a un'identità tramite l'API REST, l'utente deve avere un ruolo definito. Il ruolo Operator definisce l'utente e al suo token dell'app verrà concesso l'accesso in base a tale ruolo. ``` PS C:\Users\adamr> Invoke-RestMethod http://localhost:5000/api/v1/apptoken/grant/2 -WebSession $Session id : 4 token : eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2Ns YWltcy9uYW1lIjoiYWRhbUBpcm9ubWFuc29mdHdhcmUub25taWNyb3NvZnQuY29tIiwiaHR0cDovL3NjaGVtYXMueG1sc29hcC5vcmcvd 3MvMjAwNS8wNS9pZGVudGl0eS9jbGFpbXMvaGFzaCI6IjhhYWM2NWFmLTA2NmItNDYwNy1hMGJjLTNlYTM2ZDY2YjJmMSIsInN1YiI6Il Bvd2VyU2hlbGxVbml2ZXJzYWwiLCJodHRwOi8vc2NoZW1hcy5taWNyb3NvZnQuY29tL3dzLzIwMDgvMDYvaWRlbnRpdHkvY2xhaW1zL3J vbGUiOiJPcGVyYXRvciIsIm5iZiI6MTU5MzE5MjM2MCwiZXhwIjoxNjI0NzI4MzYwLCJpc3MiOiJJcm9ubWFuU29mdHdhcmUiLCJhdWQi OiJQb3dlclNoZWxsVW5pdmVyc2FsIn0.9VYiRFOojFyZMH0E5rwdfFcOkoasXFrrWJDNtYk0PIw identity : @{id=2; name=adam@ironmansoftware.onmicrosoft.com; source=0; role=} revoked : False role : Operator created : 26/06/2020 17:26:00 expiration : 26/06/2021 17:26:00 revokedDate : 01/01/0001 00:00:00 ``` ## Ruoli I ruoli dei token dell'app vengono assegnati direttamente nel token stesso. I ruoli indicano ciò che il token è in grado di eseguire. Non vengono calcolati durante l'uso, pertanto la mappatura tra ruoli e claim non funziona con i token dell'app. Consigliamo inoltre di limitare il numero di ruoli all'interno di un token dell'app. Più ruoli vengono aggiunti al token, più aumenta la dimensione del token e si riducono le prestazioni oppure si verificano problemi con determinati strumenti che non consentono valori di token più lunghi. Può utilizzare ruoli personalizzati con un insieme personalizzato di autorizzazioni per limitare il numero di ruoli fornendo comunque un accesso personalizzato alla piattaforma PowerShell Universal. Le autorizzazioni vengono valutate quando il ruolo viene utilizzato. Ciò significa che l'assegnazione di un ruolo personalizzato a un token lo rende più flessibile rispetto a un ruolo integrato, poiché le autorizzazioni possono essere aggiunte o rimosse da un ruolo senza generare un nuovo token. ## Migrazione dei token dell'app Può migrare i token dell'app tra sistemi utilizzando l'API di gestione. Ciò è utile durante lo sviluppo per scenari ad alta disponibilità. Di seguito è riportato un esempio della POST necessaria per creare un token dell'app esistente in qualsiasi istanza PSU. Tenga presente che la chiave di firma deve essere la stessa tra le istanze. È necessario un token dell'app valido nel sistema di destinazione per creare i token migrati. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/apptoken -Method POST -Body (@{ Token = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMDhiYTFlMTktMjgyZi00YTRjLWIxZGUtNTY0Zjk3NWU2ODEwIiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6InBvbGljeSIsIm5iZiI6MTYzMzEwNjkzMywiZXhwIjoxNjQwODg2NDgwLCJpc3MiOiJJcm9ubWFuU29mdHdhcmUiLCJhdWQiOiJQb3dlclNoZWxsVW5pdmVyc2FsIn0.GHjJI3kMpcAY1pvOGLWOdPqC2-IPo0-4lJfHZwStmOk' Identity = @{ Name = 'Admin' } Role = 'Administrator' Expiration = (Get-Date).AddMonths(6) } | ConvertTo-Json) -Headers @{ "Content-Type" = "application/json"; "Authorization" = "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9uYW1lIjoiQWRtaW4iLCJodHRwOi8vc2NoZW1hcy54bWxzb2FwLm9yZy93cy8yMDA1LzA1L2lkZW50aXR5L2NsYWltcy9oYXNoIjoiMjVjMzFlZTAtMGM4Mi00NzBiLWJkZGYtOGFmOTgxZGI2ZDdmIiwic3ViIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCIsImh0dHA6Ly9zY2hlbWFzLm1pY3Jvc29mdC5jb20vd3MvMjAwOC8wNi9pZGVudGl0eS9jbGFpbXMvcm9sZSI6IkFkbWluaXN0cmF0b3IiLCJuYmYiOjE2MzM2NDY5OTgsImV4cCI6MTYzNjIzODk0MCwiaXNzIjoiSXJvbm1hblNvZnR3YXJlIiwiYXVkIjoiUG93ZXJTaGVsbFVuaXZlcnNhbCJ9.jw2VCvtpOWpgnpIUlO8sTdK9Z5RMoWLmvYn0MDmzkNM" } ``` ## Sicurezza avanzata dei token dell'app Quando la sicurezza avanzata dei token dell'app è abilitata, i valori dei token sono accessibili solo al momento della creazione. Vengono sottoposti ad hashing e il database memorizza il valore hash anziché il token. Il token si utilizza allo stesso modo di qualsiasi altro token. {% hint style="warning" %} L'abilitazione della sicurezza dei token dell'app invaliderà tutti i token esistenti. {% endhint %} ## Token di sistema I token di sistema sono un modo per fornire token a sistemi non utente. Non sono legati direttamente all'identità di un utente. Può fornire un nome per il token, oltre alla scadenza e ai ruoli. ## Chiavi di firma ### Chiave di firma locale Per impostazione predefinita, PowerShell Universal crea una chiave di firma basata sulla stringa Jwt \ SigningKey in appsettings.json. Questo valore viene utilizzato per codificare e decodificare il token. Se le chiavi di firma non corrispondono, il token verrà considerato non valido. La modifica della chiave di firma invaliderà tutte le chiavi di firma esistenti. ### Chiave di firma remota Potrebbe voler utilizzare un documento di discovery OAuth 2.0 per fornire la convalida della chiave di firma. Utilizzando un sistema remoto di questo tipo, può assicurarsi che, quando le chiavi di firma vengono modificate, non sia necessario modificare la configurazione di PowerShell Universal. Per utilizzare una chiave di firma remota, imposti il valore Jwt \ DiscoveryDocument in appsettings.json sull'URL del documento di metadati OAuth 2.0. Al caricamento, PowerShell Universal leggerà le chiavi di firma dal documento e le fornirà al sistema di convalida JWT. ```json { "Jwt" : { "DiscoveryDocument": "https://auth20/metadata.xml" } } ``` ## Token dell'app esterni Quando si configura una chiave di firma remota, i token vengono generati dal provider OAuth 2.0. Per questo motivo, anche le informazioni sui claim vengono generate da tale provider. Per assegnare correttamente ruoli e autorizzazioni all'interno di PowerShell Universal, dovrà assicurarsi che i claim corretti siano definiti all'interno del token. PowerShell Universal valuterà i seguenti valori di claim all'interno di un token. * PSUPermission - Definisce le autorizzazioni del token * Roles - Definisce i ruoli del token. Per consentire l'accesso alle risorse all'interno di un'istanza di PowerShell Universal, si assicuri che il token contenga i claim corretti. Ad esempio, il token seguente consentirebbe l'accesso completo alle API di gestione di PowerShell Universal perché fornisce il claim `PSUPermission` con un selettore per tutte le autorizzazioni. Può utilizzare l'[esempio seguente](#example-auth0-access-token-with-custom-claims) per vedere come farlo in Auth0. ```json { "PSUPermission": "(.*)", "iss": "https://myprovider.us.auth0.com/", "sub": "wKeaTMprlv7kX46eI9SwwvaGJzWPkbtt@clients", "aud": "https://mydomain.com", "iat": 1758898719, "exp": 1758985119, "scope": "(.*) Administrator", "gty": "client-credentials", "azp": "wKeaTMprlv7kX46eI9SwwvaGJzWPkbtt", "permissions": [ "(.*)", "Administrator" ] } ``` In alternativa, può abilitare la valutazione dei claim per i token JWT. Per impostazione predefinita, PowerShell Universal utilizza un insieme statico di autorizzazioni quando riceve un token. Se abilita la valutazione dei claim per i token JWT, il sistema di autorizzazione elaborerà il token e aggiungerà le autorizzazioni quando il token viene utilizzato anziché quando viene generato. ### Valutazione dei claim per i token Per abilitare la valutazione dei claim per i token, può modificare appsettings.json per indicare a PSU di eseguire la valutazione dei claim durante l'esecuzione della convalida del token. ```json { "Jwt": { "EvaluateClaims": "true" } } ``` Questo utilizzerà `roles.ps1` per verificare i claim dei token forniti e assegnare le autorizzazioni in base ai ruoli qualificati. ### Esempio: token di accesso Auth0 con valutazione dei claim Utilizzando le funzionalità standard di Auth0, può generare token che possono quindi fornire ruoli in base ai claim del token. Ciò non richiede trigger o azioni speciali all'interno di Auth0. #### Creare un'applicazione Auth0 In Auth0, crei un'applicazione per una regular web application. Può farlo facendo clic su Applications \ Applications e quindi su Create Application.
#### Creare un'API Auth0 Successivamente, crei un'API Auth0 facendo clic su Applications \ APIs e quindi su Create API. Imposti il nome e lo spazio dei nomi su valori univoci e lasci le altre opzioni come predefinite.
#### Creare ambiti di autorizzazione personalizzati nella propria API All'interno della propria API, definisca autorizzazioni personalizzate, ad esempio una con un nome di ruolo.
#### Autorizzare l'applicazione a utilizzare l'API All'interno delle impostazioni dell'applicazione, faccia clic su APIs e attivi l'interruttore accanto all'API per autorizzare l'applicazione a utilizzarla. Selezioni le autorizzazioni che desidera fornire all'applicazione. Queste verranno visualizzate come claim di autorizzazione nel token.
#### Recuperare un token di accesso da Auth0 Con l'applicazione e l'API definite, ora può richiedere un token di accesso in Auth0. I valori `client_id` e `client_secret` sono disponibili nella pagina Application Details. Il valore `audience` deve essere l'identificatore della sua API. ```powershell Invoke-RestMethod 'https://ironmansoftware.us.auth0.com/oauth/token' -Body @{ client_id = "xyz123" client_secret = "xyz123" audience = "https://powershelluniversal.com" grant_type = "client_credentials" } -Method POST ``` #### Configurare PowerShell Universal Dovrà configurare PowerShell Universal per utilizzare Auth0 come provider JWT. Può farlo modificando il file appsettings.json. Questi devono includere valori di Auth0. Il `DiscoveryDocument` farà parte del suo tenant e aiuta a definire dati come le chiavi di firma per i token JWT. L'`Issuer` sarà l'URL del suo tenant. L'`Audience` sarà l'identificatore della sua API. ```json { "Jwt": { "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration", "Issuer": "https://ironmansoftware.us.auth0.com/", "Audience": "https://powershelluniversal.com", "EvaluateClaims": "true" } } ``` #### Configurare un ruolo da mappare all'autorizzazione di Auth0 Infine, crei un ruolo che si mappa all'autorizzazione di Auth0. L'esempio seguente verifica che il token API abbia un claim permissions con il valore `Administrator`, come configurato sopra. In tal caso, al token viene assegnato il ruolo API Admin, che dispone di tutte le autorizzazioni all'interno dell'API di gestione di PowerShell Universal. ```powershell New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator" ``` #### Utilizzare un token dell'app con PowerShell Universal Ora che dispone di un token dell'app Auth0, può utilizzarlo esattamente come farebbe con i token dell'app integrati. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` ### Esempio: token di accesso Auth0 con claim personalizzati Può utilizzare le API e le applicazioni Auth0 per fornire token dell'app per PowerShell Universal. #### Creare un'applicazione Auth0 In Auth0, crei un'applicazione per una regular web application. Può farlo facendo clic su Applications \ Applications e quindi su Create Application.
#### Creare un'API Auth0 Successivamente, crei un'API Auth0 facendo clic su Applications \ APIs e quindi su Create API. Imposti il nome e lo spazio dei nomi su valori univoci e lasci le altre opzioni come predefinite.
#### Autorizzare l'applicazione a utilizzare l'API All'interno delle impostazioni dell'applicazione, faccia clic su APIs e attivi l'interruttore accanto all'API per autorizzare l'applicazione a utilizzarla. #### Recuperare un token di accesso da Auth0 Con l'applicazione e l'API definite, ora può richiedere un token di accesso in Auth0. I valori `client_id` e `client_secret` sono disponibili nella pagina Application Details. Il valore `audience` deve essere l'identificatore della sua API. ```powershell Invoke-RestMethod 'https://ironmansoftware.us.auth0.com/oauth/token' -Body @{ client_id = "xyz123" client_secret = "xyz123" audience = "https://powershelluniversal.com" grant_type = "client_credentials" } -Method POST ``` #### Configurare PowerShell Universal Dovrà configurare PowerShell Universal per utilizzare Auth0 come provider JWT. Può farlo modificando il file appsettings.json. Questi devono includere valori di Auth0. Il `DiscoveryDocument` farà parte del suo tenant e aiuta a definire dati come le chiavi di firma per i token JWT. L'`Issuer` sarà l'URL del suo tenant. L'`Audience` sarà l'identificatore della sua API. ```json { "Jwt": { "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration", "Issuer": "https://ironmansoftware.us.auth0.com/", "Audience": "https://powershelluniversal.com" } } ``` #### Utilizzare un token dell'app con PowerShell Universal Ora che dispone di un token dell'app Auth0, può utilizzarlo esattamente come farebbe con i token dell'app integrati. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` #### Facoltativo: definire un trigger di azione Auth0 Quando si concede un nuovo token di accesso da Auth0, questo non conterrà i ruoli o le autorizzazioni standard come i token dell'app integrati in PowerShell Universal. Può controllare questo aspetto definendo una Custom Action e assegnandola al trigger `credential-exchange`. Faccia clic su Actions, quindi su Library e Create Action e infine su Create Custom Action. Selezioni il trigger Password Reset / Post Challenge e assegni un nome all'azione.
Definisca l'azione impostando un claim personalizzato per il tipo di claim `PSUPermission`. Questo esempio fornisce semplicemente l'accesso completo alle API di PowerShell Universal. Può utilizzare il contesto dell'evento per definire quali autorizzazioni vengono ricevute in base alla richiesta del token di accesso. ```javascript exports.onExecuteCredentialsExchange = async (event, api) => { api.accessToken.setCustomClaim("PSUPermission", "(.*)") }; ``` Successivamente, aggiunga l'azione al trigger del flusso di lavoro per `credential-exchange` facendo clic su Actions, quindi su Triggers e infine su `credential-exchange.`
Trascini l'azione Set Permissions nel flusso di lavoro. Una volta completata questa operazione, potrà generare un nuovo token e accedere a qualsiasi API all'interno di PowerShell Universal. ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity -Headers @{ Authorization = "tokenValue" } ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/it/sicurezza/app-tokens.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.