Autenticazione SAML 2.0

Scopri come configurare e autenticare gli utenti finali (non gli autori dell'AEM) in un IDP compatibile con SAML 2.0 di tua scelta.

L’integrazione di SAML 2.0 con AEM Publish (o Preview), consente agli utenti finali di un’esperienza Web basata su AEM di autenticarsi a un IDP (Identity Provider) non Adobe e di accedere all’AEM come utente autorizzato e designato.

Procedura dettagliata della configurazione

Questo video illustra come configurare l’integrazione SAML 2.0 con il servizio AEM as a Cloud Service Publish e utilizzare Okta come IDP.

Prerequisiti

Per configurare l’autenticazione SAML 2.0 sono necessari i seguenti elementi:

SAML 2.0 è supportato solo per autenticare gli utilizzi in AEM Publish o Preview. Per gestire l'autenticazione dell'autore dell'AEM tramite e IDP, integra l'IDP con Adobe IMS.

Supporto del servizio AEM as a Cloud Service Preview

SAML 2.0 è supportato su AEM come Cloud Service, inclusa AEM Preview. Tuttavia, le configurazioni SAML dell'AEM si basano sulle configurazioni OSGi e sia l'anteprima AEM che l'AEM Publish condividono la stessa risoluzione della modalità di esecuzione OSGi (config.publish). Di conseguenza, non è possibile creare file di configurazioni SAML separati per Preview e Publish.

Utilizza invece valori di configurazione specifici dell'ambiente nelle configurazioni OSGi e imposta i valori di variabile appropriati per gli ambienti di anteprima e pubblicazione.

Installare il certificato pubblico IDP su AEM

Il certificato pubblico dell'IDP viene aggiunto all'archivio fonti attendibili globale di AEM e utilizzato per convalidare la validità dell'asserzione SAML inviata dall'IDP.

L'archivio protetto globale è configurato con il certificato pubblico dell'IDP sull'autore dell'AEM, ma poiché SAML viene utilizzato solo su AEM Publish, l'archivio protetto globale deve essere replicato sull'AEM Publish affinché il certificato pubblico dell'IDP sia accessibile lì.

Crea keystore del servizio di autenticazione authentication-service-keystore

La creazione di un archivio chiavi per il servizio di autenticazione è necessaria quando la proprietà di configurazione OSGi ​ del gestore di autenticazione handleLogoutSAML 2.0 è impostata su true o quando è richiesta la firma AuthnRequest/la crittografia dell'asserzione SAML

Installa coppia di chiavi pubblica/privata AEM install-aem-public-private-key-pair

L'installazione della coppia di chiavi pubblica/privata di AEM è facoltativa

AEM Publish può essere configurato per firmare le richieste di authoring (a IDP) e crittografare le asserzioni SAML (ad AEM). Ciò si ottiene fornendo una chiave privata ad AEM Publish, che corrisponde alla chiave pubblica dell'IDP.

Sia la firma di AuthnRequest che la crittografia delle asserzioni SAML sono facoltative, tuttavia entrambe sono abilitate, utilizzando la proprietà di configurazione OSGi ​ del gestore di autenticazione useEncryptionSAML 2.0, che indica che è possibile utilizzare entrambe le proprietà o nessuna delle due.

Configurazione del gestore di autenticazione SAML 2.0 configure-saml-2-0-authentication-handler

La configurazione SAML AEM viene eseguita tramite la configurazione OSGi di Adobe Granite SAML 2.0 Authentication Handler.
La configurazione è una configurazione di fabbrica OSGi, il che significa che un singolo servizio di pubblicazione AEM as a Cloud Service può avere più strutture di risorse discrete di copertura della configurazione SAML dell’archivio; questo è utile per le distribuzioni AEM multisito.

Le configurazioni OSGi per ambiente (config.publish.dev, config.publish.stage e config.publish.prod) possono essere definite con attributi specifici se la configurazione SAML varia da un ambiente all'altro.

Usa crittografia

Quando si crittografano le asserzioni AuthnRequest e SAML, sono necessarie le seguenti proprietà: useEncryption, spPrivateKeyAlias e keyStorePassword. keyStorePassword contiene una password, pertanto il valore non deve essere archiviato nel file di configurazione OSGi, ma inserito utilizzando valori di configurazione segreti

Configura filtro Referrer

Durante il processo di autenticazione SAML, l'IDP avvia un HTTP POST lato client all'endpoint .../saml_login di AEM Publish. Se l'IDP e la pubblicazione AEM esistono in un'origine diversa, il filtro referrer di AEM Publish viene configurato tramite la configurazione OSGi per consentire i POST HTTP dall'origine dell'IDP.

AEM Publish supporta una singola configurazione del filtro Referrer, in modo da unire i requisiti di configurazione SAML con eventuali configurazioni esistenti.

Le configurazioni OSGi per ambiente (config.publish.dev, config.publish.stage e config.publish.prod) possono essere definite con attributi specifici se allow.hosts (o allow.hosts.regex) variano da un ambiente all'altro.

Configurare la condivisione CORS (Cross-Origin Resource Sharing)

Durante il processo di autenticazione SAML, l'IDP avvia un HTTP POST lato client all'endpoint .../saml_login di AEM Publish. Se l'IDP e il Publish AEM esistono su host/domini diversi, è necessario configurare CORS-Origin Resource Sharing (CORS) di AEM Publish per consentire POST HTTP dall'host/dominio dell'IDP.

L'intestazione Origin di questa richiesta HTTP POST in genere ha un valore diverso rispetto all'host AEM Publish, pertanto è necessaria la configurazione CORS.

Durante il test dell'autenticazione SAML sul SDK AEM locale (localhost:4503), l'IDP può impostare l'intestazione Origin su null. In tal caso, aggiungere "null" all'elenco alloworigin.

{
    "alloworigin": [
        "$[env:SAML_IDP_ORIGIN;default=https://dev-1234567890.okta.com]",
        "null"
    ],
    "allowedpaths": [
        ".*/saml_login"
    ],
    "supportedmethods": [
        "POST"
    ]
}

Le configurazioni OSGi per ambiente (config.publish.dev, config.publish.stage e config.publish.prod) possono essere definite con attributi specifici se alloworigin e allowedpaths variano da un ambiente all'altro.

Configura AEM Dispatcher per consentire SAML HTTP POST

Dopo aver eseguito correttamente l'autenticazione nell'IDP, l'IDP orchestrerà un POST HTTP per tornare all'endpoint /saml_login registrato di AEM (configurato nell'IDP). Questo HTTP POST a /saml_login è bloccato per impostazione predefinita in Dispatcher, pertanto deve essere consentito esplicitamente utilizzando la seguente regola di Dispatcher:

...

# Allow SAML HTTP POST to ../saml_login end points
/0190 { /type "allow" /method "POST" /url "*/saml_login" }

Se la riscrittura dell'URL nel server web Apache è configurata (dispatcher/src/conf.d/rewrites/rewrite.rules), assicurati che le richieste agli endpoint .../saml_login non vengano gestite accidentalmente.

Appartenenza a gruppi dinamici

L'appartenenza al gruppo dinamico è una funzionalità di Apache Jackrabbit Oak che aumenta le prestazioni della valutazione e del provisioning del gruppo. Questa sezione descrive come utenti e gruppi vengono memorizzati quando questa funzione è abilitata e come modificare la configurazione del gestore di autenticazione SAML per abilitarlo per ambienti nuovi o esistenti.

Come abilitare l'iscrizione a gruppi dinamici per gli utenti SAML in nuovi ambienti

Per migliorare in modo significativo le prestazioni di valutazione dei gruppi nei nuovi ambienti AEM come Cloud Service, si consiglia di attivare la funzione di iscrizione dinamica ai gruppi in nuovi ambienti.
Si tratta di un passaggio necessario anche quando viene attivata la sincronizzazione dei dati. Ulteriori dettagli qui .
A tale scopo, aggiungere la seguente proprietà al file di configurazione OSGI:

/apps/example/osgiconfig/config.publish/com.adobe.granite.auth.saml.SamlAuthenticationHandler~example.cfg.json

Con questa configurazione, utenti e gruppi vengono creati come Utenti esterni Oak. In AEM, gli utenti e i gruppi esterni dispongono di un rep:principalName predefinito composto da [user name];[idp] o [group name];[idp].
Tenere presente che gli elenchi di controllo di accesso (ACL) sono associati al nome principale degli utenti o dei gruppi.
Quando si distribuisce questa configurazione in una distribuzione esistente in cui in precedenza identitySyncType non era specificato o impostato su default, verranno creati nuovi utenti e gruppi e a questi nuovi utenti e gruppi deve essere applicato l'ACL. I gruppi esterni non possono contenere utenti locali. Repoinit può essere utilizzato per creare ACL per i gruppi esterni SAML, anche se verranno creati solo quando l'utente eseguirà un accesso.
Per evitare questo refactoring su ACL, è stata implementata una funzionalità di migrazione standard.

Come archiviare le iscrizioni in gruppi locali ed esterni con appartenenza a gruppi dinamici

Nei gruppi locali i membri del gruppo sono memorizzati nell'attributo oak: rep:members. L’attributo contiene l’elenco degli UID di ogni membro del gruppo. Ulteriori dettagli sono disponibili qui.
Esempio:

{
  "jcr:primaryType": "rep:Group",
  "rep:principalName": "operators",
  "rep:managedByIdp": "SAML",
  "rep:members": [
    "635afa1c-beeb-3262-83c4-38ea31e5549e",
    "5e496093-feb6-37e9-a2a1-7c87b1cec4b0",
    ...
  ],
   ...
}

I gruppi esterni con appartenenza dinamica al gruppo non memorizzano alcun membro nella voce del gruppo.
L'appartenenza al gruppo viene invece memorizzata nelle voci utente. Ulteriori informazioni sono disponibili qui. Ad esempio, questo è il nodo OAK del gruppo:

{
  "jcr:primaryType": "rep:Group",
  "jcr:mixinTypes": [
    "rep:AccessControllable"
  ],
  "jcr:createdBy": "",
  "jcr:created": "Tue Jul 16 2024 08:58:47 GMT+0000",
  "rep:principalName": "GROUP_1;aem-saml-idp-1",
  "rep:lastSynced": "Tue Jul 16 2024 08:58:47 GMT+0000",
  "jcr:uuid": "d9c6af8a-35c0-3064-899a-59af55455cd0",
  "rep:externalId": "GROUP_1;aem-saml-idp-1",
  "rep:authorizableId": "GROUP_1;aem-saml-idp-1"
}

Questo è il nodo per un membro utente di quel gruppo:

{
  "jcr:primaryType": "rep:User",
  "jcr:mixinTypes": [
    "rep:AccessControllable"
  ],
  "surname": "Test",
  "rep:principalName": "testUser",
  "rep:externalId": "test;aem-saml-idp-1",
  "rep:authorizableId": "test",
  "rep:externalPrincipalNames": [
    "projects-users;aem-saml-idp-1",
    "GROUP_2;aem-saml-idp-1",
    "GROUP_1;aem-saml-idp-1",
    "operators;aem-saml-idp-1"
  ],
  ...
}

Come abilitare l'iscrizione a gruppi dinamici per gli utenti SAML negli ambienti esistenti

Come spiegato nella sezione precedente, il formato degli utenti e dei gruppi esterni è leggermente diverso da quello utilizzato per gli utenti e i gruppi locali. È possibile definire un nuovo ACL per i gruppi esterni ed eseguire il provisioning di nuovi utenti esterni, oppure utilizzare lo strumento di migrazione come descritto di seguito.

Abilitazione dell’iscrizione dinamica ai gruppi per gli ambienti esistenti con utenti esterni

Il gestore di autenticazione SAML crea utenti esterni quando viene specificata la seguente proprietà: "identitySyncType": "idp". In questo caso, è possibile abilitare l'appartenenza a gruppi dinamici modificando questa proprietà in: "identitySyncType": "idp_dynamic". Nessuna migrazione richiesta.

Migrazione automatica all'appartenenza a gruppi dinamici per gli ambienti esistenti con utenti locali

Il gestore di autenticazione SAML crea utenti locali quando viene specificata la seguente proprietà: "identitySyncType": "default". Questo è anche il valore predefinito quando la proprietà non è specificata. In questa sezione vengono descritti i passaggi eseguiti dalla procedura di migrazione automatica.

Quando questa migrazione è abilitata, viene eseguita durante l’autenticazione dell’utente ed è costituita dai seguenti passaggi:

Ad esempio, se prima della migrazione user1 è un utente locale e un membro del gruppo locale group1, dopo la migrazione si verificheranno le seguenti modifiche:
user1 diventa un utente esterno. Attributo rep:externalId aggiunto al suo profilo.
user1 diventa membro del gruppo esterno: group1;idp
user1 non è più membro diretto del gruppo locale: group1
group1;idp è membro del gruppo locale: group1.
user1 è quindi membro del gruppo locale: group1 sebbene ereditarietà

L'appartenenza al gruppo per i gruppi esterni è archiviata nel profilo utente nella proprietà rep:externalPrincipalNames

Come configurare la migrazione automatica all'appartenenza a un gruppo dinamico

{
  "idpIdentifier": "<value of IDP Identifier (idpIdentifier)" property from the "com.adobe.granite.auth.saml.SamlAuthenticationHandler" configuration to be migrated>"
}

Per migrare più configurazioni SAML, è necessario creare più configurazioni OSGi factory per com.adobe.granite.auth.saml.migration.SamlDynamicGroupMembershipMigration, ognuna delle quali specifica un idpIdentifier per la migrazione.

Hook di accesso SAML personalizzati

Per i casi d'uso avanzati, AEM supporta lo sviluppo di hook di accesso SAML personalizzati, ovvero servizi OSGi che implementano l'interfaccia com.adobe.granite.auth.saml.SamlLoginHook. Questi hook vengono eseguiti durante il processo di autenticazione SAML e possono essere utilizzati per implementare una logica personalizzata, ad esempio provisioning utente aggiuntivo o registrazione personalizzata.

Per ulteriori informazioni su come sviluppare e registrare un hook di accesso SAML personalizzato, consulta la documentazione Hook di accesso SAML personalizzato.

Distribuzione della configurazione SAML

Le configurazioni OSGi devono essere salvate in Git e distribuite in AEM as a Cloud Service utilizzando Cloud Manager.

$ git remote -v
adobe   https://git.cloudmanager.adobe.com/myOrg/myCloudManagerGit/ (fetch)
adobe   https://git.cloudmanager.adobe.com/myOrg/myCloudManagerGit/ (push)
$ git add .
$ git commit -m "SAML 2.0 configurations"
$ git push adobe saml-auth:develop

Distribuire il ramo Git Cloud Manager di destinazione (in questo esempio, develop) utilizzando una pipeline di distribuzione full stack.

Richiamare l’autenticazione SAML

Il flusso di autenticazione SAML può essere richiamato da una pagina web del sito AEM creando un collegamento creato appositamente o un pulsante. I parametri descritti di seguito possono essere impostati a livello di programmazione in base alle esigenze. Ad esempio, un pulsante di accesso può impostare saml_request_path, ovvero il punto in cui l'utente viene indirizzato dopo l'autenticazione SAML, su pagine AEM diverse, in base al contesto del pulsante.

Memorizzazione in cache protetta durante l’utilizzo di SAML

Nell’istanza di pubblicazione di AEM, la maggior parte delle pagine viene generalmente memorizzata nella cache. Tuttavia, per i percorsi protetti da SAML, la memorizzazione nella cache deve essere disabilitata o abilitata utilizzando la configurazione auth_checker. Per ulteriori informazioni, fare riferimento ai dettagli forniti qui

Tieni presente che se memorizzi nella cache i percorsi protetti senza abilitare auth_checker, potresti riscontrare un comportamento imprevedibile.

richiesta GET

L’autenticazione SAML può essere richiamata creando una richiesta HTTP GET nel formato:

HTTP GET /system/sling/login

e fornendo parametri di query:

Questo collegamento HTML, ad esempio, attiverà il flusso di accesso SAML e, al termine dell'operazione, porterà l'utente a /content/wknd/us/en/protected/page.html. Questi parametri di query possono essere impostati a livello di programmazione in base alle esigenze.

<a href="/system/sling/login?resource=/content/wknd&saml_request_path=/content/wknd/us/en/protected/page.html">
    Log in using SAML
</a>

richiesta POST

L'autenticazione SAML può essere richiamata creando una richiesta HTTP POST nel formato:

HTTP POST /system/sling/login

e fornendo i dati del modulo:

Questo pulsante HTML, ad esempio, utilizzerà un POST HTTP per attivare il flusso di accesso SAML e, al termine, porterà l'utente a /content/wknd/us/en/protected/page.html. Questi parametri dei dati dei moduli possono essere impostati a livello di programmazione in base alle esigenze.

<form action="/system/sling/login" method="POST">
    <input type="hidden" name="resource" value="/content/wknd">
    <input type="hidden" name="saml_request_path" value="/content/wknd/us/en/protected/page.html">
    <input type="submit" value="Log in using SAML">
</form>

Configurazione del Dispatcher

Entrambi i metodi HTTP GET e POST richiedono l'accesso client agli endpoint AEM /system/sling/login e pertanto devono essere consentiti tramite Dispatcher AEM.

Consenti i pattern URL necessari in base al caso in cui GET o POST siano in uso

# Allow GET-based SAML authentication invocation
/0191 { /type "allow" /method "GET" /url "/system/sling/login" /query "*" }

# Allow POST-based SAML authentication invocation
/0192 { /type "allow" /method "POST" /url "/system/sling/login" }