SAML2

SAML2 richiede una licenza.

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 fornisce un meccanismo per caricare il documento dei metadati direttamente dal provider di identità SAML2 anziché fornire manualmente le opzioni di configurazione. Questo raccoglierà quante più informazioni possibili. Sarà comunque necessario fornire l'Entity ID.

Il percorso di callback verrà visualizzato nella parte superiore della finestra modale della proprietà.

Caricamento dei metadati

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.

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name

Dovrebbe mapparlo all'identità utente che desidera venga utilizzata all'interno di PowerShell Universal.

È possibile mappare attributi aggiuntivi che saranno disponibili durante la valutazione dei ruoli. Di seguito troverà un esempio di configurazione di Shibboleth.

Impostazioni dell'Entity ID

HTTPS è richiesto per l'autenticazione SAML2.

Sono disponibili diverse impostazioni di base che può configurare nella console di amministrazione di PowerShell Universal. Per aggiungere il supporto SAML2, faccia clic su Security \ Authentication. 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 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à.

Proprietà SAML2

Il certificato del servizio viene utilizzato per firmare le richieste. Non è obbligatorio. Può essere un percorso locale al servizio PSU oppure il nome distinto di un certificato installato nell'archivio certificati Personal Computer.

Impostazioni aggiuntive

Oltre alle impostazioni disponibili nella console di amministrazione, può anche impostare quanto segue 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.

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')

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à chiamato quando il provider viene configurato e riceverà un singolo parametro che contiene un oggetto con le opzioni per l'autenticazione SAML2.

L'oggetto è di tipo Saml2Options. Il sotto-oggetto di SPOptions si trova qui.

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'
}

Esempio: Entra ID

Configuri un'applicazione aziendale Entra ID all'interno di Azure. Può trovare una guida dettagliata qui. Sarà necessario recuperare l'ID applicazione e il documento dei metadati di federazione, nonché l'endpoint di accesso SAML-P. All'interno della registrazione dell'applicazione, faccia clic sul pulsante Endpoints.

Passo dopo passo

In PowerShell Universal:

1. Faccia clic su Security \ Authentication.
2. Aggiunga il provider di autenticazione SAML2.
3. Faccia clic sul pulsante Edit Properties.

Per Entity ID, dovrà inserire l'ID applicazione di Entra ID preceduto dal prefisso spn:

Ad esempio: spn:2cf33625-e312-4659-a7bd-66ade51a0ea2

Per Identity Provider Entity ID, dovrà recuperare l'entity ID dal documento dei metadati di federazione. Apra l'URL del documento in un browser web.

Per Metadata Address, inserisca l'URL del documento dei metadati di federazione.

Per il Return URL, inserisca l'URL del suo server PowerShell Universal con il percorso /Saml/Acs.

https://localhost/Saml2/Acs

Per Single Sign-On Service URL, inserisca l'endpoint di accesso SAML-P di Azure.

Configurazione di PSU

Una volta completato, salvi le impostazioni e abiliti il provider SAML. Faccia clic su Sign out e navighi all'URL della console di amministrazione.

https://localhost/admin

Verrà inoltrato ad Azure per l'accesso e reindirizzato nuovamente a PowerShell Universal dopo l'autenticazione.

Eventuali errori che si verificano verranno elencati nel log di PowerShell Universal. Se non riesce ad accedere, può navigare a /login per accedere con un account locale.

Mappatura dei claim

Per fornire i claim di gruppo a PowerShell Universal, sarà necessario esporre i claim di gruppo dalla registrazione dell'applicazione. Faccia clic su Token Configuration e poi su Add groups claim.

Claim di gruppo di Entra ID

Dopo aver fatto clic su Add groups claim, avrà la possibilità di selezionare quali gruppi vengono forniti. Se seleziona All Groups, i claim di gruppo 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.

Impostazione Emit groups as role claims

Per assegnare un gruppo alla registrazione dell'applicazione, individui l'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 configurato il claim di gruppo in Entra ID, può aggiornare le mappature dei claim di PowerShell Universal con i 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 è http://schemas.microsoft.com/ws/2008/06/identity/claims/role.

Per assegnarlo al gruppo di amministratori, procederei come segue.

Mappatura dei claim

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 es. sAMAccountName).

Eccedenze di gruppi

Per le organizzazioni con molti gruppi, sarà opportuno limitare il numero di gruppi forniti a PowerShell Universal. Ciò può alleviare i problemi di autorizzazione derivanti dalla presenza di troppi gruppi forniti, che causano il superamento dei limiti all'interno dell'applicazione. Nelle impostazioni dell'applicazione aziendale, faccia clic su Single sign-on e poi sul pulsante Edit sotto Attributes & Claims.

