SAML 2.0-autentisering saml-2-0-authentication

Lär dig hur du konfigurerar och autentiserar slutanvändare (inte författare till AEM) till en SAML 2.0-kompatibel IDP som du väljer.

Vilken SAML för AEM as a Cloud Service?

SAML 2.0-integration med AEM Publish (eller Preview) gör det möjligt för slutanvändare av en AEM-baserad webbupplevelse att autentisera sig mot en icke-Adobe IDP (Identity Provider) och få tillgång till AEM som namngiven, auktoriserad användare.

Konfigurationsgenomgång

Den här videon går igenom hur man sätter upp SAML 2.0-integration med AEM som en Cloud Service Publish-tjänst och använder Okta som IDP.

Förkunskapskrav

Följande krävs vid installation av SAML 2.0-autentisering:

SAML 2.0 stöds endast för att autentisera användning av AEM Publish eller Preview. Om du vill hantera autentiseringen av AEM Author med hjälp av och IDP integrerar du IDP med Adobe IMS.

Installera IDP publikt certifikat på AEM

IDP:ns publika certifikat läggs till i AEM:s Global Trust Store och används för att validera att SAML-assertionen som skickas av IDP:n är giltig.

Global Trust Store har konfigurerats med IDP:s offentliga certifikat på AEM Author, men eftersom SAML bara används på AEM Publish måste Global Trust Store replikeras till AEM Publish för att IDP:s offentliga certifikat ska vara tillgängligt där.

Skapa autentiseringstjänst-nyckellagring authentication-service-keystore

Att skapa en nyckellagring för autentiseringstjänst krävs när SAML 2.0-autentiseringshanterarens OSGi-konfigurationsegenskap handleLogout sätts till true eller när AuthnRequest-signering/SAML-assertionskryptering krävs

Installera AEM offentlig/privat nyckelpar install-aem-public-private-key-pair

Installation av AEM:s publika/privata nyckelpar är valfritt

AEM Publish kan konfigureras för att signera AuthnRequests (till IDP) och kryptera SAML-assertioner (till AEM). Detta uppnås genom att tillhandahålla en privat nyckel till AEM Publish, och dess publika nyckel matchar IDP:n.

Både AuthnRequest-signering och SAML-assertionskryptering är valfria, men båda är aktiverade, med hjälp av SAML 2.0-autentiseringshanteraren OSGi-konfigurationsegenskapen useEncryption, vilket innebär att båda eller ingen kan användas.

Konfigurera autentiseringshanteraren för SAML 2.0 configure-saml-2-0-authentication-handler

AEM:s SAML-konfiguration utförs via Adobe Granite SAML 2.0 Authentication Handler OSGi-konfigurationen .
Konfigurationen är en OSGi-fabrikskonfiguration, vilket innebär att en enskild AEM som Cloud Service Publish-tjänst kan ha flera SAML-konfigurationer som täcker diskreta resursträd i arkivet; detta är användbart för AEM-installationer på flera platser.

OSGi-konfigurationer per miljö (config.publish.dev, config.publish.stage, och config.publish.prod) kan definieras med specifika attribut om SAML-konfigurationen varierar mellan miljöer.

Använd kryptering

Vid kryptering av AuthnRequest- och SAML-assertionen krävs följande egenskaper: useEncryption, spPrivateKeyAlias, och keyStorePassword. Innehåller keyStorePassword ett lösenord, därför får värdet inte lagras i OSGi-konfigurationsfilen, utan istället injiceras med hjälp av hemliga konfigurationsvärden

Configure Referrer-filter

Under SAML-autentiseringsprocessen initierar IDP:n en klientsida HTTP POST till AEM Publishs .../saml_login slutpunkt. Om IDP och AEM Publish finns på en annan plats är AEM Publish Referer-filter konfigurerat via OSGi-konfigurationen för att tillåta HTTP POST från IDP:ns ursprung.

AEM Publish har stöd för en enda konfiguration av referensfilter, så sammanfoga SAML-konfigurationskraven med befintliga konfigurationer.

OSGi-konfigurationer per miljö (config.publish.dev, config.publish.stage och config.publish.prod) kan definieras med specifika attribut om allow.hosts (eller allow.hosts.regex) varierar mellan miljöer.

