Open ID Connect-Unterstützung für AEM as a Cloud Service auf Veröffentlichungsebene open-id-connect-support-for-aem-as-a-cloud-service-on-publish-tier

Einführung introduction

Wenn Unternehmen ihre digitalen Erlebnisse modernisieren, wird sicheres und skalierbares Identitäts-Management zu einer grundlegenden Anforderung. Adobe Experience Manager (AEM) Cloud Service unterstützt jetzt OpenID Connect (OIDC) auf der Veröffentlichungsebene, was eine nahtlose und standardbasierte Integration mit führenden Identitätsanbietern (IDPs) wie Entra ID (Azure AD), Google, Okta, Auth0, Ping Identity, ForgeRock und von OIDC unterstützten IDPs ermöglicht.

OIDC ist eine Identitätsebene auf dem OAuth 2.0-Protokoll, die eine zuverlässige Benutzerauthentifizierung ermöglicht und gleichzeitig Entwicklungsfachleuten die Arbeit erleichtert. Sie wird häufig für B2C- (Business-to-Consumer), Intranet- und Partnerportalszenarien verwendet, in denen ein sicherer Verbund von Benutzeranmeldung und Identität erforderlich ist.

Bisher waren AEM-Kundinnen und -Kunden dafür verantwortlich, ihre eigene benutzerdefinierte Anmeldelogik auf der Veröffentlichungsebene zu implementieren. Dies hat die Entwicklungszeit verlängert und langfristige Wartungs- und Sicherheitsprobleme mit sich gebracht. Durch die native Unterstützung von OIDC beseitigt AEM Cloud Service diese Belastung, indem ein sicherer, erweiterbarer und von Adobe unterstützter Authentifizierungsmechanismus für Benutzende bereitgestellt wird, die auf Veröffentlichungsumgebungen zugreifen.

Unabhängig davon, ob Sie eine personalisierte Verbraucher-Website oder ein authentifiziertes internes Portal bereitstellen, vereinfacht OIDC auf der Veröffentlichungsebene die Identitätsverknüpfung und reduziert das Risiko durch zentralisierte Identitäts-Governance. Außerdem können Unternehmen moderne Compliance- und Sicherheitsstandards erfüllen, ohne auf Flexibilität zu verzichten.

Konfigurieren von AEM für die OIDC-Authentifizierung configure-aem-oidc-authentication

Voraussetzungen prerequisits

Wir gehen davon aus, dass die folgenden Informationen verfügbar oder definiert sind:

Informationen aus der IDP-Konfiguration:

Überblick über die Konfigurationsdateien overview-of-the-configuration-files

Unten finden Sie eine Liste der Dateien, die konfiguriert werden müssen:

Das folgende Diagramm zeigt, wie die genannten Konfigurationselemente verknüpft sind. Da es sich hierbei um ServiceFactory-Komponenten handelt, kann ~uniqueid eine beliebige eindeutige Zeichenfolge sein:

Konfigurieren der OIDC-Verbindung configure-the-oidc-connection

Zunächst müssen wir die OIDC-Verbindung konfigurieren. Es können mehrere OIDC-Verbindungen konfiguriert werden, von denen jede einen anderen Namen haben muss.

In einigen Umgebungen macht der Identitätsanbieter (IdP) möglicherweise keinen gültigen .well-known-Endpunkt verfügbar.
In diesem Fall können die erforderlichen Endpunkte manuell definiert werden, indem die folgenden Eigenschaften in der Konfigurationsdatei angegeben werden.
In diesem Konfigurationsmodus darf die baseUrl-Eigenschaft nicht festgelegt werden.

"authorizationEndpoint": "https://idp-url/oauth2/v1/authorize",
"tokenEndpoint": "https://idp-url/oauth2/v1/token",
"jwkSetURL":"https://idp-url/oauth2/v1/keys",
"issuer": "https://idp-url"

Konfigurieren des OIDC-Authentifizierungs-Handlers configure-oidc-authentication-handler

Konfigurieren Sie jetzt den OIDC-Authentifizierungs-Handler. Es können mehrere OIDC-Verbindungen konfiguriert werden. Jede muss einen anderen Namen haben. Wenn sie denselben externen OAK-Identitätsanbieter nutzen, können sie Benutzende freigeben.

Konfigurieren von SlingUserInfoProcessor configure-slinguserinfoprocessor