Faccia clic sul claim dei gruppi per visualizzare le opzioni. Le opzioni avanzate le consentiranno di filtrare i gruppi forniti al server PowerShell Universal. Può anche configurare i claim di gruppo tramite la configurazione del token nella registrazione dell'applicazione per l'applicazione aziendale.

Esempio: Okta

Questo esempio mostra come configurare l'autenticazione SAML2 di Okta per l'uso con PowerShell Universal.

All'interno di Okta, dovrà configurare l'applicazione in modo simile al seguente. SAML2 richiede HTTPS e dovrà includere l'URL della sua istanza di PSU nel Single Sign On URL, seguito da /Saml2/Acs. Il percorso distingue tra maiuscole e minuscole.

L'Audience Restriction deve essere l'URL del suo server PowerShell Universal.

Affinché gli utenti possano accedere a PowerShell Universal, dovrà assicurarsi che siano stati assegnati all'applicazione Okta.

Nella scheda Sign On dell'applicazione, faccia clic sul pulsante View SAML setup instructions.

Dovrà acquisire i due URL e scaricare il certificato per configurare PowerShell Universal. Veda il passo successivo su come utilizzare questi URL nel file authentication.ps1.

authentication.ps1

Il file authentication.ps1 viene utilizzato per configurare PowerShell Universal.

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"

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 a cui l'utente verrà reindirizzato se non è stato fornito alcun percorso di reindirizzamento	string
SigningKey	Questo è il file del certificato scaricato nella 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 per l'uso con PowerShell Universal. Fornisce la configurazione di base e non segue necessariamente le migliori pratiche.

Si presuppone che abbia installato Shibboleth Identity Provider v4 con integrazione Active Directory.

ldap.properties

Le proprietà LDAP sono state configurate per l'autenticazione sul dominio locale utilizzando un account di amministratore di dominio. L'URL LDAP è stato configurato e TLS è stato disabilitato.

Di seguito troverà l'esempio completo del file ldap.properties.

# 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=[e-mail]
idp.authn.LDAP.bindDN=[e-mail]

# Format DN resolution, used by directAuthenticator, adAuthenticator
# for AD use idp.authn.LDAP.dnFormat=[e-mail]
idp.authn.LDAP.dnFormat=[e-mail]

# 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

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à. È anche possibile configurarlo per applicare entity ID specifici. Anche la configurazione predefinita è stata modificata per utilizzare il bean SAML2.AttributeQuery.

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:context="http://www.springframework.org/schema/context"
       xmlns:util="http://www.springframework.org/schema/util"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:c="http://www.springframework.org/schema/c"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
                           http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context.xsd
                           http://www.springframework.org/schema/util http://www.springframework.org/schema/util/spring-util.xsd"
                           
       default-init-method="initialize"
       default-destroy-method="destroy">

    <!--
    Unverified RP configuration, defaults to no support for any profiles. Add <ref> elements to the list
    to enable specific default profile settings (as below), or create new beans inline to override defaults.
    
    "Unverified" typically means the IdP has no metadata, or equivalent way of assuring the identity and
    legitimacy of a requesting system. To run an "open" IdP, you can enable profiles here.
    -->
    <bean id="shibboleth.UnverifiedRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
			<bean parent="SAML2.SSO" p:encryptAssertions="false" />
            </list>
        </property>
    </bean>

    <!-- Default configuration, with default settings applied for all profiles. -->
    <bean id="shibboleth.DefaultRelyingParty" parent="RelyingParty">
        <property name="profileConfigurations">
            <list>
                <!-- SAML 1.1 and SAML 2.0 AttributeQuery are disabled by default. -->
                <!--
                <bean parent="Shibboleth.SSO" />
                <ref bean="SAML1.AttributeQuery" />
                <ref bean="SAML1.ArtifactResolution" />
                -->
                <bean parent="SAML2.SSO" />
                <ref bean="SAML2.ECP" />
                <ref bean="SAML2.Logout" />
                <ref bean="SAML2.AttributeQuery" />
                <ref bean="SAML2.ArtifactResolution" />
                <ref bean="Liberty.SSOS" />
            </list>
        </property>
    </bean>
</beans>

attribute-resolver.xml

Il file attribute-resolver.xml è stato aggiornato per utilizzare il Data Connector LDAPDirectory. Carica l'indirizzo e-mail, il nome, il cognome (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 claim richiesto utilizzando un codificatore di attributi.

