Supporto OpenID Connect per AEM as a Cloud Service sul livello di pubblicazione open-id-connect-support-for-aem-as-a-cloud-service-on-publish-tier

Introduzione introduction

Man mano che le organizzazioni modernizzano le proprie esperienze digitali, la gestione delle identità sicura e scalabile diventa un requisito fondamentale. Adobe Experience Manager (AEM) Cloud Service ora supporta OpenID Connect (OIDC) sul livello di pubblicazione, che consente un’integrazione fluida e basata su standard con i principali provider di identità (IdP) come Entra ID (Azure AD), Google, Okta, Auth0, Ping Identity, ForgeRock e gli IDP supportati da OIDC.

OIDC è un livello di identità sopra il protocollo OAuth 2.0 che consente una solida autenticazione utente mantenendo al contempo la semplicità per gli sviluppatori. È ampiamente adottato per scenari business-to-consumer (B2C), Intranet e portale partner, in cui sono necessari account utente sicuri e federazioni di identità.

Finora, i clienti di AEM erano responsabili dell’implementazione della propria logica di accesso personalizzata sul livello di pubblicazione, che ha aumentato i tempi di sviluppo e introdotto problemi di manutenzione e sicurezza a lungo termine. Con il supporto nativo per OIDC, AEM Cloud Service rimuove questo carico fornendo un meccanismo di autenticazione sicuro, estensibile e supportato da Adobe per gli utenti finali che accedono agli ambienti di pubblicazione.

Che tu stia distribuendo un sito web consumer personalizzato o un portale interno autenticato, OIDC on Publish semplifica la federazione delle identità e riduce i rischi tramite la governance centralizzata delle identità. Consente inoltre alle organizzazioni di soddisfare i moderni standard di conformità e sicurezza senza sacrificare l’agilità.

Configurare AEM per l’autenticazione OIDC configure-aem-oidc-authentication

Prerequisiti prerequisits

Si presuppone che siano disponibili o definite le seguenti informazioni:

Informazioni dalla configurazione IdP:

Panoramica dei file di configurazione overview-of-the-configuration-files

Di seguito è riportato un elenco di file da configurare:

Il diagramma seguente mostra come vengono collegati gli elementi di configurazione menzionati. Poiché si tratta di componenti ServiceFactory, ~uniqueid può essere una qualsiasi stringa univoca casuale:

Configurare la connessione OIDC configure-the-oidc-connection

Per prima cosa, è necessario configurare la connessione OIDC. È possibile configurare più connessioni OIDC, ognuna delle quali deve avere un nome diverso.

In alcuni ambienti, il provider di identità (IdP) potrebbe non esporre un endpoint .well-known valido.
In questo caso, gli endpoint richiesti possono essere definiti manualmente specificando le seguenti proprietà nel file di configurazione.
In questa modalità di configurazione, la proprietà baseUrl non deve essere impostata.

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

Configurare il Gestore autenticazione OIDC configure-oidc-authentication-handler

Ora configura il gestore di autenticazione OIDC. È possibile configurare più connessioni OIDC. Ognuna deve avere un nome diverso. Se condividono lo stesso Provider di identità esterno OAK, possono condividere gli utenti.

Configurare SlingUserInfoProcessor configure-slinguserinfoprocessor

Configurare il gestore di sincronizzazione configure-the-synchronization-handler

È necessario configurare almeno un gestore di sincronizzazione per sincronizzare gli utenti autenticati in oak. Per ulteriori dettagli, consulta questa pagina.

Crea un file denominato org.apache.jackrabbit.oak.spi.security.authentication.external.impl.DefaultSyncHandler~azure.cfg.json. Il suffisso azure deve essere un identificatore univoco. Per ulteriori informazioni su come configurarne le proprietà, consulta la documentazione sulla sincronizzazione di utenti e gruppi di Oak. Di seguito trovi un esempio di configurazione:

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

Durante lo sviluppo, i tempi di scadenza possono essere ridotti a un valore inferiore (ad esempio: 1 s) per velocizzare il test della sincronizzazione di utenti e gruppi in oak.
Di seguito sono riportati alcuni degli attributi più rilevanti da configurare in DefaultSyncHandler. Tieni presente che l’Iscrizione al gruppo dinamico deve essere sempre abilitata nei Cloud Service.

Configurare il Modulo di accesso esterno configure-the-external-login-module

Infine, devi configurare il Modulo di accesso esterno.

Facoltativo: implementa un UserInfoProcessor personalizzato implement-a-custom-userinfoprocessor

L’utente è autenticato da un token ID e gli attributi aggiuntivi vengono recuperati dall’endpoint userInfo definito per l’IdP. UserInfoProcessor è responsabile della trasformazione dei dati ricevuti dal provider di identità in credenziali e attributi che AEM può utilizzare per la sincronizzazione degli utenti.

Quando creare un UserInfoProcessor personalizzato when-to-create-custom-userinfoprocessor

Il SlingUserInfoProcessorImpl predefinito gestisce le attestazioni OIDC standard e la sincronizzazione dei gruppi. Potresti aver bisogno di un’implementazione personalizzata per:

Informazioni sull’interfaccia UserInfoProcessor understanding-userinfoprocessor-interface

L’interfaccia UserInfoProcessor del pacchetto org.apache.sling.auth.oauth_client.spi definisce due metodi:

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();
}

L’oggetto OidcAuthCredentials restituito consente di:

Esempio: implementazione personalizzata di UserInfoProcessor custom-userinfoprocessor-implementation

Di seguito è riportato un esempio completo che mostra come implementare un UserInfoProcessor personalizzato:

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

Configurazione custom-userinfoprocessor-configuration

Crea un file di configurazione per UserInfoProcessor personalizzato nel progetto AEM in ui.config/src/main/content/jcr_root/apps/myapp/osgiconfig/config.publish/:

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

{
  "connection": "azure"
}

La configurazione deve corrispondere al nome della connessione definito nella configurazione OidcConnectionImpl. La proprietà service.ranking nell’annotazione @Component (impostata su 50 nell’esempio) determina la priorità se più processori sono registrati per la stessa connessione. Le classificazioni superiori hanno la precedenza rispetto a SlingUserInfoProcessorImpl (che ha una classificazione di 0) predefinito.

Dipendenze custom-userinfoprocessor-dependencies

Aggiungi le dipendenze seguenti a pom.xml del modulo core:

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

Sincronizzazione degli attributi con DefaultSyncHandler synchronizing-custom-attributes

Per garantire che gli attributi personalizzati vengano mantenuti nei nodi utente nel JCR, aggiorna la configurazione DefaultSyncHandler per includere le mappature delle proprietà:

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

Il formato è jcrPropertyPath=credentialAttributeName. Il lato sinistro è il punto in cui la proprietà viene memorizzata nel nodo utente in /home/users e il lato destro corrisponde al nome dell’attributo impostato in UserInfoProcessor utilizzando credentials.setAttribute().

Distribuzione e test custom-userinfoprocessor-deployment

Best practice custom-userinfoprocessor-best-practices

Configurare ACL per gruppi esterni configure-acl-for-external-groups

Quando gli utenti vengono autenticati tramite OIDC, le appartenenze ai loro gruppi vengono in genere sincronizzate dal provider di identità esterno.
Questi gruppi esterni vengono creati in modo dinamico nell’archivio di AEM, ma non vengono associati automaticamente ad alcuna voce di controllo di accesso.
Per garantire che gli utenti dispongano delle autorizzazioni appropriate, è necessario definire in modo esplicito gli elenchi di controllo di accesso (ACL, Access Control List) per questi gruppi.

Sono disponibili due approcci primari.

Opzione 1 — Gruppi locali

Il gruppo esterno può essere aggiunto come membro di un gruppo locale che dispone già degli ACL richiesti.

Opzione 2 — ACL diretti su gruppi esterni tramite RepoInit

Gli ACL possono essere applicati direttamente ai gruppi esterni utilizzando gli script RepoInit.

Esempio: configurare l’autenticazione OIDC con Azure Active Directory

Configurare una nuova applicazione 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"
}

Informazioni aggiuntive sui gruppi di Azure AD additional-information-about-azure-ad-groups

Per configurare un gruppo per l’applicazione enterprise nel portale di Microsoft Azure, è necessario cercare l’applicazione in Applicazioni enterprise e aggiungere i gruppi:

Per abilitare l’attestazione di gruppo nel token ID, aggiungi l’attestazione nella sezione Configurazione token del portale di Microsoft Azure:

La configurazione di SlingUserInfoProcessor deve essere modificata come nell’esempio seguente.

Il nome file da modificare è org.apache.sling.auth.oauth_client.impl.SlingUserInfoProcessorImpl.cfg.json. Il contenuto deve essere configurato come segue:

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

Reindirizzamento personalizzato dopo l’autenticazione custom-redirect-after-authentication

Per impostazione predefinita, una volta completata l’autenticazione OIDC, gli utenti vengono reindirizzati all’URL richiesto originariamente. Tuttavia, è possibile personalizzare questo comportamento utilizzando il parametro di query redirect.

Utilizzo del parametro di reindirizzamento

Quando si avvia l’autenticazione, è possibile specificare un URL di reindirizzamento personalizzato aggiungendo il parametro redirect alla richiesta di autenticazione:

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

In questo esempio, dopo l’autenticazione riuscita, l’utente verrà reindirizzato a /content/wknd/us/en/welcome anziché alla pagina richiesta originariamente.

Vincoli di sicurezza

Per motivi di sicurezza, il parametro redirect presenta le seguenti restrizioni:

Se viene fornito un URL di reindirizzamento non valido, l’autenticazione non riuscirà e verrà restituito un errore.

Casi d’uso di esempio

Come migrare dal gestore di autenticazione Saml al gestore di autenticazione Oidc

Quando AEM è già configurato con un gestore di autenticazione SAML e gli utenti sono presenti nel repository con sincronizzazione dati abilitata, possono verificarsi conflitti tra gli utenti SAML originali e i nuovi utenti OIDC.