Konfigurieren des Synchronisierungs-Handlers configure-the-synchronization-handler

Es muss mindestens ein Synchronisierungs-Handler konfiguriert werden, um die in Oak authentifizierten Benutzenden zu synchronisieren. Weitere Details finden Sie auf dieser Seite.

Erstellen Sie eine Datei mit dem Namen org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler~azure.cfg.json. Das Suffix azure muss eine eindeutige Kennung sein. Weitere Informationen zum Konfigurieren der Eigenschaften finden Sie in der Dokumentation zur Benutzer- und Gruppensynchronisierung in Oak. Nachfolgend sehen Sie eine Beispielkonfiguration:

{
  "user.expirationTime":"1h",
  "user.membershipExpTime":"1h",
  "group.expirationTime": "1d"
  "user.propertyMapping":[
    "profile/givenName=profile/given_name",
    "profile/familyName=profile/family_name",
    "rep:fullname=profile/name",
    "profile/email=profile/email",
    "access_token=access_token",
    "refresh_token=refresh_token"
  ],
  "user.pathPrefix":"azure",
  "handler.name":"azure"
}

Während der Entwicklung können die Ablaufzeiten auf einen niedrigeren Wert reduziert werden (z. B.: 1s), um das Testen der Benutzer- und Gruppensynchronisierung in Oak zu beschleunigen.
Im Folgenden finden Sie einige der relevantesten Attribute, die in DefaultSyncHandler konfiguriert werden müssen. Beachten Sie, dass die dynamische Gruppenmitgliedschaft immer in Cloud Services aktiviert sein sollte.

Konfigurieren des externen Anmeldemoduls configure-the-external-login-module

Schließlich müssen Sie das externe Anmeldemodul konfigurieren.

Optional: Implementieren eines benutzerdefinierten UserInfoProcessor implement-a-custom-userinfoprocessor

Der Benutzer wird durch ein ID-Token authentifiziert und zusätzliche Attribute werden von dem für die ID definierten userInfo-Endpunkt abgerufen. Der UserInfoProcessor ist für die Umwandlung der vom Identitätsanbieter empfangenen Daten in Anmeldeinformationen und Attribute verantwortlich, die AEM für die Benutzersynchronisierung verwenden kann.

Erstellen eines benutzerdefinierten UserInfoProcessor when-to-create-custom-userinfoprocessor

Der standardmäßige SlingUserInfoProcessorImpl verarbeitet OIDC-Standardansprüche und Gruppensynchronisierung. Möglicherweise benötigen Sie eine benutzerdefinierte Implementierung, wenn Sie Folgendes tun müssen:

Grundlegendes zur Benutzeroberfläche von UserInfoProcessor understanding-userinfoprocessor-interface

Die UserInfoProcessor aus dem org.apache.sling.auth.oauth_client.spi definiert zwei Methoden:

public interface UserInfoProcessor {
    /**
     * Process the UserInfo and token response to create OIDC credentials
     *
     * @param userInfo - JSON response from the UserInfo endpoint (may be null)
     * @param tokenResponse - JSON response from the token endpoint
     * @param oidcSubject - The subject claim from the ID token
     * @param idp - The configured IDP name
     * @return OidcAuthCredentials containing user attributes and group memberships
     */
    @NotNull OidcAuthCredentials process(
        @Nullable String userInfo,
        @NotNull String tokenResponse,
        @NotNull String oidcSubject,
        @NotNull String idp
    );

    /**
     * @return The name of the OIDC connection this processor is associated with
     */
    @NotNull String connection();
}

Mit dem zurückgegebenen OidcAuthCredentials können Sie:

Beispiel: Benutzerdefinierte UserInfoProcessor-Implementierung custom-userinfoprocessor-implementation

Im Folgenden finden Sie ein vollständiges Beispiel für die Implementierung eines benutzerdefinierten UserInfoProcessor:

package com.mycompany.aem.auth;

import java.nio.charset.StandardCharsets;
import java.util.Base64;

import org.apache.sling.auth.oauth_client.spi.OidcAuthCredentials;
import org.apache.sling.auth.oauth_client.spi.UserInfoProcessor;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
import org.osgi.service.component.annotations.Activate;
import org.osgi.service.component.annotations.Component;
import org.osgi.service.metatype.annotations.AttributeDefinition;
import org.osgi.service.metatype.annotations.Designate;
import org.osgi.service.metatype.annotations.ObjectClassDefinition;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;