<?xml version="1.0" encoding="UTF-8"?>
<!--
    This file is an EXAMPLE configuration file containing some example attributes
    based on some commonly used approaches when LDAP is the principal data source.
     
    Not all attribute definitions or data connectors are demonstrated, but some
    LDAP attributes common to Shibboleth deployments (and some not so common) are
    included.

    This example is in no way usable as a substitute for reading the documentation.    
-->
<AttributeResolver
        xmlns="urn:mace:shibboleth:2.0:resolver"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:resolver http://shibboleth.net/schema/idp/shibboleth-attribute-resolver.xsd">

    <!-- ========================================== -->
    <!--      Attribute Definitions                 -->
    <!-- ========================================== -->

    <!-- Simple attributes are exported directly from the LDAP connector. -->

    <AttributeDefinition id="uid" xsi:type="PrincipalName" />
    <AttributeDefinition id="username" xsi:type="PrincipalName">
         <AttributeEncoder xsi:type="SAML2String" name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" friendlyName="displayName" encodeType="false" />
    </AttributeDefinition>

    <!-- ========================================== -->
    <!--      Data Connectors                       -->
    <!-- ========================================== -->

    <!-- Example LDAP Connector -->

    <DataConnector id="myLDAP" xsi:type="LDAPDirectory"
        ldapURL="%{idp.attribute.resolver.LDAP.ldapURL}"
        baseDN="%{idp.attribute.resolver.LDAP.baseDN}" 
        principal="%{idp.attribute.resolver.LDAP.bindDN}"
        principalCredential="%{idp.attribute.resolver.LDAP.bindDNCredential}"
        useStartTLS="%{idp.attribute.resolver.LDAP.useStartTLS:true}"
        connectTimeout="%{idp.attribute.resolver.LDAP.connectTimeout}"
        responseTimeout="%{idp.attribute.resolver.LDAP.responseTimeout}"
        connectionStrategy="%{idp.attribute.resolver.LDAP.connectionStrategy}"
        noResultIsError="true"
        multipleResultsIsError="true"
        excludeResolutionPhases="c14n/attribute"
        exportAttributes="mail displayName sn givenName">
        <FilterTemplate>
            <![CDATA[
                %{idp.attribute.resolver.LDAP.searchFilter}
            ]]>
        </FilterTemplate>
        <ConnectionPool
            minPoolSize="%{idp.pool.LDAP.minSize:3}"
            maxPoolSize="%{idp.pool.LDAP.maxSize:10}"
            blockWaitTime="%{idp.pool.LDAP.blockWaitTime:PT3S}"
            validatePeriodically="%{idp.pool.LDAP.validatePeriodically:true}"
            validateTimerPeriod="%{idp.pool.LDAP.validatePeriod:PT5M}"
            validateDN="%{idp.pool.LDAP.validateDN:}"
            validateFilter="%{idp.pool.LDAP.validateFilter:(objectClass=*)}"
            expirationTime="%{idp.pool.LDAP.idleTime:PT10M}"/>
    </DataConnector>

</AttributeResolver>

attribute-filter.xml

Il file attribute-filter.xml è stato aggiornato per rilasciare diversi degli attributi mappati dal data connector LDAPDirectory, nonché il nome utente che verrà utilizzato come identità all'interno di PowerShell Universal.

<?xml version="1.0" encoding="UTF-8"?>
<!-- 
    This file is an EXAMPLE policy file.  While the policy presented in this 
    example file is illustrative of some simple cases, it relies on the names of
    non-existent example services and the example attributes demonstrated in the
    default attribute-resolver.xml file.

    This example does contain some usable "general purpose" policies that may be
    useful in conjunction with specific deployment choices, but those policies may
    not be applicable to your specific needs or constraints.    
-->
<AttributeFilterPolicyGroup id="ShibbolethFilterPolicy"
        xmlns="urn:mace:shibboleth:2.0:afp"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="urn:mace:shibboleth:2.0:afp http://shibboleth.net/schema/idp/shibboleth-afp.xsd">

<AttributeFilterPolicy id="example1">
        <PolicyRequirementRule xsi:type="ANY" />
        <AttributeRule attributeID="username">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="displayName">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="uid">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="mail">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
        <AttributeRule attributeID="sn">
            <PermitValueRule xsi:type="ANY" />
        </AttributeRule>
    </AttributeFilterPolicy>
 


</AttributeFilterPolicyGroup>