Konfigurera Cross-Origin Resource Sharing (CORS)

Under SAML-autentiseringsprocessen initierar IDP en HTTP POST på klientsidan till AEM Publish .../saml_login-slutpunkten. Om IDP och AEM Publish finns på olika värdar/domäner måste AEM Publish CRoss-Origin Resource Sharing (CORS) konfigureras så att HTTP POST tillåts från IDP:s värd/domän.

HTTP POST-begärans Origin-huvud har vanligtvis ett annat värde än AEM Publish-värden, vilket kräver CORS-konfiguration.

När SAML-autentisering testas på det lokala AEM SDK:n (localhost:4503), kan IDP:n ställa in Origin headern till null. Om så är fallet, lägg till "null" på listan alloworigin .

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

OSGi-konfigurationer per miljö (config.publish.dev, config.publish.stage, och config.publish.prod) kan definieras med specifika attribut om och alloworigin allowedpaths varierar mellan miljöer.

Konfigurera AEM Dispatcher för att tillåta SAML HTTP POSTs

Efter framgångsrik autentisering till IDP:n kommer IDP:n att orkestrera en HTTP POST tillbaka till AEM:s registrerade /saml_login slutpunkt (konfigurerad i IDP:n). Denna HTTP POST till /saml_login blockeras som standard hos Dispatcher, så den måste uttryckligen tillåtas med följande Dispatcher-regel:

...

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

Om URL-omskrivning på Apache-webbservern är konfigurerad (dispatcher/src/conf.d/rewrites/rewrite.rules), se till att förfrågningar till .../saml_login slutpunkterna inte av misstag förstörs.

Dynamiskt gruppmedlemskap

Dynamiskt gruppmedlemskap är en funktion i Apache Jackrabbit Oak som ökar prestandan vid grupputvärdering och provisionering. Detta avsnitt beskriver hur användare och grupper lagras när denna funktion aktiveras och hur man kan ändra konfigurationen av SAML Authentication Handler för att möjliggöra den för nya eller befintliga miljöer.

Hur man aktiverar dynamiskt gruppmedlemskap för SAML-användare i nya miljöer

För att avsevärt förbättra grupputvärderingsprestandan i nya AEM som molntjänst-miljöer rekommenderas aktivering av funktionen Dynamiskt gruppmedlemskap i nya miljöer.
Detta är också ett nödvändigt steg när datasynkronisering aktiveras. Mer information här .
För att göra detta, lägg till följande egenskap i OSGI-konfigurationsfilen:

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

Med denna konfiguration skapas användare och grupper som Oak Externa användare. I AEM har externa användare och grupper en standard rep:principalName komponerad av [user name];[idp] eller [group name];[idp].
Observera att åtkomstkontrolllistor (ACL) är kopplade till användarnas eller gruppers huvudnamn.
När denna konfiguration distribueras i en befintlig distribution där det tidigare identitySyncType inte specificerades eller sattes till default, kommer nya användare och grupper att skapas och ACL måste tillämpas på dessa nya användare och grupper. Observera att externa grupper inte kan innehålla lokala användare. Repoinit kan användas för att skapa ACL för SAML Externa grupper, även om de bara skapas när användaren gör en inloggning.
För att undvika denna omstrukturering på ACL har en standard migreringsfunktion implementerats.

Hur medlemskap lagras i lokala och externa grupper med dynamiskt gruppmedlemskap

På lokala grupper lagras gruppmedlemmarna i ekattributet: rep:members. Attributet innehåller listan över uid för varje medlem i gruppen. Ytterligare detaljer finns här.
Exempel:

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

Externa grupper med dynamiskt gruppmedlemskap lagrar ingen medlem i gruppposten.
Gruppmedlemskapet lagras istället i användarens poster. Ytterligare dokumentation finns här. Till exempel är detta OAK-noden för gruppen:

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

Detta är noden för en användarmedlem i den gruppen:

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

Aktivera dynamiskt gruppmedlemskap för SAML-användare i befintliga miljöer