/**
 * Custom UserInfoProcessor that extracts additional claims from the ID token
 * and adds custom user attributes and group memberships.
 */
@Component(service = UserInfoProcessor.class, property = {"service.ranking:Integer=50"})
@Designate(ocd = CustomUserInfoProcessor.Config.class, factory = true)
public class CustomUserInfoProcessor implements UserInfoProcessor {

    private static final Logger logger = LoggerFactory.getLogger(CustomUserInfoProcessor.class);

    @ObjectClassDefinition(name = "Custom UserInfo Processor")
    @interface Config {
        @AttributeDefinition(name = "Connection Name", description = "OIDC Connection Name")
        String connection();
    }

    private final String connection;

    @Activate
    public CustomUserInfoProcessor(Config config) {
        this.connection = config.connection();
        logger.info("CustomUserInfoProcessor activated for connection: {}", connection);
    }

    @Override
    public @NotNull OidcAuthCredentials process(
            @Nullable String userInfo,
            @NotNull String tokenResponse,
            @NotNull String oidcSubject,
            @NotNull String idp) {

        // Parse the token response to extract tokens
        JsonObject tokenJson = JsonParser.parseString(tokenResponse).getAsJsonObject();
        String accessToken = tokenJson.has("access_token") ?
            tokenJson.get("access_token").getAsString() : null;
        String idToken = tokenJson.has("id_token") ?
            tokenJson.get("id_token").getAsString() : null;

        logger.debug("Processing authentication for subject: {}", oidcSubject);

        // Decode and extract claims from ID Token
        JsonObject claims = null;
        if (idToken != null) {
            claims = decodeJwtPayload(idToken);
            logger.debug("Extracted claims from ID token: {}", claims);
        }

        // Create credentials object
        OidcAuthCredentials credentials = new OidcAuthCredentials(oidcSubject, idp);
        credentials.setAttribute(".token", "");

        // Extract standard profile attributes
        if (claims != null) {
            // Standard OIDC claims
            setAttributeIfPresent(credentials, claims, "given_name", "profile/given_name");
            setAttributeIfPresent(credentials, claims, "family_name", "profile/family_name");
            setAttributeIfPresent(credentials, claims, "email", "profile/email");
            setAttributeIfPresent(credentials, claims, "name", "profile/name");

            // Custom claims from your IdP
            setAttributeIfPresent(credentials, claims, "department", "profile/department");
            setAttributeIfPresent(credentials, claims, "employee_id", "profile/employeeId");
            setAttributeIfPresent(credentials, claims, "job_title", "profile/jobTitle");
        }

        // Extract group memberships from claims
        if (claims != null && claims.has("groups")) {
            if (claims.get("groups").isJsonArray()) {
                claims.get("groups").getAsJsonArray().forEach(group -> {
                    credentials.addGroup(group.getAsString());
                });
            }
        }

        // Optionally store tokens if needed for later API calls
        // Note: Only store tokens if your application needs to call external APIs
        // on behalf of the user. Tokens are encrypted before storage.
        if (accessToken != null) {
            credentials.setAttribute("access_token", accessToken);
        }

        return credentials;
    }

    @Override
    public @NotNull String connection() {
        return connection;
    }

    /**
     * Helper method to set attribute if present in claims
     */
    private void setAttributeIfPresent(OidcAuthCredentials credentials,
                                      JsonObject claims,
                                      String claimName,
                                      String attributeName) {
        if (claims.has(claimName) && !claims.get(claimName).isJsonNull()) {
            String value = claims.get(claimName).getAsString();
            if (value != null && !value.isEmpty()) {
                credentials.setAttribute(attributeName, value);
            }
        }
    }

    /**
     * Decode JWT payload (middle part) to extract claims
     */
    private JsonObject decodeJwtPayload(String jwt) {
        try {
            String[] parts = jwt.split("\\.");
            if (parts.length != 3) {
                logger.warn("Invalid JWT format");
                return null;
            }

            // Decode the payload (second part)
            String payload = parts[1];
            // Add padding if needed
            payload = payload + "====".substring(0, (4 - payload.length() % 4) % 4);
            // Replace URL-safe characters
            payload = payload.replace('-', '+').replace('_', '/');

            byte[] decoded = Base64.getDecoder().decode(payload);
            String json = new String(decoded, StandardCharsets.UTF_8);
            return JsonParser.parseString(json).getAsJsonObject();
        } catch (Exception e) {
            logger.error("Failed to decode JWT payload", e);
            return null;
        }
    }
}

