Autenticazione SAML 2.0 saml-2-0-authentication

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

Quale SAML per AEM as a Cloud Service?

L’integrazione SAML 2.0 con AEM Publish (o Anteprima), consente agli utenti finali di un’esperienza web basata su AEM di autenticarsi in un IDP (Identity Provider) non Adobe e di accedere ad AEM come utente autorizzato con nome.

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 l’autenticazione degli utilizzi in AEM Publish o Preview. Per gestire l'autenticazione di AEM Author tramite e IDP, integra l'IDP con Adobe IMS.

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 fonti attendibili globale è configurato con il certificato pubblico dell’IDP su AEM Author, ma poiché SAML viene utilizzato solo su AEM Publish, l’archivio fonti attendibili globale deve essere replicato su AEM Publish affinché il certificato pubblico dell’IDP sia accessibile.

Crea keystore del servizio di autenticazione authentication-service-keystore

È necessario creare un keystore per il servizio di autenticazione quando la proprietà di configurazione OSGi handleLogout del gestore di autenticazione SAML 2.0 è impostata su true o quando è richiesta la firma AuthnRequest/la crittografia dell'asserzione SAML

Installare una coppia di chiavi pubblica/privata di 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 AuthnRequest che la crittografia delle asserzioni SAML sono facoltative, ma entrambe sono abilitate, utilizzando la proprietà di configurazione OSGi useEncryption🔗 del gestore di autenticazione SAML 2.0, che indica che è possibile utilizzare entrambe o nessuna delle due.

Configura gestore autenticazione SAML 2.0 configure-saml-2-0-authentication-handler

La configurazione SAML di AEM viene eseguita tramite la configurazione OSGi 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 memorizzato 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 la pubblicazione AEM esistono su host/domini diversi, è necessario configurare la condivisione CORS (CRoss-Origin Resource Sharing)di AEM Publish per consentire i 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 gruppo dinamico

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 vengono memorizzati utenti e gruppi quando questa funzione è abilitata e come modificare la configurazione del gestore di autenticazione SAML per abilitarlo per gli ambienti nuovi o esistenti.

Abilitare l’iscrizione al gruppo dinamico per gli utenti SAML nei nuovi ambienti

Per migliorare in modo significativo le prestazioni di valutazione dei gruppi nei nuovi ambienti AEM as a Cloud Service, si consiglia di attivare la funzione di iscrizione al gruppo dinamico nei nuovi ambienti.
Questo è anche un passaggio necessario quando viene attivata la sincronizzazione dei dati. Ulteriori dettagli qui .
A questo scopo, aggiungi 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 il refactoring in ACL, è stata implementata una funzionalità di migrazione standard.

Memorizzazione delle appartenenze 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"
  ],
  ...
}

Abilitare l’iscrizione al gruppo dinamico 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 al gruppo dinamico modificando questa proprietà in: "identitySyncType": "idp_dynamic". Non è richiesta alcuna migrazione.

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 proprietà seguente: "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 e consiste dei 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.

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, in caso di esito positivo, 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, in caso di esito positivo, porterà l'utente a /content/wknd/us/en/protected/page.html. Questi parametri dei dati del modulo 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 Dispatcher

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

Consenti i pattern URL necessari in base all’utilizzo di GET o POST

# 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" }