SAML 2.0-Authentifizierung saml-2-0-authentication

Erfahren Sie, wie Sie Endbenutzende (keine AEM-Autorinnen oder -Autoren) für einen mit SAML 2.0 kompatiblen Identitätsanbieter (Identity Provider, IDP) Ihrer Wahl einrichten und authentifizieren.

SAML für AEM as a Cloud Service

Die SAML 2.0-Integration in AEM Publish (oder in der Vorschau) ermöglicht es Endbenutzenden eines AEM-basierten Web-Erlebnisses, sich bei einem Nicht-Adobe-IDP zu authentifizieren und auf AEM als benannte, autorisierte Benutzende zuzugreifen.

Konfigurationsanleitung

In diesem Video werden die Einrichtung der SAML 2.0-Integration im Publish-Service von AEM as a Cloud Service und die Verwendung von Okta als IDP erläutert.

Voraussetzungen

Folgendes ist beim Einrichten der SAML 2.0-Authentifizierung erforderlich:

SAML 2.0 wird nur zur Authentifizierung von Benutzenden für AEM Publish oder die Vorschau unterstützt. Um die Authentifizierung von AEM Author mit einem IDP zu verwalten, integrieren Sie den IDP in Adobe IMS.

Installieren des öffentlichen IDP-Zertifikats in AEM

Das öffentliche Zertifikat des IDP wird zum AEM Global Trust Store hinzugefügt und dient zur Überprüfung der vom IDP gesendeten SAML-Assertion.

Der Global Trust Store ist mit dem öffentlichen Zertifikat des IDP in AEM Author konfiguriert. Da SAML jedoch nur in AEM Publish verwendet wird, muss der Global Trust Store in AEM Publish repliziert werden, damit dort auf das öffentliche IDP-Zertifikat zugegriffen werden kann.

Erstellen eines Keystores für „authentication-service“ authentication-service-keystore

Für „authentication-service“ muss ein Keystore erstellt werden, wenn die OSGi-Konfigurationseigenschaft handleLogout des SAML 2.0-Authentifizierungs-Handlers auf true gesetzt ist oder wenn eine AuthnRequest-Signierung/Verschlüsselung der SAML-Assertion erforderlich ist.

Installieren des öffentlichen/privaten AEM-Schlüsselpaars install-aem-public-private-key-pair

Die Installation des öffentlichen/privaten AEM-Schlüsselpaars ist optional.

AEM Publish kann so konfiguriert werden, dass AuthnRequests (an IDP) signiert und SAML-Assertionen (an AEM) verschlüsselt werden. Dies wird erreicht, indem ein privater Schlüssel für AEM Publish und der zugehörige öffentliche Schlüssel für den IDP bereitgestellt wird.

Die Signierung der AuthnRequest und Verschlüsselung der SAML-Assertion sind optional. Beides wird jedoch mit der OSGi-Konfigurationseigenschaft useEncryption des SAML 2.0-Authentifizierungs-Handlers aktiviert. Das bedeutet, dass entweder beide oder keines der Verfahren verwendet werden kann.

Konfigurieren des SAML 2.0-Authentifizierungs-Handlers configure-saml-2-0-authentication-handler

Die SAML-Konfiguration für AEM erfolgt über die OSGi-Konfiguration Adobe Granite SAML 2.0 Authentication Handler.
Die Konfiguration ist eine OSGi-Werkskonfiguration, d. h., ein Publish-Service von AEM as a Cloud Service kann über mehrere SAML-Konfigurationen verfügen, die diskrete Ressourcenbäume des Repositorys abdecken. Dies ist für AEM-Multi-Site-Bereitstellungen nützlich.

OSGi-Konfigurationen pro Umgebung (config.publish.dev, config.publish.stage und config.publish.prod) können mit bestimmten Attributen definiert werden, wenn die SAML-Konfiguration zwischen Umgebungen variiert.

Verwenden von Verschlüsselung

Beim Verschlüsseln der AuthnRequest und SAML-Assertion sind die folgenden Eigenschaften erforderlich: useEncryption, spPrivateKeyAlias und keyStorePassword. keyStorePassword enthält ein Passwort. Daher darf der Wert nicht in der OSGi-Konfigurationsdatei gespeichert werden, sondern muss stattdessen mithilfe geheimer Konfigurationswerte eingefügt werden.

Konfigurieren des Referrer-Filters