Konfiguration custom-userinfoprocessor-configuration

Erstellen Sie unter eine Konfigurationsdatei für Ihre benutzerdefinierte UserInfoProcessor in Ihrem AEM-Projektui.config/src/main/content/jcr_root/apps/myapp/osgiconfig/config.publish/

com.mycompany.aem.auth.CustomUserInfoProcessor~azure.cfg.json

{
  "connection": "azure"
}

Die Konfiguration muss mit dem Verbindungsnamen übereinstimmen, der in Ihrer OidcConnectionImpl-Konfiguration definiert ist. Die service.ranking-Eigenschaft in der @Component (im Beispiel auf 50 gesetzt) bestimmt die Priorität, wenn mehrere Prozessoren für dieselbe Verbindung registriert sind. Höhere Rankings haben Vorrang vor dem standardmäßigen SlingUserInfoProcessorImpl (der ein Ranking von 0 hat).

Abhängigkeiten custom-userinfoprocessor-dependencies

Fügen Sie die folgenden Abhängigkeiten zum pom.xml Ihres Kernmoduls hinzu:

<dependency>
    <groupId>org.apache.sling</groupId>
    <artifactId>org.apache.sling.auth.oauth-client</artifactId>
    <version>0.1.7</version>
    <scope>provided</scope>
</dependency>
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.8.9</version>
    <scope>provided</scope>
</dependency>

Synchronisieren von Attributen mit DefaultSyncHandler synchronizing-custom-attributes

Um sicherzustellen, dass Ihre benutzerdefinierten Attribute auf Benutzerknoten im JCR beibehalten werden, aktualisieren Sie Ihre DefaultSyncHandler-Konfiguration, um Eigenschaftszuordnungen einzuschließen:

org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler~azure.cfg.json

{
  "user.expirationTime": "1h",
  "user.membershipExpTime": "1h",
  "user.propertyMapping": [
    "profile/givenName=profile/given_name",
    "profile/familyName=profile/family_name",
    "rep:fullname=profile/name",
    "profile/email=profile/email",
    "profile/department=profile/department",
    "profile/employeeId=profile/employeeId",
    "profile/jobTitle=profile/jobTitle",
    "access_token=access_token"
  ],
  "user.pathPrefix": "azure",
  "handler.name": "azure"
}

Das Format lautet jcrPropertyPath=credentialAttributeName. Auf der linken Seite wird die Eigenschaft im Benutzerknoten unter /home/users gespeichert, und auf der rechten Seite wird der Attributname angezeigt, den Sie im UserInfoProcessor mithilfe von credentials.setAttribute() festgelegt haben.

Bereitstellung und Tests custom-userinfoprocessor-deployment

Best Practices custom-userinfoprocessor-best-practices

Konfigurieren von ACL für externe Gruppen configure-acl-for-external-groups

Wenn Benutzer über OIDC authentifiziert werden, werden ihre Gruppenmitgliedschaften normalerweise mit dem externen Identitätsanbieter synchronisiert.
Diese externen Gruppen werden dynamisch im AEM-Repository erstellt, aber nicht automatisch mit Zugriffssteuerungseinträgen verknüpft.
Um sicherzustellen, dass Benutzende über die entsprechenden Berechtigungen verfügen, müssen für diese Gruppen explizit Zugriffssteuerungslisten (ACLs) definiert werden.

Es stehen zwei Hauptansätze zur Verfügung.

Option 1 — Lokale Gruppen

Die externe Gruppe kann als Mitglied einer lokalen Gruppe hinzugefügt werden, die bereits über die erforderlichen ACLs verfügt.

Option 2 - Direkte ACLs für externe Gruppen über RepoInit

ACLs können mithilfe von RepoInit-Skripten direkt auf externe Gruppen angewendet werden.

Beispiel: Konfigurieren der OIDC-Authentifizierung mit Azure Active Directory

Konfigurieren einer neuen Anwendung in Azure Active Directory configure-a-new-application-in-azure-ad

org.apache.sling.auth.oauth_client.impl.OidcConnectionImpl~azure.cfg.json

{
  "name":"azure",
  "scopes":[
    openid", "User.Read", "profile", "email"
  ],
  "baseUrl":"https://login.microsoftonline.com/tenant-id/v2.0",
  "clientId":"client-id",
  "clientSecret":"secret"
}

