> 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/enterprise-security/openid-connect.md). # OpenID Connect Configuri l'autenticazione OpenID Connect in PowerShell Universal con Entra ID o Okta, inclusa la mappatura dei claim e i token di accesso delegati. {% hint style="info" %} OpenID Connect richiede una [licenza](https://store.devolutions.net/package#psu). {% endhint %} OpenID Connect è un livello di autenticazione basato su OAuth 2.0, un framework di autorizzazione. È supportato da molti vendor e offre la possibilità di autenticarsi presso sistemi come EntraID. Questo documento illustra i passaggi necessari per configurare EntraID OpenID Connect e utilizzarlo con Universal. ## Configurazione di Azure Entra ID (Azure Active Directory) Nel portale di Azure, vada al blade Entra ID. Quindi, clicchi sul nodo Enterprise Application e poi su New application. Quindi, clicchi su Create your own application. Scelga un nome per l'applicazione e selezioni Register an application to integrate with Microsoft Entra ID. Nella pagina Register an application, definisca un redirect URI. Sarà l'URL del server PowerShell Universal a cui Entra ID reindirizzerà l'utente. Questo valore è definito nel file di configurazione di PowerShell Universal, `appsettings.json`. Ora che l'applicazione è stata creata, dalla pagina Enterprise Applications, clicchi su Single sign-on e poi su Go to application. Verrà portato alla pagina di registrazione dell'applicazione. Certificates and secrets e definisca un nuovo secret. Verrà utilizzato con il file di configurazione di PowerShell Universal. Ora dovremo raccogliere diverse informazioni dall'applicazione da fornire a PowerShell Universal. Dalla home page dell'applicazione, salvi l'Application (client) ID e il directory (tenant) ID. ### Mappatura dei claim Per fornire i group claim a PowerShell Universal, dovrà esporre i group claim dalla registrazione dell'app. Clicchi su Token Configuration e poi su Add groups claim. Dopo aver cliccato su Add groups claim, potrà selezionare quali gruppi vengono forniti. Se seleziona All Groups, i groups claim verranno forniti a PowerShell Universal Se seleziona Groups assigned to the application, si assicuri di selezionare il valore Emit groups as role claims. Questa impostazione richiede un piano Entra ID a pagamento. Per assegnare un gruppo alla registrazione dell'app, individui la sua app in Enterprise Applications e clicchi su User and Groups. Quindi, clicchi su Add User\Group e selezioni i gruppi che desidera assegnare all'applicazione. Una volta configurato il groups claim in Entra ID, potrà aggiornare le mappature dei claim di PowerShell Universal in base ai gruppi forniti. Per ogni ruolo che desidera assegnare a un gruppo Entra ID, specifichi il Claim Type e il Claim Value per quel ruolo. Ad esempio, nel mio ambiente ho un gruppo con l'ID 446832da-d4ad-4972-b0a2-eda736129928. Il Claim Type per questo oggetto è . Per assegnarlo al gruppo di amministratori, procederei come segue. Gli utenti di questo gruppo farebbero ora parte del ruolo Administrator in PowerShell Universal. ### Eccedenze di gruppi Per le organizzazioni che hanno utenti con molti gruppi, è consigliabile limitare il numero di gruppi inviati a PowerShell Universal. L'invio di un numero elevato di gruppi può superare la dimensione del token e causare errori di autorizzazione. Se desidera limitare i gruppi, selezioni Groups assigned to the application. Per aggiungere gruppi all'applicazione, torni alla pagina dell'Enterprise application e selezioni Users and groups. Clicchi sul valore Add user/group per assegnare questi gruppi all'applicazione. Quando gli utenti accedono a PowerShell Universal, verranno forniti solo questi group claim. Per maggiori informazioni sulle eccedenze di gruppi, [clicchi qui](https://learn.microsoft.com/en-us/security/zero-trust/develop/configure-tokens-group-claims-app-roles#group-overages). ### Configurazione di Universal per Entra ID #### Utilizzare Appsettings.json {% hint style="info" %} Maggiori informazioni su `appsettings.json` nella nostra pagina [Impostazioni ](/powershell-universal/it/config/settings.md). {% endhint %} Ora che abbiamo completato la configurazione di una App Registration di AzureAD, possiamo aggiornare il file `appsettings.json` con le impostazioni appropriate. Per la mia applicazione, sarebbe simile a questo. {% code collapsedlinecount="10" %} ```javascript "OIDC": { "Enabled": "true", "CallbackPath": "/auth/signin-oidc", "ClientID": "", "ClientSecret": "", "Resource": "", "Authority": "https://login.microsoftonline.com/", "ResponseType": "code", "SaveTokens": "false", "GetUserInfo": false }, ``` {% endcode %} {% hint style="warning" %} Se utilizza Chrome, dovrà anche abilitare HTTPS. Senza HTTPS abilitato, visualizzerà un errore 500. {% endhint %} #### Utilizzare Authentication.ps1 Può utilizzare la console di amministrazione per configurare OpenID Connect. Consigliamo questo metodo, poiché non sarà necessario riavviare il servizio PowerShell Universal dopo aver configurato OIDC. Per aggiungere un nuovo metodo di autenticazione, vada su Secure > Authentication e aggiunga il provider OpenID Connect. Una volta aggiunto il provider, può cliccare sul pulsante dei dettagli per inserire le impostazioni necessarie per autenticarsi presso il suo provider OIDC. Dopo aver configurato le opzioni OIDC, imposti il provider su abilitato ed esegua il logout. Quando visiterà la pagina `/admin`, le verrà richiesto il login OIDC. ### Token di accesso delegati Può utilizzare i token di accesso generati da un login OIDC per altri servizi a cui l'utente potrebbe avere accesso. Nel suo provider OIDC, come Entra ID, può concedere autorizzazioni aggiuntive al token. Dovrà inoltre abilitare i token di accesso all'interno del flusso di autenticazione, in modo che il token fornisca l'accesso alle risorse necessarie. Infine, nel file `appsettings.json` di PSU, dovrà assicurarsi che `SaveTokens` sia abilitato, che il tipo di risorsa includa token e che la risorsa a cui desidera accedere sia inclusa nell'impostazione Resource. L'URL specificato nella risorsa dovrebbe essere elencato all'interno del provider. L'esempio seguente aggiunge una risorsa per Microsoft O365. {% code collapsedlinecount="10" %} ```javascript "OIDC": { "Enabled": "true", "CallbackPath": "/auth/signin-oidc", "ClientID": "", "ClientSecret": "", "Resource": "https://manage.office.com/", "Authority": "https://login.microsoftonline.com/tenant", "ResponseType": "id_token token", "SaveTokens": "true", "UseTokenLifetime": true }, ``` {% endcode %} Nella sua dashboard, avrà ora accesso alle variabili `$AccessToken` e `$IdToken` che può utilizzare con i cmdlet che richiedono autorizzazione. Ad esempio, il cmdlet `Connect-AzureAd` accetta un token di accesso. {% code collapsedlinecount="10" %} ```powershell Connect-AzureAD [-AzureEnvironmentName ] [-TenantId ] -AadAccessToken [-MsAccessToken ] -AccountId [-LogLevel ] [-LogFilePath ] [-InformationAction ] [-InformationVariable ] [-WhatIf] [-Confirm] [] ``` {% endcode %} ### Refresh token Può configurare Azure Active Directory e PowerShell Universal per fornire refresh token per richiedere nuovi token se il token di accesso scade. Per farlo, dovrà abilitare offline\_access nella registrazione dell'app. Durante la configurazione di PowerShell Universal, deve richiedere lo scope `offline_access`, impostare SaveTokens su true e utilizzare il tipo di risposta id\_token. {% code collapsedlinecount="10" %} ```json "OIDC": { "Enabled": "true", "CallbackPath": "/auth/signin-oidc", "ClientID": "----", "ClientSecret": "---", "Resource": "https://graph.microsoft.com", "Authority": "https://login.microsoftonline.com/----", "ResponseType": "code id_token", "SaveTokens": "true", "CorrelationCookieSameSite": "", "UseTokenLifetime": true, "Scope": "openid profile groups offline_access", "GetUserInfo": false }, ``` {% endcode %} Una volta configurato, può accedere alla variabile `$RefreshToken` nei suoi script e nelle sue app. ## Configurazione di Okta Okta supporta OpenID Connect. Può configurare un'applicazione per consentire l'autenticazione verso istanze di PowerShell Universal. Nella console di amministrazione di Okta, espanda Applications e clicchi su Applications. Quindi clicchi su Create App Integration. Selezioni OIDC e Web Application. Assegni un nome all'applicazione e definisca il Sign-In redirect URL utilizzato per chiamare il suo server PowerShell Universal. Dovrà specificare questo URL di callback nella configurazione di PowerShell Universal. Una volta creata l'applicazione, prenda nota del Client ID e del Client Secret. Li specificherà nella configurazione di PowerShell Universal. Nella scheda Sign On, specifichi il filtro dei group claim da utilizzare per fornire i claim a PowerShell Universal. Questi claim possono essere utilizzati per assegnare ruoli in base all'appartenenza ai gruppi: `groups` / regex `.*`. Una volta configurata la sua applicazione, può configurare PowerShell Universal. ### Configurazione di Universal per Okta Dopo aver definito la sua applicazione Okta, può impostare il file `appsettings.json` per utilizzare il provider per gli accessi. Di seguito è riportato un esempio della sezione necessaria per il funzionamento di Okta. Presti attenzione alla funzionalità scope, poiché è necessaria per recuperare l'appartenenza ai gruppi. {% code collapsedlinecount="10" %} ```json "OIDC": { "Enabled": "true", "CallbackPath": "/authorization-code/callback", "ClientID": "6f006906-643a-40fe-af00-9060cea5d6ef", "ClientSecret": "M~.rE56.md_MOpB2I5kwj_voFuX-i891N0", "Resource": "", "Authority": "https://poshtools.okta.com", "ResponseType": "code", "SaveTokens": "true", "CorrelationCookieSameSite": "", "UseTokenLifetime": true, "Scope": "openid profile groups", "GetUserInfo": true }, ``` {% endcode %} ### Accesso basato sui ruoli Per verificare l'appartenenza ai gruppi per Okta, dovrà utilizzare la variabile `$UserInfo` disponibile in `roles.ps1`. Questa variabile fornisce informazioni aggiuntive sull'utente che effettua l'accesso. La proprietà groups conterrà un elenco dei gruppi di cui l'utente è membro. Può convalidare l'appartenenza verificando se l'elenco contiene il gruppo desiderato. {% code collapsedlinecount="10" %} ```powershell param($User) $UserInfo.groups -contains 'Administrators' ``` {% endcode %} ### Token di accesso delegati I token di accesso sono disponibili per gli utenti all'interno dei loro script. Può utilizzare i token di accesso nei job avviati dagli utenti e nelle dashboard. Ad esempio, potrebbe restituire le informazioni dell'utente corrente utilizzando il token di accesso fornito da Okta. {% code collapsedlinecount="10" %} ```powershell Invoke-RestMethod https://poshtools.okta.com/oauth2/v1/userinfo -Headers @{ Authorization = "Bearer $AccessToken" } ``` {% endcode %} ## Visualizzazione delle informazioni sui claim Se non è sicuro di quali informazioni sui claim vengono inviate a PowerShell Universal dal suo provider di identità, può utilizzare il pulsante View Claim Information nella pagina Secure > Roles per visualizzare tutti i ruoli che sono stati forniti a PSU dal sistema remoto. --- # 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/enterprise-security/openid-connect.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.