Während des SAML-Authentifizierungsprozesses initiiert der IDP eine Client-seitige HTTP-POST-Anfrage an den AEM Publish-Endpunkt .../saml_login. Haben der IDP und AEM Publish einen anderen Ursprung, wird der Referrer-Filter von AEM Publish über die OSGi-Konfiguration konfiguriert, um HTTP-POST-Anfragen vom IDP-Ursprung zuzulassen.

AEM Publish unterstützt eine Konfiguration mit einem einzelnen Referrer-Filter. Führen Sie daher die SAML-Konfigurationsanforderungen mit vorhandenen Konfigurationen zusammen.

OSGi-Konfigurationen pro Umgebung (config.publish.dev, config.publish.stage und config.publish.prod) können mit bestimmten Attributen definiert werden, wenn allow.hosts (oder allow.hosts.regex) zwischen Umgebungen variiert.

Konfigurieren von Cross-Origin Resource Sharing (CORS)

Während des SAML-Authentifizierungsprozesses initiiert der IDP eine Client-seitige HTTP-POST-Anfrage an den AEM Publish-Endpunkt .../saml_login. Wenn der IDP und AEM Publish auf verschiedenen Hosts/Domains vorhanden sind, muss der Mechanismus Cross-Origin Resource Sharing (CORS) so konfiguriert werden, dass HTTP-POST-Anfragen vom Host bzw. von der Domain des IDP zugelassen werden.

Der Origin-Header dieser HTTP-POST-Anfrage weist in der Regel einen anderen Wert auf als der AEM Publish-Host und erfordert daher eine CORS-Konfiguration.

Beim Testen der SAML-Authentifizierung für das lokale AEM SDK (localhost:4503) kann der IDP den Origin-Header auf null festlegen. Ist dies der Fall, fügen Sie "null" der alloworigin-Liste hinzu.

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

OSGi-Konfigurationen pro Umgebung (config.publish.dev, config.publish.stage, und config.publish.prod) können mit bestimmten Attributen definiert werden, wenn alloworigin und allowedpaths zwischen Umgebungen variieren.

Konfigurieren von AEM Dispatcher zum Zulassen von SAML-HTTP-POSTs

Nach erfolgreicher Authentifizierung beim IDP orchestriert der IDP eine HTTP-POST-Anfrage zurück zum registrierten /saml_login-AEM-Endpunkt (beim IDP konfiguriert). Diese HTTP-POST-Anfrage an /saml_login wird standardmäßig auf Dispatcher-Ebene blockiert. Daher muss diese explizit mithilfe der folgenden Dispatcher-Regel zugelassen werden:

...

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

Wenn das Umschreiben von URLs auf dem Apache-Webserver konfiguriert ist (dispatcher/src/conf.d/rewrites/rewrite.rules) stellen Sie sicher, dass Anfragen an .../saml_login-Endpunkte nicht versehentlich beschädigt werden.

So aktivieren Sie die dynamische Gruppenmitgliedschaft für SAML-Benutzer in neuen Umgebungen

Um die Leistung bei der Gruppenbewertung in neuen AEM as a Cloud Service-Umgebungen deutlich zu verbessern, wird die Aktivierung der Funktion "Dynamische Gruppenmitgliedschaft"in neuen Umgebungen empfohlen.
Dies ist auch ein notwendiger Schritt bei der Aktivierung der Datensynchronisation. Weitere Details hier .
Fügen Sie dazu der OSGi-Konfigurationsdatei die folgende Eigenschaft hinzu:

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

Mit dieser Konfiguration werden Benutzer und Gruppen als externe Oak-Benutzer erstellt. In AEM haben externe Benutzer und Gruppen eine standardmäßige rep:principalName, die von [user name];[idp] oder [group name];[idp] zusammengestellt wird.
Beachten Sie, dass Zugriffssteuerungslisten (ACL) mit dem PrincipalName von Benutzern oder Gruppen verknüpft sind.
Bei der Bereitstellung dieser Konfiguration in einer vorhandenen Bereitstellung, in der zuvor identitySyncType nicht angegeben oder auf default festgelegt wurde, werden neue Benutzer und Gruppen erstellt und die ACL muss auf diese neuen Benutzer und Gruppen angewendet werden. Beachten Sie, dass externe Gruppen keine lokalen Benutzer enthalten können. Repoinit kann verwendet werden, um ACL für externe SAML-Gruppen zu erstellen, auch wenn diese nur erstellt werden, wenn der Benutzer eine Anmeldung durchführt.
Um diese Umgestaltung der ACL zu vermeiden, wurde eine standardmäßige Migrationsfunktion implementiert.