org.apache.sling.auth.oauth_client.impl.OidcAuthenticationHandler~azure.cfg.json

{
  "callbackUri":"https://www.mywebsite.com/content/wknd/us/en/adventures/j_security_check",
  "path":[
    "/content/wknd/us/en/adventures"
  ],
  "idp":"azure",
  "defaultConnectionName":"azure"
}

org.apache.jackrabbit.oak.spi.security.authentication.external.impl.ExternalLoginModuleFactory~azure.cfg.json

{
  "sync.handlerName":"azure",
  "idp.name":"azure"
}

org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler~azure.cfg.json

{
  "user.expirationTime":"1h",
  "user.membershipExpTime":"1h",
  "group.expirationTime": "1d"
  "user.propertyMapping":[
    "profile/givenName=profile/given_name",
    "profile/familyName=profile/family_name",
    "rep:fullname=profile/name",
    "profile/email=profile/email",
    "access_token=access_token",
    "refresh_token=refresh_token"
  ],
  "user.pathPrefix":"azure",
  "group.pathPrefix": "oidc",
  "user.membershipNestingDepth": "1",
  "handler.name":"azure"
}

org.apache.sling.jcr.repoinit.RepositoryInitializer~azure.cfg.json

{
  "scripts":[
    "set ACL for \"adventures;azure\"  (ACLOptions=ignoreMissingPrincipal)\r\n  allow jcr:read on /content/wknd/us/en/adventures\r\nend"
  ]
}

org.apache.sling.auth.oauth_client.impl.SlingUserInfoProcessorImpl~azure.cfg.json

{
  "groupsInIdToken": "true",
  "storeAccessToken": "false",
  "storeRefreshToken": "false",
  "connection": "azure",
  "groupsClaimName": "groups"
}

Zusätzliche Informationen zu Azure AD-Gruppen additional-information-about-azure-ad-groups

Um eine Gruppe für die Enterprise-Anwendung im Microsoft Azure-Portal zu konfigurieren, müssen Sie die Anwendung nach Enterprise-Anwendungen durchsuchen und die Gruppen hinzufügen:

Um die Gruppenanforderung im ID-Token zu aktivieren, fügen Sie die Anforderung im Abschnitt Tokenkonfiguration des Microsoft Azure-Portals hinzu:

Die Konfiguration von SlingUserInfoProcessor muss wie im folgenden Beispiel geändert werden.

Der Dateiname, der geändert werden muss, ist org.apache.sling.auth.oauth_client.impl.SlingUserInfoProcessorImpl.cfg.json. Der Inhalt muss wie folgt konfiguriert werden:

{
  "connection": "azure",
  "groupsInIdToken": "true",
  "storeAccessToken": "false",
  "storeRefreshToken": "false"
}

Benutzerdefinierte Weiterleitung nach der Authentifizierung custom-redirect-after-authentication

Standardmäßig werden Benutzer nach erfolgreicher OIDC-Authentifizierung zurück zur ursprünglich angeforderten URL geleitet. Sie können dieses Verhalten jedoch mithilfe des redirect Abfrageparameters anpassen.

Verwenden des Weiterleitungsparameters

Beim Initiieren der Authentifizierung können Sie eine benutzerdefinierte Umleitungs-URL angeben, indem Sie den redirect-Parameter zu Ihrer Authentifizierungsanfrage hinzufügen:

/content/wknd/us/en/adventures?redirect=/content/wknd/us/en/welcome

In diesem Beispiel wird der Benutzer nach erfolgreicher Authentifizierung an /content/wknd/us/en/welcome anstelle der ursprünglich angeforderten Seite weitergeleitet.

Sicherheitsbeschränkungen

Aus Sicherheitsgründen hat der redirect-Parameter die folgenden Einschränkungen:

Wenn eine ungültige Umleitungs-URL angegeben wird, schlägt die Authentifizierung mit einem Fehler fehl.

Beispiel-Anwendungsfälle

Migration vom SAML-Authentifizierungs-Handler zum OIDC-Authentifizierungs-Handler

Wenn AEM bereits mit einem SAML-Authentifizierungs-Handler konfiguriert ist und Benutzende mit aktivierter Datensynchronisierung im Repository vorhanden sind, können Konflikte zwischen den ursprünglichen SAML-Benutzenden und den neuen OIDC-Benutzenden auftreten.