> 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 Conceda, gestisca e migri gli app token di PowerShell Universal per l'accesso alle API, con ruoli, chiavi di firma e sicurezza avanzata dei token. Può utilizzare gli app token di PowerShell Universal sia con gli [endpoint API personalizzati](/powershell-universal/it/api/endpoints.md) sia con la [Management API](/powershell-universal/it/config/management-api.md). La Management API utilizza i ruoli standard Administrator, Operator e Reader. Gli app token delle API personalizzate possono utilizzare ruoli personalizzati oltre a quelli integrati. Può concedere App Token utilizzando l'Admin Console oppure può utilizzare direttamente la Management API. ## Admin Console Per concedere un token nell'Admin Console, vada su Secure > Application Tokens. Faccia clic sul pulsante Create App Token per concedere un App Token. Quando fa clic su Create App Token, una finestra di dialogo consente di specificare l'identità, il ruolo e l'ora di scadenza del token. ## Management API Può anche concedere app token agli utenti dalla Management API. Per concedere un App Token in modo programmatico tramite l'API, può procedere come segue: {% code collapsedlinecount="10" %} ``` 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 ``` {% endcode %} Gli amministratori possono concedere app token a qualsiasi utente specificando l'ID identità dell'utente. Per concedere un app token a un'identità tramite l'API REST, l'utente deve avere un ruolo definito. Il ruolo Operator definisce l'utente e il relativo App Token otterrà l'accesso in base a tale ruolo. {% code collapsedlinecount="10" %} ``` 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 ``` {% endcode %} ## Ruoli I ruoli degli App Token vengono assegnati direttamente nel token stesso. I ruoli indicano ciò che il token è in grado di eseguire. Non vengono calcolati durante l'uso, quindi la mappatura da ruolo a claim non funzionerà con gli app token. Suggeriamo inoltre di limitare il numero di ruoli all'interno di un app token. Più ruoli vengono aggiunti al token, maggiore sarà la dimensione del token, con conseguente riduzione delle prestazioni o problemi con determinati strumenti che non consentono valori di token più lunghi. Può utilizzare ruoli personalizzati con un set di autorizzazioni personalizzato per limitare il numero di ruoli fornendo al contempo un accesso personalizzato alla piattaforma PowerShell Universal. Le autorizzazioni vengono valutate quando il ruolo viene utilizzato. Ciò significa che assegnare 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 degli App Token Può migrare gli app token tra sistemi utilizzando la Management API. Ciò è utile quando si sviluppa per scenari ad alta disponibilità. Di seguito è riportato un esempio della POST necessaria per creare un app token esistente in qualsiasi istanza PSU. Tenga presente che la chiave di firma deve essere la stessa tra le istanze. È necessario un app token valido nel sistema di destinazione per creare i token migrati. {% code collapsedlinecount="10" %} ```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" } ``` {% endcode %} ## Sicurezza avanzata degli App Token Quando la sicurezza avanzata degli app token è 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 degli app token 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 volere utilizzare un documento di discovery OAuth 2.0 per fornire la convalida della chiave di firma. Utilizzando un sistema remoto di questo tipo, può garantire 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. Quando PowerShell Universal viene caricato, leggerà le chiavi di firma dal documento e le fornirà al sistema di convalida JWT. {% code collapsedlinecount="10" %} ```json { "Jwt" : { "DiscoveryDocument": "https://auth20/metadata.xml" } } ``` {% endcode %} ## App Token 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 realizzarlo in Auth0. {% code collapsedlinecount="10" %} ```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" ] } ``` {% endcode %} In alternativa, può abilitare la valutazione dei claim per i token JWT. Per impostazione predefinita, PowerShell Universal utilizza un set 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. {% code collapsedlinecount="10" %} ```json { "Jwt": { "EvaluateClaims": "true" } } ``` {% endcode %} 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 normale applicazione web. Può farlo facendo clic su Applications \ Applications e poi su Create Application. #### Creare un'API Auth0 Successivamente, crei un'API Auth0 facendo clic su Applications \ APIs e poi su Create API. Imposti il nome e il namespace su valori univoci e lasci le restanti opzioni ai valori predefiniti. #### 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 Nelle impostazioni dell'applicazione, faccia clic su APIs e attivi l'interruttore accanto all'API per autorizzare l'applicazione a utilizzare l'API. Selezioni le autorizzazioni che desidera fornire all'applicazione. Queste appariranno come claim di autorizzazione nel token. #### Recuperare un token di accesso da Auth0 Dopo aver definito l'applicazione e l'API, può richiedere un token di accesso in Auth0. I valori `client_id` e `client_secret` si trovano nella pagina Application Details. Il valore `audience` deve essere l'identificatore della propria API. {% code collapsedlinecount="10" %} ```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 ``` {% endcode %} #### Configurare PowerShell Universal Dovrà configurare PowerShell Universal per utilizzare Auth0 come provider JWT. Può farlo modificando il file appsettings.json. Questi devono includere valori provenienti da 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. {% code collapsedlinecount="10" %} ```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" } } ``` {% endcode %} #### Configurare un ruolo da mappare all'autorizzazione Auth0 Infine, crei un ruolo che si mappa all'autorizzazione 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 della Management API di PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell New-PSURole -Name "API Admin" -Permissions ".*" -ClaimType "permissions" -ClaimValue "Administrator" ``` {% endcode %} #### Utilizzo di un App Token con PowerShell Universal Ora che dispone di un app token Auth0, può utilizzarlo esattamente come farebbe con gli app token integrati. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} ### Esempio: token di accesso Auth0 con claim personalizzati Può utilizzare le API e le applicazioni Auth0 per fornire app token per PowerShell Universal. #### Creare un'applicazione Auth0 In Auth0, crei un'applicazione per una normale applicazione web. Può farlo facendo clic su Applications \ Applications e poi su Create Application. #### Creare un'API Auth0 Successivamente, crei un'API Auth0 facendo clic su Applications \ APIs e poi su Create API. Imposti il nome e il namespace su valori univoci e lasci le restanti opzioni ai valori predefiniti. #### Autorizzare l'applicazione a utilizzare l'API Nelle impostazioni dell'applicazione, faccia clic su APIs e attivi l'interruttore accanto all'API per autorizzare l'applicazione a utilizzare l'API. #### Recuperare un token di accesso da Auth0 Dopo aver definito l'applicazione e l'API, può richiedere un token di accesso in Auth0. I valori `client_id` e `client_secret` si trovano nella pagina Application Details. Il valore `audience` deve essere l'identificatore della propria API. {% code collapsedlinecount="10" %} ```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 ``` {% endcode %} #### Configurare PowerShell Universal Dovrà configurare PowerShell Universal per utilizzare Auth0 come provider JWT. Può farlo modificando il file appsettings.json. Questi devono includere valori provenienti da 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. {% code collapsedlinecount="10" %} ```json { "Jwt": { "DiscoveryDocument": "https://ironmansoftware.us.auth0.com/v2.0/.well-known/openid-configuration", "Issuer": "https://ironmansoftware.us.auth0.com/", "Audience": "https://powershelluniversal.com" } } ``` {% endcode %} #### Utilizzo di un App Token con PowerShell Universal Ora che dispone di un app token Auth0, può utilizzarlo esattamente come farebbe con gli app token integrati. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity/my -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} #### 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 gli app token 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 poi 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. {% code collapsedlinecount="10" %} ```javascript exports.onExecuteCredentialsExchange = async (event, api) => { api.accessToken.setCustomClaim("PSUPermission", "(.*)") }; ``` {% endcode %} Successivamente, aggiunga l'azione al trigger del flusso di lavoro per `credential-exchange` facendo clic su Actions, quindi su Triggers e poi su `credential-exchange.` Trascini l'azione Set Permissions nel flusso di lavoro. Una volta completata questa operazione, può generare un nuovo token e accedere a qualsiasi API all'interno di PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod http://localhost:5000/api/v1/identity -Headers @{ Authorization = "tokenValue" } ``` {% endcode %} ### Vedere anche * [Devolutions Academy – Struttura e autenticazione](https://academy.devolutions.net/student/activity/3542770-part-1-outline-and-authentication) * [Devolutions Academy – Autenticazione](https://academy.devolutions.net/student/path/3465905/activity/5612255) --- # 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.