Som förklaras i föregående avsnitt skiljer sig formatet för externa användare och grupper något från formatet som används för lokala användare och grupper. Det går att definiera en ny åtkomstkontrollista för externa grupper och etablera nya externa användare, eller använda migreringsverktyget enligt beskrivningen nedan.

Aktivera dynamiskt gruppmedlemskap för befintliga miljöer med externa användare

Hanteraren för SAML-autentisering skapar externa användare när följande egenskap anges: "identitySyncType": "idp". I detta fall kan dynamiskt gruppmedlemskap aktiveras genom att modifiera denna egenskap till: "identitySyncType": "idp_dynamic". Ingen migration krävs.

Automatisk migrering till dynamiskt gruppmedlemskap för befintliga miljöer med lokala användare

SAML-autentiseringshanteraren skapar lokala användare när följande egenskap anges "identitySyncType": "default": . Detta är också standardvärdet när egenskapen inte är specificerad. I detta avsnitt beskriver vi de steg som utförs av den automatiska migrationsproceduren.

När denna migrering är aktiverad utförs den under användarautentisering och består av följande steg:

Om migreringen user1 till exempel är en lokal användare och medlem i den lokala gruppen group1 sker följande ändringar efter migreringen:
user1 blir en extern användare. Attributet rep:externalId har lagts till i den här profilen.
user1 blir medlem i den externa gruppen: group1;idp
user1 är inte längre en direkt medlem i den lokala gruppen: group1
group1;idp är medlem i den lokala gruppen: group1.
user1 är sedan medlem i den lokala gruppen: group1 genom arv

Gruppmedlemskapet för externa grupper lagras i användarprofilen i egenskapen rep:externalPrincipalNames

Konfigurera automatisk migrering till dynamiskt gruppmedlemskap

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

Om du vill migrera flera SAML-konfigurationer måste du skapa flera OSGi-fabrikskonfigurationer för com.adobe.granite.auth.saml.migration.SamlDynamicGroupMembershipMigration, där var och en anger en idpIdentifier som ska migreras.

Distribuera SAML-konfiguration

OSGi-konfigurationerna måste implementeras i Git och distribueras till AEM as a Cloud Service med 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

Distribuera Cloud Manager Git-målgrenen (i det här exemplet develop) med hjälp av en pipeline för distribution av Full Stack.

Anropa SAML-autentisering

SAML-autentiseringsflödet kan anropas från en AEM-webbplats, genom att skapa särskilt utformade länkar eller knappar. De parametrar som beskrivs nedan kan programmatiskt ställas in vid behov, så till exempel kan en inloggningsknapp ställa in saml_request_path, vilket är där användaren tas vid lyckad SAML-autentisering, till olika AEM-sidor, baserat på knappens kontext.

Säker cache medan jag använder SAML

På AEM publiceringsinstansen är de flesta sidor vanligtvis cachade. För SAML-skyddade vägar bör dock caching antingen inaktiveras eller säkrad caching aktiveras med auth_checker-konfigurationen. Mer information finns i här

Observera att om du cachelagrar skyddade sökvägar utan att aktivera auth_checker kan du uppleva oförutsägbara beteenden.

GET-begäran

SAML-autentisering kan anropas genom att skapa en HTTP GET-förfrågan i formatet:

HTTP GET /system/sling/login

och tillhandahåller frågeparametrar:

Till exempel kommer denna HTML-länk att trigga SAML:s inloggningsflöde, och när det lyckas tas användaren till /content/wknd/us/en/protected/page.html. Dessa frågeparametrar kan programmatiskt ställas in efter behov.

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

POST-förfrågan

SAML-autentisering kan anropas genom att skapa en HTTP POST-förfrågan i formatet:

HTTP POST /system/sling/login

och tillhandahålla formulärdata:

Till exempel använder denna HTML-knapp en HTTP POST för att trigga SAML-inloggningsflödet, och när det lyckas ta användaren till /content/wknd/us/en/protected/page.html. Dessa formulärdataparametrar kan programmatiskt ställas in efter behov.

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

Dispatcherkonfiguration

Både HTTP GET och POST-metoderna kräver klientåtkomst till AEM:s /system/sling/login endpoints, och därför måste de tillåtas via AEM Dispatcher.

Tillåt nödvändiga URL-mönster baserat på om GET eller POST används

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