> 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/saml2.md). # SAML2 Configura l'autenticazione SAML2 in PowerShell Universal con provider di identità come Entra ID, Okta e Shibboleth, inclusi metadati e mappatura delle attestazioni. {% hint style="info" %} SAML2 richiede una [licenza](https://store.devolutions.net/package#psu). {% endhint %} PowerShell Universal può essere configurato per integrarsi con un provider di identità SAML2. Questa documentazione fornisce i dettagli per configurare PSU con un sistema di questo tipo. ## Caricamento automatico dei metadati PowerShell Universal offre un meccanismo per caricare il documento dei metadati direttamente dal provider di identità SAML2 anziché fornire manualmente le opzioni di configurazione. Questo raccoglierà il maggior numero possibile di informazioni. Sarà comunque necessario fornire l'Entity ID. Il percorso di callback verrà visualizzato nella parte superiore della finestra modale della proprietà. ## Fornire manualmente i valori ### Impostazioni del provider di identità Sarà necessario configurare il provider di identità per l'applicazione PowerShell Universal. Sarà necessario impostare un entity ID accettabile e mappare gli attributi. PowerShell Universal richiede che l'attributo name sia mappato. Il nome dell'attributo deve essere il seguente. {% code collapsedlinecount="10" %} ``` http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name ``` {% endcode %} Dovrebbe mapparlo all'identità utente che desidera utilizzare all'interno di PowerShell Universal. È possibile mappare attributi aggiuntivi, che saranno disponibili durante la [valutazione dei ruoli](/powershell-universal/it/sicurezza/security.md#authorization). Di seguito trova un esempio di configurazione di Shibboleth. ### Impostazioni dell'Entity ID {% hint style="info" %} [HTTPS ](/powershell-universal/it/config/hosting.md#configuring-https)è richiesto per l'autenticazione SAML2. {% endhint %} Sono disponibili diverse impostazioni di base configurabili nella console di amministrazione di PowerShell Universal. Per aggiungere il supporto SAML2, faccia clic su Secure > Autenticazione. Nell'angolo in alto a destra, può selezionare SAML2 dal menu a discesa. Una volta aggiunta l'integrazione SAML2, può configurare le impostazioni di base per la comunicazione con il suo provider di identità. Sarà necessario configurare almeno l'Entity ID e l'Identity Provider Entity ID. In genere, questi entity ID sono URL configurati all'interno del provider di identità. Il certificato del servizio viene utilizzato per firmare le richieste. Non è obbligatorio. Può essere un percorso locale al servizio PSU oppure il nome distinto (distinguished name) di un certificato installato nell'archivio certificati Personal del computer. ### Impostazioni aggiuntive Oltre alle impostazioni disponibili nella console di amministrazione, può anche impostare le seguenti nel file di configurazione `authentication.ps1`. #### ServiceCertificatePassword Se utilizza un percorso file per il certificato e questo richiede una password, può specificarla tramite il parametro `-ServiceCertificatePassword` di `Set-PSUAuthenticationMethod`. Il valore di questo parametro è una `SecureString`. Può sfruttare il modulo SecretManagement per caricare i segreti. {% code collapsedlinecount="10" %} ```powershell Set-PSUAuthenticationMethod ` -Type "Saml2" ` -EntityId "http://psu.ironman.local/sp" ` -IdentityProviderEntityId 'https://ironman.local/idp' ` -MetadataAddress 'https://idp.ironman.local/idp/shibboleth' ` -CallbackPath "https://localhost:5000/" ` -ServiceCertificate cert.pfx ` -ServiceCertificatePassword (Get-Secret -Name 'certPassword') ``` {% endcode %} #### Configure Il parametro `-Configure` è un blocco di script che può essere utilizzato per impostare opzioni aggiuntive non esposte da `Set-PSUAuthenticationMethod`. Il blocco di script verrà richiamato durante la configurazione del provider e riceverà un singolo parametro che contiene un oggetto con le opzioni per l'autenticazione SAML2. L'oggetto è di tipo [Saml2Options](https://github.com/Sustainsys/Saml2/blob/v2.11.0/Sustainsys.Saml2.AspNetCore2/Saml2Options.cs). Il sotto-oggetto di SPOptions è disponibile [qui](https://github.com/Sustainsys/Saml2/blob/v2.11.0/Sustainsys.Saml2/Configuration/SPOptions.cs). {% code collapsedlinecount="10" %} ```powershell Set-PSUAuthenticationMethod ` -Type "Saml2" ` -EntityId "http://psu.ironman.local/sp" ` -IdentityProviderEntityId 'https://ironman.local/idp' ` -MetadataAddress 'https://idp.ironman.local/idp/shibboleth' ` -Configure { $options = $args[0] $options.SPOptions.DiscoveryServiceUrl = 'https://idp.ironman.local/discovery' } ``` {% endcode %} ## Esempio: Entra ID Configuri un'Enterprise Application di Entra ID all'interno di Azure. Trova una [guida passo passo qui](/powershell-universal/it/sicurezza/enterprise-security/openid-connect.md#configuring-azure-entra-id-azure-active-directory). Dovrà recuperare l'ID applicazione e il documento di metadati di federazione, oltre all'endpoint di accesso SAML-P. All'interno della registrazione dell'applicazione, faccia clic sul pulsante Endpoints. ### Passo dopo passo **All'interno di PowerShell Universal:** 1. Faccia clic su Secure > Autenticazione. 2. Aggiunga il provider di autenticazione SAML2. 3. Faccia clic sul pulsante Edit Properties. Per l'Entity ID, dovrà inserire l'ID applicazione di Entra ID preceduto dal prefisso `spn:` Per esempio: `spn:2cf33625-e312-4659-a7bd-66ade51a0ea2` Per l'Identity Provider Entity ID, dovrà recuperare l'entity ID dal documento di metadati di federazione. Apra l'URL del documento in un browser web. Per Metadata Address, inserisca l'URL del documento di metadati di federazione. Per il Return URL, inserisca l'URL del suo server PowerShell Universal con il percorso `/Saml/Acs`. {% code collapsedlinecount="10" %} ``` https://localhost/Saml2/Acs ``` {% endcode %} Per Single Sign-On Service URL, inserisca l'endpoint di accesso SAML-P di Azure. Al termine, salvi le impostazioni e abiliti il provider SAML. Faccia clic su Sign out e vada all'URL della sua console di amministrazione. {% code collapsedlinecount="10" %} ``` https://localhost/admin ``` {% endcode %} Verrà inoltrato ad Azure per l'accesso e reindirizzato a PowerShell Universal dopo l'autenticazione. Eventuali errori verranno elencati nel log di PowerShell Universal. Se l'accesso non riesce, può andare a `/login` per accedere con un account locale. ### Mappatura delle attestazioni Per fornire le attestazioni dei gruppi a PowerShell Universal, dovrà esporre le attestazioni dei gruppi dalla registrazione dell'app. Faccia clic su Token Configuration e poi su Add groups claim. Dopo aver fatto clic su Add groups claim, avrà la possibilità di selezionare quali gruppi vengono forniti. Se seleziona All Groups, le attestazioni dei gruppi verranno fornite 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 faccia clic su User and Groups. Successivamente, faccia clic su Add User\Group e selezioni i gruppi che desidera assegnare all'applicazione. Una volta configurata l'attestazione dei gruppi in Entra ID, può aggiornare le mappature delle attestazioni di PowerShell Universal ai gruppi forniti. Per ogni ruolo che desidera assegnare a un gruppo di Entra ID, specifichi il Claim Type e il Claim Value per quel ruolo. Per 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 administrator, procederei come segue. Gli utenti di questo gruppo farebbero ora parte del ruolo Administrator in PowerShell Universal. Se ha selezionato una proprietà di gruppo SAML diversa, il valore potrebbe essere differente (ad esempio sAMAccountName). ### Eccedenze di gruppi Per le organizzazioni con molti gruppi, è consigliabile limitare il numero di gruppi forniti a PowerShell Universal. Questo può alleviare i problemi di autorizzazione derivanti dalla presenza di troppi gruppi forniti, che causano il superamento dei limiti all'interno dell'applicazione. All'interno delle impostazioni dell'Enterprise application, faccia clic su Single sign-on e poi sul pulsante Edit sotto Attributes & Claims. Faccia clic sull'attestazione dei gruppi per visualizzare le opzioni. Le opzioni avanzate consentono di filtrare i gruppi forniti al server PowerShell Universal. Può anche configurare le attestazioni dei gruppi tramite la configurazione dei token nella registrazione dell'applicazione per l'Enterprise Application. ## Esempio: Okta Questo esempio mostra come configurare l'autenticazione SAML2 di Okta da utilizzare con PowerShell Universal. In Okta, dovrà configurare la sua applicazione in modo simile a quanto segue. HTTPS è richiesto da SAML2 e dovrà includere l'URL della sua istanza PSU in Single Sign On URL, seguito da `/Saml2/Acs`. Il percorso è sensibile alle maiuscole e minuscole. L'Audience Restriction deve essere l'URL del suo server PowerShell Universal. Affinché i suoi utenti possano accedere a PowerShell Universal, dovrà assicurarsi che siano stati assegnati all'applicazione Okta. Nella scheda Sign On della sua applicazione, faccia clic sul pulsante View SAML setup instructions. Dovrà acquisire i due URL e scaricare il certificato per configurare PowerShell Universal. Consulti il passo successivo per sapere come utilizzare questi URL all'interno del file `authentication.ps1`. ### authentication.ps1 Il file authentication.ps1 viene utilizzato per configurare PowerShell Universal. {% code collapsedlinecount="10" %} ```powershell Set-PSUAuthenticationMethod -Type "Saml2" ` -EntityId "https://localhost:5001" ` -IdentityProviderEntityId "http://www.okta.com/exk5dvbyzgASPiOFp5d7" ` -CallbackPath "https://localhost:5001" ` -SigningKey "C:\Users\adamr\Downloads\okta.cert" ` -SingleSignOnServiceUrl "https://dev-36706648.okta.com/app/dev-36706648_psusaml_1/exk5dvbyzgASPiOFp5d7/sso/saml" ``` {% endcode %} | Parametro | Descrizione | Tipo | | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | ------ | | EntityId | Questo valore deve corrispondere a quanto inserito in Audience Restriction all'interno di Okta. | string | | IdentityProviderEntityId | Questo è il valore presentato nella pagina View SAML setup instructions. | string | | CallbackPath | Questo è il percorso al quale l'utente verrà reindirizzato se non è stato fornito alcun percorso di reindirizzamento | string | | SigningKey | Questo è il file di certificato scaricato dalla pagina View SAML setup instructions. | string | | SingleSignOnServiceUrl | Questo è l'URL di accesso fornito nella pagina View SAML setup instructions. | string | ## Esempio: Shibboleth Questo esempio mostra come configurare Shibboleth da utilizzare con PowerShell Universal. Fornisce la configurazione di base e non segue necessariamente le best practice. Si presuppone che abbia installato Shibboleth Identity Provider v4 con l'integrazione di Active Directory. ### ldap.properties Le proprietà LDAP sono state configurate per l'autenticazione nel dominio locale utilizzando un account di amministratore di dominio. L'URL LDAP è stato configurato e TLS è stato disabilitato. Di seguito trova l'esempio completo del file `ldap.properties`. {% code collapsedlinecount="10" %} ``` # LDAP authentication (and possibly attribute resolver) configuration # Note, this doesn't apply to the use of JAAS authentication via LDAP ## Authenticator strategy, either anonSearchAuthenticator, bindSearchAuthenticator, directAuthenticator, adAuthenticator idp.authn.LDAP.authenticator=adAuthenticator ## Connection properties ## idp.authn.LDAP.ldapURL=ldap://ironman.local:389 idp.authn.LDAP.useStartTLS = false # Time in milliseconds that connects will block #idp.authn.LDAP.connectTimeout = PT3S # Time in milliseconds to wait for responses #idp.authn.LDAP.responseTimeout = PT3S # Connection strategy to use when multiple URLs are supplied, either ACTIVE_PASSIVE, ROUND_ROBIN, RANDOM #idp.authn.LDAP.connectionStrategy = ACTIVE_PASSIVE ## SSL configuration, either jvmTrust, certificateTrust, or keyStoreTrust idp.authn.LDAP.sslConfig = jvmTrust ## If using certificateTrust above, set to the trusted certificate's path idp.authn.LDAP.trustCertificates=%{idp.home}/credentials/ldap-server.crt ## If using keyStoreTrust above, set to the truststore path idp.authn.LDAP.trustStore=%{idp.home}/credentials/ldap-server.truststore ## Return attributes during authentication idp.authn.LDAP.returnAttributes=passwordExpirationTime,loginGraceRemaining,sn,mail ## DN resolution properties ## # Search DN resolution, used by anonSearchAuthenticator, bindSearchAuthenticator # for AD: CN=Users,DC=example,DC=org idp.authn.LDAP.baseDN=CN=Users,DC=ironman, DC=local idp.authn.LDAP.subtreeSearch = true idp.authn.LDAP.userFilter=(sAMAccountName={user}) # bind search configuration # for AD: idp.authn.LDAP.bindDN=adminuser@domain.com idp.authn.LDAP.bindDN=administrator@ironman.local # Format DN resolution, used by directAuthenticator, adAuthenticator # for AD use idp.authn.LDAP.dnFormat=%s@domain.com idp.authn.LDAP.dnFormat=%s@ironman.local # pool passivator, either none, bind or anonymousBind #idp.authn.LDAP.bindPoolPassivator = none # LDAP attribute configuration, see attribute-resolver.xml # Note, this likely won't apply to the use of legacy V2 resolver configurations idp.attribute.resolver.LDAP.ldapURL=%{idp.authn.LDAP.ldapURL} idp.attribute.resolver.LDAP.connectTimeout=%{idp.authn.LDAP.connectTimeout:PT3S} idp.attribute.resolver.LDAP.responseTimeout=%{idp.authn.LDAP.responseTimeout:PT3S} idp.attribute.resolver.LDAP.connectionStrategy=%{idp.authn.LDAP.connectionStrategy:ACTIVE_PASSIVE} idp.attribute.resolver.LDAP.baseDN=%{idp.authn.LDAP.baseDN:undefined} idp.attribute.resolver.LDAP.bindDN=%{idp.authn.LDAP.bindDN:undefined} idp.attribute.resolver.LDAP.useStartTLS=%{idp.authn.LDAP.useStartTLS:true} idp.attribute.resolver.LDAP.trustCertificates=%{idp.authn.LDAP.trustCertificates:undefined} idp.attribute.resolver.LDAP.searchFilter=(sAMAccountName=$resolutionContext.principal) # LDAP pool configuration, used for both authn and DN resolution #idp.pool.LDAP.minSize = 3 #idp.pool.LDAP.maxSize = 10 #idp.pool.LDAP.validateOnCheckout = false #idp.pool.LDAP.validatePeriodically = true #idp.pool.LDAP.validatePeriod = PT5M #idp.pool.LDAP.validateDN = #idp.pool.LDAP.validateFilter = (objectClass=*) #idp.pool.LDAP.prunePeriod = PT5M #idp.pool.LDAP.idleTime = PT10M #idp.pool.LDAP.blockWaitTime = PT3S ``` {% endcode %} ### relying-party.xml Il file `relying-party.xml` è stato aggiornato per abilitare l'IdP aperto. Ciò significa che qualsiasi entity ID può comunicare con il provider di identità. Può anche configurarlo per applicare entity ID specifici. Anche la configurazione predefinita è stata modificata per utilizzare il bean `SAML2.AttributeQuery`. {% code collapsedlinecount="10" %} ``` ``` {% endcode %} ### attribute-resolver.xml Il file `attribute-resolver.xml` è stato aggiornato per utilizzare il Data Connector LDAPDirectory. Carica l'indirizzo email, il nome, l'SN e il nome visualizzato da Active Directory. Quindi mappa il Principal Name, che sarà il nome utente dell'utente che effettua l'accesso, al tipo di attestazione richiesto utilizzando un encoder di attributi. {% code collapsedlinecount="10" %} ``` ``` {% endcode %} ### attribute-filter.xml Il file `attribute-filter.xml` è stato aggiornato per rilasciare diversi attributi mappati dal data connector LDAPDirectory, nonché il nome utente che verrà utilizzato come identità all'interno di PowerShell Universal. {% code collapsedlinecount="10" %} ``` ``` {% endcode %} --- # 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/saml2.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.