> 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/authorization.md). # Autorizzazione Configuri l'autorizzazione basata sui ruoli in PowerShell Universal utilizzando la mappatura dei claim, gli script di criteri e i ruoli predefiniti per controllare l'accesso alla piattaforma. L'autorizzazione degli utenti si realizza tramite i ruoli. I ruoli possono essere assegnati tramite la mappatura dei claim, uno script di criteri o assegnando il ruolo direttamente all'identità. {% hint style="info" %} Per impostazione predefinita, nessun ruolo viene assegnato automaticamente. Durante la configurazione iniziale viene creato un account amministratore locale, utilizzato per configurare le assegnazioni dei ruoli. {% endhint %} ### Mappatura dei ruoli ai claim È possibile mappare i ruoli a un claim (ad esempio l'appartenenza a un gruppo) utilizzando i parametri `-ClaimType` e `-ClaimValue` di `New-PSURole`. Le impostazioni sono disponibili anche nella finestra di dialogo delle proprietà del ruolo in **Secure > Roles**. Ad esempio, con l'autenticazione Windows, se volesse mappare un gruppo a un ruolo, potrebbe configurarlo in modo che il SID del gruppo venga mappato al ruolo di amministratore. ```powershell New-PSURole -Name Administrator -ClaimType 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid' -ClaimValue 'S-123-123-123' ``` Mappare i ruoli ai claim in questo modo è più rapido rispetto agli script di criteri, perché non richiede l'esecuzione di PowerShell quando l'utente effettua l'accesso. ### Visualizzare le informazioni sui claim Per facilitare lo sviluppo degli script di criteri o l'assegnazione dei ruoli ai claim, è possibile visualizzare le informazioni sui claim facendo clic su View Claim Information in **Secure > Roles**. ### Esempio: Azure Active Directory È possibile mappare un gruppo di Azure Active Directory a un ruolo cercando l'Object ID del gruppo in Azure. Ad esempio, all'interno del dominio Ironman Software abbiamo un gruppo chiamato Dashboard Administrators. Questo gruppo ha un object ID pari a `61849bf2-e44b-4057-b589-6cd1812d7545`. All'interno di PowerShell Universal, posso assegnare gli utenti di questo gruppo al gruppo Administrator configurando la mappatura dei claim. Il Claim Type sarà `groups` e il Claim Value sarà `61849bf2-e44b-4057-b589-6cd1812d7545`. Una volta mappato il claim, gli utenti del gruppo Dashboard Administrators faranno parte del gruppo Administrators di PowerShell Universal. Il file `roles.ps1` risultante avrà questo aspetto. Tutti gli altri ruoli sono disabilitati. ```powershell New-PSURole -Name Administrator -ClaimType 'groups' -ClaimValue '61849bf2-e44b-4057-b589-6cd1812d7545' New-PSURole -Name "Operator" -Description "Operators have access to manage and execute scripts, create other entities within PowerShell Universal but cannot manage PowerShell Universal itself." -Policy {} -Disabled New-PSURole -Name "Reader" -Description "Readers have read-only access to PowerShell Universal. They cannot make changes to any entity within the system." -Policy { } -Disabled New-PSURole -Name "Execute" -Description "Execute scripts within PowerShell Universal." -Policy { } -Disabled New-PSURole -Name "User" -Description "Does not have access to the admin console but can be assigned resources like APIs, scripts, dashboards and pages." -Policy { } -Disabled ``` ### Assegnazione tramite criteri Per impostazione predefinita, i ruoli vengono assegnati tramite criteri. I criteri vengono eseguiti quando l'utente effettua l'accesso. È possibile modificare gli script dei criteri visitando **Secure > Roles**. Faccia clic sul pulsante Edit Code per configurare lo script del criterio. Gli script dei criteri riceveranno un oggetto `ClaimsPrincipal` come parametro e devono restituire true o false. I criteri che generano errori verranno considerati false. L'oggetto `ClaimsPrincipal` contiene l'identità dell'utente e i claim che l'utente ha ricevuto. Questi possono includere le assegnazioni di gruppo o altre caratteristiche dell'account di un utente. Può aspettarsi un oggetto con questa struttura. ```csharp public class ClaimsPrincipal { public List Claims { get; set; } = new List(); public Identity Identity { get; set; } = new Identity(); } public class Identity { public string Name { get ;set; } } public class Claim { public string Type { get; set; } public string Value { get; set; } public string ValueType { get; set; } public string Issuer { get; set; } public Dictionary Properties { get; set; } = new Dictionary(); } ``` ### Assegnazione dei ruoli Per assegnare un ruolo a un utente, è possibile creare la sua identità in Universal e quindi selezionare il ruolo nel menu a discesa in **Secure > Identities**. Per impostazione predefinita, le identità ricevono un ruolo tramite la mappatura dei claim o i criteri. ### Importare i ruoli Quando l'autenticazione Windows è abilitata, è possibile fare clic sul pulsante Import Windows Groups per selezionare i gruppi che desidera importare in PowerShell Universal. Dopo aver selezionato questi gruppi, i ruoli verranno creati con la mappatura dei ruoli ai claim, senza doverla configurare manualmente. ### Ruoli predefiniti #### Administrator Accesso completo a tutta la piattaforma PowerShell Universal e alle impostazioni. #### Operator Gli operatori possono aggiungere e rimuovere risorse come API, Script e Dashboard. Gli operatori non possono modificare impostazioni come gli ambienti, i ruoli o le impostazioni generali. #### Execute Il ruolo Execute concede la possibilità di eseguire script e l'accesso in lettura a tutto il resto. #### Reader Il ruolo Reader fornisce accesso in sola lettura a PowerShell Universal. ### Route predefinita per ruolo È possibile modificare la pagina che l'utente vede al momento dell'accesso impostando la proprietà `Default Route` per il ruolo. Ad esempio, potrebbe voler indirizzare gli utenti HR alla dashboard Human Resources e gli utenti IT alla dashboard IT. ### Utenti con molti gruppi Se i suoi utenti sono membri di più di circa 40 gruppi, potrebbe riscontrare problemi di accesso. Ciò è dovuto ai limiti di dimensione delle intestazioni HTTP in IIS e Kestrel. Più gruppi un utente ha, più claim di autorizzazione possiede e più grande diventa l'intestazione. È possibile aumentare il limite delle intestazioni per Kestrel utilizzando la configurazione dei limiti nel file `appsettings.json`. Dovrà aumentare la dimensione dell'intestazione. È un valore in byte e per impostazione predefinita è 32 kb. ``` { "Kestrel": { "Endpoints": { "HTTP": { "Url": "http://*:5000" } }, "Limits": { "MaxRequestHeadersTotalSize": 132768 }, "RedirectToHttps": "false" }, ``` ### Autorizzazione in IIS L'autorizzazione in IIS funziona come con qualsiasi altro metodo, ma è necessario tenere presente il limite di dimensione delle intestazioni delle richieste. Potrebbe ricevere errori quando abilita claim che includono molti gruppi. Possono superare il limite di dimensione dell'intestazione e IIS restituirà errori. Abbiamo constatato che circa 40 gruppi di Azure Active Directory causano questo problema in un'installazione IIS predefinita. L'errore che riceverà sarà un errore 400 con l'indicazione che la richiesta è troppo lunga. *Bad Request - Request Too Long* *HTTP Error 400. The size of the request headers is too long.* Se ha HTTPS abilitato, riceverà un errore relativo a un errore di protocollo HTTP2. È possibile aumentare la dimensione delle richieste di IIS impostando le seguenti chiavi di registro. Dovrà riavviare la macchina perché abbiano effetto. ``` HKLM:\System\CurrentControlSet\Services\Http\Parameters MaxFieldLength: DWORD HKLM:\System\CurrentControlSet\Services\Http\Parameters MaxRequestBytes: DWORD ``` Maggiori informazioni sono disponibili nella [documentazione di Microsoft](https://docs.microsoft.com/en-us/troubleshoot/iis/http-bad-request-response-kerberos#workaround-2-set-maxfieldlength-and-maxrequestbytes-registry-entries). Come alternativa all'aumento della dimensione delle richieste, è possibile anche ridurre il numero di gruppi inviati. In Azure Active Directory è possibile impostare solo i gruppi assegnati all'applicazione per evitare che vengano inviati tutti i gruppi. In Azure vada su **App registrations** > (selezioni l'app) > **Token Configuration** e specifichi i gruppi assegnati all'applicazione. Ora vada su **Enterprise Application** > (selezioni l'app) > **Users and groups**. Assegni il gruppo o i gruppi che desidera includere nei claim. (Nota: questo può essere utilizzato anche come limite di sicurezza se imposta “User Assignment Required” su Yes nella sezione ‘Properties’ dell'app) ## App Token Gli App Token possono essere assegnati a servizi che non possono effettuare l'accesso in modo interattivo. È possibile concedere un nuovo app token al proprio account facendo clic sul pulsante Grant App Token in **User menu > User Settings > Tokens**. Il token avrà una scadenza di un anno e includerà i ruoli validi per il suo account. Per copiare l'App Token nel suo account, faccia clic sull'azione Copy. Per revocare un App Token, faccia clic sull'azione Revoke. È possibile utilizzare gli App Token con i cmdlet di Universal oppure tramite richieste web dirette utilizzando \*\*\*\*\*\* src="" alt=""> Pagina App Token ## Ambiente Per impostazione predefinita, gli script di autenticazione tramite form e di assegnazione dei criteri vengono eseguiti all'interno del processo di PowerShell Universal. Quando configura un ambiente di sicurezza, verrà avviato un processo PowerShell esterno e configurato per utilizzare le impostazioni del suo ambiente. Per modificare l'ambiente utilizzato dal processo di sicurezza, imposti `-SecurityEnvironment` in `settings.ps1`. ```powershell Set-PSUSetting -SecurityEnvironment '5.1' ``` ## Esempio: autenticazione tramite form con Active Directory L'esempio seguente mostra l'esecuzione di un semplice "LDAP BIND" per convalidare le credenziali Active Directory di un utente. Se un utente che tenta di accedere a PowerShell Universal non è il Default Admin User, dovrà autenticare correttamente le proprie credenziali con Active Directory tramite un semplice bind LDAP. Questo può essere combinato con una verifica dell'appartenenza a un gruppo AD nei criteri dei ruoli Admin, Operator e Reader per utilizzare efficacemente l'autenticazione Active Directory E l'appartenenza ai gruppi di Active Directory al fine di fornire accesso basato sui ruoli a PowerShell Universal. ```powershell param( [PSCredential]$Credential ) # # You can call whatever cmdlets you like to conduct authentication here. # Just make sure to return the $Result with the Success property set to $true # $Result = [Security.AuthenticationResult]::new() if ($Credential.UserName -eq 'Admin') { #Maintain the out of box admin user $Result.UserName = 'Default Admin' $Result.Success = $true } else { # Get current domain using logged-on user's credentials - this validates their credential $CurrentDomain = "LDAP://DC=mydemodomain,DC=com" # Insert Your Domain Here $domain = New-Object System.DirectoryServices.DirectoryEntry($CurrentDomain,($Credential.UserName),$Credential.GetNetworkCredential().password) if ($domain.name -eq $null) { "Authentication failed for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt" write-host "Authentication failed - please verify your username and password." $Result.UserName = ($Credential.UserName) $Result.Success = $false } else { write-host "Successfully authenticated with domain $($domain.name)" "Authentication success for $($Credential.UserName)!" | Out-File "C:\test\adlogin.txt" $Result.UserName = ($Credential.UserName) $Result.Success = $true } } $Result ``` ## Esempio: criterio basato sull'appartenenza a un gruppo di Active Directory (autenticazione Windows) {% hint style="info" %} Questo esempio richiede un metodo di autenticazione che fornisca le informazioni sui gruppi durante il processo di autenticazione. Metodi come l'autenticazione Windows e WS-Federation possono fornire queste informazioni. L'autenticazione tramite form non funzionerà con questo tipo di criterio. {% endhint %} Questo esempio sfrutta i claim forniti durante l'autenticazione. È possibile verificare se l'utente possiede un groupsid (appartenenza a un gruppo) utilizzando le mappature dei claim. Mappi il tipo di claim groupid al valore a cui desidera assegnare il ruolo. ```powershell $Parameters = @{ Name = "Administrators" ClaimType = 'http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid' ClaimValue = 'S-1-5-21-22222222-111111-3333333-153' } New-PSURole @Parameters ``` ## Esempio: criterio basato sull'appartenenza a un gruppo di Active Directory In questo esempio configureremo lo script del criterio Administrator per utilizzare LDAP al fine di recuperare l'appartenenza a un gruppo di Active Directory. Qui abbiamo creato un gruppo chiamato "PowerShell Universal Admins", i cui membri devono ottenere l'accesso Administrator in PowerShell Universal. In questo caso eseguiamo un semplice controllo del samaccountname dell'utente per verificare che sia membro del gruppo. Per ambienti più robusti sarebbe più appropriato un controllo SID/DN/ObjectGUID. ```powershell param( $User ) $UserName = ($User.Identity.Name) $UserName = $UserName.Substring($UserName.IndexOf('\')+1,($UserName.Length -($UserName.IndexOf('\')+1))) $IsMember = $false; # Perform LDAP Group Member Lookup $Searcher = New-Object DirectoryServices.DirectorySearcher $Searcher.SearchRoot = 'LDAP://CN=Users,DC=berg,DC=com' # INSERT ROOT LDAP HERE $Searcher.Filter = "(&(objectCategory=person)(memberOf=CN=PowerShell Universal Admins,OU=Information Technology,DC=berg,DC=com))" #GROUP INSERT DN TO CHECK HERE $Users = $Searcher.FindAll() $Users | ForEach-Object{ If($_.Properties.samaccountname -eq $UserName) { $IsMember = $true; "$UserName is a member of admin group!" | Out-File "C:\test\adgroup.txt" } else { "$UserName is NOT member of admin group!" | Out-File "C:\test\adgroup.txt" } } return $IsMember ``` ## Esempio: appartenenza ai gruppi basata su Azure Active Directory Questo esempio sfrutta OpenID Connect e Azure Active Directory. Dopo aver configurato PowerShell Universal e Azure Active Directory, è possibile configurare gli script dei ruoli per verificare se gli utenti sono membri di gruppi presenti in Azure AD. È possibile sfruttare le mappature dei claim per mappare l'ID del gruppo di Azure AD a un ruolo di PowerShell Universal. Innanzitutto, si assicuri di aver abilitato i claim di appartenenza ai gruppi nel manifest della registrazione dell'applicazione. Questo includerà tutte le appartenenze ai gruppi, in modo che siano accessibili in PowerShell Universal. ``` "groupMembershipClaims": "All", ``` Una volta configurato, è possibile aggiornare lo script del ruolo per verificare l'appartenenza a un gruppo. Prima annoti l'object ID del gruppo che desidera verificare in Azure AD. Successivamente, nello script `roles.ps1`, è possibile convalidare che un utente possieda un determinato ruolo utilizzando la mappatura dei claim. ```powershell New-PSURole -Name 'Administrators' -ClaimType 'groups' -ClaimValue '4acabc67-56cc-4590-9de6-164f3c4faf10' ``` Quando gli utenti effettuano l'accesso, la loro appartenenza ai gruppi verrà convalidata rispetto ai loro claim e verrà assegnato un ruolo. ### Vedere anche * [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/authorization.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.