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-integrering med AEM Publish (eller Preview) gör att slutanvändare av en AEM-baserad webbupplevelse kan autentisera till en icke-Adobe IDP (Identity Provider) och få tillgång till AEM som namngiven, behörig användare.

Genomgång av konfiguration

I den här videon går vi igenom hur man konfigurerar SAML 2.0-integrering med AEM as a Cloud Service Publish Service och använder Okta som IDP.

Förutsättningar

Följande krävs när du konfigurerar 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 det offentliga IDP-certifikatet på AEM

IDP:s offentliga certifikat läggs till i AEM Global Trust Store och används för att validera att SAML-försäkran som skickas av IDP ä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 nyckelbehållare för autentiseringstjänster authentication-service-keystore

Det krävs att du skapar en nyckelbehållare för autentiseringstjänsten när ​ SAML 2.0-autentiseringshanterarens OSGi-konfigurationsegenskap handleLogout är inställd på true eller när AuthnRequest-signering/SAML-försäkran ​ krävs

Installera AEM nyckelpar för offentlig/privat nyckel install-aem-public-private-key-pair

Det är valfritt att installera AEM nyckelpar public/private

AEM Publish kan konfigureras för att signera AuthnRequests (till IDP) och kryptera SAML-försäkringar (till AEM). Detta uppnås genom en privat nyckel till AEM Publish, och den matchar den offentliga nyckeln till IDP.

Både AuthnRequest-signering och SAML-verifieringskryptering är valfria, men båda är aktiverade med SAML 2.0-autentiseringshanterarens OSGi-konfigurationsegenskap 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 SAML-konfiguration utförs via Adobe Granite SAML 2.0 Authentication Handler OSGi-konfigurationen.
Konfigurationen är en OSGi-fabrikskonfiguration, vilket innebär att en enda AEM as a Cloud Service Publish-tjänst kan ha flera SAML-konfigurationsträd som täcker diskreta resursträd i databasen. Detta är användbart för AEM-distributioner 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 olika miljöer.

Använd kryptering

När krypterar AuthnRequest och SAML-försäkran krävs följande egenskaper: useEncryption, spPrivateKeyAlias och keyStorePassword. keyStorePassword innehåller ett lösenord och därför får värdet inte lagras i OSGi-konfigurationsfilen utan injiceras med hemliga konfigurationsvärden

Konfigurera referensfilter

Under SAML-autentiseringsprocessen initierar IDP en HTTP POST på klientsidan till AEM Publish .../saml_login-slutpunkten. 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å den lokala AEM SDK (localhost:4503) kan IDP ange Origin header som null. Om så är fallet lägger du till "null" i 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 alloworigin och allowedpaths varierar mellan miljöer.

Konfigurera AEM Dispatcher så att SAML HTTP POST tillåts

Efter lyckad autentisering till IDP kommer IDP att dirigera om en HTTP POST tillbaka till AEM registrerade /saml_login-slutpunkt (konfigurerad i IDP). Denna HTTP POST till /saml_login blockeras som standard av 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) kontrollerar du att begäranden till .../saml_login-slutpunkterna inte av misstag bemannas.

Dynamiskt gruppmedlemskap

Dynamiskt gruppmedlemskap är en funktion i Apache Jackrabbit Oak som ökar prestanda för grupputvärdering och gruppetablering. I det här avsnittet beskrivs hur användare och grupper lagras när den här funktionen är aktiverad och hur du ändrar konfigurationen av SAML Authentication Handler för att aktivera den för nya eller befintliga miljöer.

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

För att avsevärt förbättra prestandan vid grupputvärdering i nya AEM as a Cloud Service-miljöer rekommenderas aktivering av funktionen för dynamiskt gruppmedlemskap i nya miljöer.
Detta är också ett nödvändigt steg när datasynkronisering aktiveras. Mer information här.
Det gör du genom att lägga till följande egenskap i OSGI-konfigurationsfilen:

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

Med den här konfigurationen skapas användare och grupper som Oak externa användare. I AEM har externa användare och grupper standardvärdet rep:principalName som består av [user name];[idp] eller [group name];[idp].
Observera att ACL (Access Control Lists) associeras med PrincipalName för användare eller grupper.
När den här konfigurationen distribueras i en befintlig distribution där tidigare identitySyncType inte har angetts eller angetts till default, skapas nya användare och grupper och ACL måste tillämpas på de nya användarna och grupperna. Observera att externa grupper inte kan innehålla lokala användare. Repoinit kan användas för att skapa ACL för externa SAML-grupper, även om de bara skapas när användaren utför en inloggning.
För att undvika den här omfaktoriseringen för ACL har en migreringsfunktion som standard 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 med uid för varje medlem i gruppen. Ytterligare information 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 inga medlemmar i gruppposten.
Gruppmedlemskapet lagras i stället i användarens poster. Ytterligare dokumentation finns här. Detta är t.ex. 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"
}

Det här ä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 det här fallet kan dynamiskt gruppmedlemskap aktiveras om egenskapen ändras till "identitySyncType": "idp_dynamic". Ingen migrering 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 har angetts. I det här avsnittet beskriver vi de steg som har utförts av det automatiska migreringsförfarandet.

När migreringen är aktiverad utförs den under användarautentiseringen 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 webbsida på en AEM-webbplats genom att skapa en länk som skapats för ändamålet eller en knapp. Parametrarna som beskrivs nedan kan ställas in programmatiskt efter behov, så en inloggningsknapp kan till exempel ställa in saml_request_path, som är den plats där användaren tas vid lyckad SAML-autentisering, på olika AEM-sidor, baserat på knappens kontext.

Skyddad cachelagring när SAML används

I publiceringsinstansen för AEM cache-lagras de flesta sidor. För SAML-skyddade sökvägar bör cachelagring antingen vara inaktiverad eller skyddad cachelagring vara aktiverad med konfigurationen auth_checker. 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 en HTTP GET-begäran skapas i formatet:

HTTP GET /system/sling/login

och tillhandahålla frågeparametrar:

Den här HTML-länken utlöser till exempel SAML-inloggningsflödet och tar användaren till /content/wknd/us/en/protected/page.html när det är klart. Dessa frågeparametrar kan ställas in programmatiskt 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-begäran

SAML-autentisering kan anropas genom att en HTTP POST-begäran skapas i formatet:

HTTP POST /system/sling/login

och tillhandahålla formulärdata:

Den här HTML-knappen kommer till exempel att använda en HTTP POST för att utlösa SAML-inloggningsflödet och ta användaren till /content/wknd/us/en/protected/page.html när det är klart. Dessa formulärdataparametrar kan ställas in programmatiskt 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>

Dispatcher-konfiguration

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

Tillåt nödvändiga URL-mönster baserade 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" }