Speicherung von Mitgliedschaften in lokalen und externen Gruppen mit dynamischer Gruppenmitgliedschaft

Bei lokalen Gruppen werden die Gruppenmitglieder im Oak-Attribut gespeichert: rep:members. Das -Attribut enthält die Liste der UID jedes Gruppenmitglieds. Weitere Details finden Sie hier.
Zum Beispiel:

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

Externe Gruppen mit dynamischer Gruppenmitgliedschaft speichern kein Mitglied im Gruppeneintrag.
Die Gruppenmitgliedschaft wird stattdessen in den Benutzereinträgen gespeichert. Zusätzliche Dokumentation finden Sie hier. Dies ist beispielsweise der OAK-Knoten für die Gruppe:

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

Dies ist der Knoten für ein Benutzermitglied dieser Gruppe:

{
  "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"
  ],
  ...
}

Automatische Migration zur dynamischen Gruppenmitgliedschaft für bestehende Umgebungen

Wenn diese Migration aktiviert ist, wird sie während der Benutzerauthentifizierung durchgeführt und umfasst die folgenden Schritte:

Wenn beispielsweise vor der Migration user1 ein lokaler Benutzer und ein Mitglied der lokalen Gruppe group1 ist, werden nach der Migration die folgenden Änderungen vorgenommen:
user1 wird zu einem externen Benutzer. Das Attribut rep:externalId wird seinem Profil hinzugefügt.
user1 wird Mitglied der externen Gruppe: group1;idp
user1 ist kein direktes Mitglied der lokalen Gruppe mehr: group1
group1;idp ist ein Mitglied der lokalen Gruppe: group1.
user1 ist dann ein Mitglied der lokalen Gruppe: group1 durch Vererbung

Die Gruppenmitgliedschaft für externe Gruppen wird im Benutzerprofil im Attribut rep:authorizableId gespeichert.

So konfigurieren Sie die automatische Migration zu einer dynamischen Gruppenmitgliedschaft

{
  "idpIdentifier": "<vaule of identitySyncType of saml configuration to be migrated>"
}

Bereitstellen der SAML-Konfiguration

Die OSGi-Konfigurationen müssen an Git übertragen und mithilfe von Cloud Manager für AEM as a Cloud Service bereitgestellt werden.

$ 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

Stellen Sie die Git-Verzweigung von Cloud Manager (in diesem Beispiel develop) mithilfe einer Full-Stack-Implementierungs-Pipeline bereit.

Aufrufen der SAML-Authentifizierung

Der SAML-Authentifizierungsfluss kann von einer AEM Site-Web-Seite aus aufgerufen werden, indem ein speziell gestalteter Link oder eine Schaltfläche erstellt wird. Die unten beschriebenen Parameter können bei Bedarf programmgesteuert festgelegt werden. Beispielsweise kann eine Anmeldeschaltfläche den saml_request_path, der die Person nach erfolgreicher SAML-Authentifizierung auf verschiedene AEM-Seiten führt, je nach Kontext der Schaltfläche auf verschiedene Seiten weiterleiten.

GET-Anfrage

Die SAML-Authentifizierung kann durch Erstellen einer HTTP-GET-Anfrage im folgenden Format aufgerufen werden:

HTTP GET /system/sling/login

und durch Bereitstellung von Abfrageparametern:

Dieser HTML-Link löst beispielsweise den SAML-Anmeldevorgang aus und leitet die Person bei Erfolg zu /content/wknd/us/en/protected/page.html. Diese Abfrageparameter können bei Bedarf programmgesteuert festgelegt werden.

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

POST-Anfrage

Die SAML-Authentifizierung kann durch Erstellen einer HTTP-POST-Anfrage im folgenden Format aufgerufen werden:

HTTP POST /system/sling/login

und durch Angeben der Formulardaten:

Diese HTML-Schaltfläche verwendet beispielsweise einen HTTP-POST, um den SAML-Anmeldevorgang auszulösen und die Person bei Erfolg zu /content/wknd/us/en/protected/page.html weiterzuleiten. Diese Formulardatenparameter können je nach Bedarf programmgesteuert festgelegt werden.

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

Dispatcher-Konfiguration

Sowohl die HTTP-GET- als auch die POST-Methode erfordern einen Client-Zugriff auf die /system/sling/login-Endpunkte von AEM und müssen daher über den AEM Dispatcher zugelassen werden.

Zulassen der erforderlichen URL-Muster, je nachdem, ob GET oder POST verwendet wird

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