Migration vers une identité externe et l’appartenance à un groupe dynamique migrating-to-external-identity

Vue d’ensemble overview

Lorsque la synchronisation des données est activée dans AEM as a Cloud Service, le gestionnaire d’authentification SAML peut être configuré pour migrer automatiquement vers des identités externes avec appartenance à un groupe dynamique lorsqu’il gère la création d’utilisateurs et de groupes. Si votre projet utilise du code personnalisé pour créer des utilisateurs ou des groupes, vous devez le mettre à jour pour créer des utilisateurs et des groupes externes, par opposition aux utilisateurs et groupes locaux.

Pourquoi des utilisateurs et des groupes externes sont-ils requis ? why-external-required

La migration des utilisateurs et groupes locaux vers des identités externes avec appartenance à un groupe dynamique est essentielle pour plusieurs raisons essentielles :

Optimisation des performances :

Ce document fournit des conseils techniques pour :

Compréhension de l’identité externe understanding-external-identity

External Users external-users

Les utilisateurs externes sont identifiés par la propriété rep:externalId , qui lie l’utilisateur à un fournisseur d’identité externe. Le format est :

userId;idpName

Par exemple : john.doe;saml-idp.

Propriétés de la clé :

Groupes externes external-groups

Les groupes externes sont également identifiés par la propriété rep:externalId et utilisent un format de nom principal :

groupId;idpName

Par exemple : content-authors;saml-idp

Appartenance à un groupe dynamique dynamic-group-membership

Au lieu de relations directes utilisateur à groupe stockées dans le référentiel, l’appartenance à un groupe dynamique utilise la propriété rep:externalPrincipalNames sur le nœud utilisateur . Lorsque l’utilisateur possède un nom principal externe correspondant à l’ID d’un groupe externe, il devient automatiquement membre de ce groupe. Pour plus d’informations, consultez la documentation d’Apache Oak.

Avantages :

Configuration de l’utilisateur du service service-user-configuration

Toutes les opérations qui créent ou modifient des utilisateurs et des groupes externes doivent être effectuées à l’aide d’un utilisateur de service correctement configuré pour contourner la protection par défaut sur les propriétés rep:externalId et rep:externalPrincipalNames.

Pourquoi un utilisateur du service est-il requis ? why-is-a-service-user-required

Par défaut, la sécurité d’Oak empêche les sessions régulières de modifier les propriétés protégées telles que :

Seul un utilisateur de service correctement configuré peut modifier ces propriétés.

Configuration et mappage des utilisateurs de services service-user-configuration-mapping

La configuration d’un utilisateur de service pour gérer les identités externes nécessite trois configurations coordonnées :

Consultez ci-dessous une description détaillée de ces étapes.

Étape 1 : créer l’utilisateur du service via Repoinit create-the-serviice-user-via-repoinit

Cette étape décrit la création de l’utilisateur du service avec les autorisations nécessaires à l’aide d’un script repoinit.

Fichier de configuration : org.apache.sling.jcr.repoinit.RepositoryInitializer~group-provisioner.cfg.json

Emplacement exemplaire : ui.config/src/main/content/jcr_root/apps/yourproject/osgiconfig/config.publish/

{
  "scripts": [
    "create service user group-provisioner with path system/yourproject",
    "set ACL for group-provisioner\n  allow jcr:read,jcr:readAccessControl,jcr:modifyAccessControl,rep:userManagement,rep:write on /home/users\n  allow jcr:read,jcr:readAccessControl,jcr:modifyAccessControl,rep:userManagement,rep:write on /home/groups\nend"
  ]
}

Présentation des autorisations

Étape 2 : Configurer la protection ExternalPrincipal configure-externalprincipal-protection

Vous trouverez ci-dessous un exemple de configuration pour placer en liste blanche l’utilisateur du service afin qu’il puisse contourner la protection appliquée aux propriétés d’identité externes.

Nom du fichier de configuration : org.apache.jackrabbit.oak.spi.security.authentication.external.impl.principal.ExternalPrincipalConfiguration.cfg.json

Exemple d’emplacement : ui.config/src/main/content/jcr_root/apps/yourproject/osgiconfig/config.publish/

{
  "protectExternalIdentities": "Warn",
  "systemPrincipalNames": [
    "group-provisioner",
    "saml-migration-service"
  ]
}

Propriétés de configuration :

Étape 3 : Mappage des utilisateurs du service service-user-mapping

Mappez l’utilisateur du service à votre lot d’applications afin que votre code puisse l’utiliser.

Fichier de configuration : org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended~group-provisioner.cfg.json

Location: ui.config/src/main/content/jcr_root/apps/yourproject/osgiconfig/config.publish/

{
  "user.mapping": [
    "yourproject.core:group-provisioner=[group-provisioner]"
  ]
}

Format de mappage :

Utilisation de l’utilisateur du service dans le code using-the-service-user-in-code

Lors de l’ouverture d’une session pour effectuer des opérations de migration ou de création d’utilisateurs/groupes, vous devez utiliser l’utilisateur du service :

import org.apache.sling.jcr.api.SlingRepository;

@Reference
private SlingRepository repository;

// Login as the service user
Session serviceSession = repository.loginService("group-provisioner", null);

try {
    UserManager userManager = ((JackrabbitSession) serviceSession).getUserManager();
    // Perform operations...
    serviceSession.save();
} finally {
    if (serviceSession != null && serviceSession.isLive()) {
        serviceSession.logout();
    }
}

Exemple de configuration complète complete-configuration-example

Vous trouverez ci-dessous un exemple complet montrant l’ensemble des trois configurations :

Structure de fichier file-structure

ui.config/src/main/content/jcr_root/apps/yourproject/osgiconfig/
└── config.publish/
    ├── org.apache.sling.jcr.repoinit.RepositoryInitializer~group-provisioner.cfg.json
    ├── org.apache.jackrabbit.oak.spi.security.authentication.external.impl.principal.ExternalPrincipalConfiguration.cfg.json
    └── org.apache.sling.serviceusermapping.impl.ServiceUserMapperImpl.amended~group-provisioner.cfg.json

Modification du code personnalisé modifying-custom-code

Création d’utilisateurs externes creating-external-users

Before (Local User) :

UserManager userManager = ((JackrabbitSession) session).getUserManager();
User user = userManager.createUser(userId, password);

Après (Utilisateur Externe) :

import org.apache.jackrabbit.oak.spi.security.authentication.external.ExternalIdentityRef;

UserManager userManager = ((JackrabbitSession) session).getUserManager();
ValueFactory valueFactory = session.getValueFactory();

// Create user with principal
Principal userPrincipal = new Principal() {
    @Override
    public String getName() {
        return userId;
    }
};

User user = userManager.createUser(userId, null, userPrincipal, null);

// Set rep:externalId
ExternalIdentityRef externalRef = new ExternalIdentityRef(userId, idpName);
String externalId = externalRef.getString(); // Format: userId;idpName
user.setProperty("rep:externalId", valueFactory.createValue(externalId));

// Set sync timestamps to far future (workaround for OAK-12079)
// Set to 10 years in the future to prevent premature cleanup of external group memberships
// See: https://issues.apache.org/jira/browse/OAK-12079
java.util.Calendar future = java.util.Calendar.getInstance();
future.add(java.util.Calendar.YEAR, 10);
user.setProperty("rep:lastSynced", valueFactory.createValue(future));
user.setProperty("rep:lastDynamicSync", valueFactory.createValue(future));

session.save();

Création de groupes externes creating-external-groups

Before (Local Group) :

UserManager userManager = ((JackrabbitSession) session).getUserManager();
Group group = userManager.createGroup(groupId);

Après (Groupe Externe) :

import org.apache.jackrabbit.oak.spi.security.authentication.external.ExternalIdentityRef;

UserManager userManager = ((JackrabbitSession) session).getUserManager();
ValueFactory valueFactory = session.getValueFactory();

// Create group with principal
Principal groupPrincipal = new Principal() {
    @Override
    public String getName() {
        return groupId;
    }
};

Group group = userManager.createGroup(groupPrincipal);

// Set rep:externalId
ExternalIdentityRef externalRef = new ExternalIdentityRef(groupId, idpName);
String externalId = externalRef.getString(); // Format: groupId;idpName
group.setProperty("rep:externalId", valueFactory.createValue(externalId));

session.save();

Attribution d’une appartenance à un groupe dynamique assigning-dynamic-membership

Before (Direct Membership) :

Group group = (Group) userManager.getAuthorizable(groupId);
User user = (User) userManager.getAuthorizable(userId);
group.addMember(user);

Après (Abonnement Dynamique) :

User user = (User) userManager.getAuthorizable(userId);
ValueFactory valueFactory = session.getValueFactory();

// Get existing external principal names
Value[] existingValues = user.getProperty("rep:externalPrincipalNames");
List<String> principalNames = new ArrayList<>();

if (existingValues != null) {
    for (Value value : existingValues) {
        principalNames.add(value.getString());
    }
}

// Add new principal name (format: groupId;idpName)
String dynamicGroupPrincipal = groupId + ";" + idpName;
if (!principalNames.contains(dynamicGroupPrincipal)) {
    principalNames.add(dynamicGroupPrincipal);

    // Create new Value array
    Value[] newValues = new Value[principalNames.size()];
    for (int i = 0; i < principalNames.size(); i++) {
        newValues[i] = valueFactory.createValue(principalNames.get(i));
    }

    // Set the property
    user.setProperty("rep:externalPrincipalNames", newValues);

    // Update sync timestamps to far future (workaround for OAK-12079)
    // Set to 10 years in the future to prevent premature cleanup of external group memberships
    // See: https://issues.apache.org/jira/browse/OAK-12079
    java.util.Calendar future = java.util.Calendar.getInstance();
    future.add(java.util.Calendar.YEAR, 10);
    user.setProperty("rep:lastDynamicSync", valueFactory.createValue(future));
    user.setProperty("rep:lastSynced", valueFactory.createValue(future));
}

session.save();

Processus de migration migration-process

La migration des utilisateurs et groupes locaux existants vers l’identité externe n’est pas nécessaire lorsque le code personnalisé a été mis à jour avant l’activation des services de synchronisation des données.

Si des utilisateurs et des groupes locaux ont déjà été conservés dans le référentiel et que l’environnement est utilisé activement, nous vous recommandons d’effectuer une migration en plusieurs étapes comme celle-ci, afin d’éviter les perturbations ou les incohérences.

Étape 1 : Créer une structure de groupe externe step-1-create-external-group-structure

Pour chaque groupe local qui doit être migré :

Validation

Exemple de point d’entrée de servlet :

@SlingServletPaths("/bin/migration/step1")
public class MigrationStep1Servlet extends SlingAllMethodsServlet {

    @Override
    protected void doPost(SlingHttpServletRequest request,
                          SlingHttpServletResponse response) {
        String groupPath = request.getParameter("groupPath");
        String idpName = request.getParameter("idpName");

        // Check if the caller is authorized to run the servlet
        isAuthorizedCaller(request, response);

        // Get local group
        Authorizable localGroupAuth = userManager.getAuthorizableByPath(groupPath);
        Group localGroup = (Group) localGroupAuth;
        String localGroupId = localGroup.getID();

        // Create external group
        String externalGroupPrincipalName = localGroupId + ";" + idpName;
        // The function createExternalGroup performs the following steps:
        // 1. Creates a new external group with the given principal name (format: "<localGroupId>;<idpName>").
        // 2. Sets the 'rep:externalId' property on the group to mark it as an external group (value: "<localGroupId>;<idpName>").
        // 3. Sets the 'rep:principalName' property for the group if required.
        // 4. Assigns any other required group metadata, such as a title or description, if needed.
        // 5. Persists the new group node in the repository at the appropriate path under /home/groups.
        // 6. Returns the created Group object so it can be used for further operations, such as membership assignment.
        Group externalGroup = createExternalGroup(externalGroupPrincipalName, localGroupId, idpName);

        // Add external group to local group
        localGroup.addMember(externalGroup);

        session.save();
    }
}

Usage:

curl -X POST "http://localhost:4503/bin/migration/step1?groupPath=/home/groups/c/content-authors&idpName=saml-idp"

Étape 2 : convertir des utilisateurs et affecter une appartenance dynamique step-2-convert-users-and-assign-dynamic-membership

Pour chaque utilisateur qui est membre d’un groupe local :

Exemple de point d’entrée de servlet :

@SlingServletPaths("/bin/migration/step2")
public class MigrationStep2Servlet extends SlingAllMethodsServlet {

    @Override
    protected void doPost(SlingHttpServletRequest request,
                          SlingHttpServletResponse response) {
        String userId = request.getParameter("userId");
        String idpName = request.getParameter("idpName");

        // Check if the caller is authorized to run the servlet
        isAuthorizedCaller(request, response);

        // Login as the service user
        Session serviceSession = repository.loginService("group-provisioner", null);

        try {
            UserManager userManager = ((JackrabbitSession) serviceSession).getUserManager();
            User user = (User) userManager.getAuthorizable(userId);

            // Ensure user has rep:externalId
            Value[] externalIdValues = user.getProperty("rep:externalId");
            if (externalIdValues == null || externalIdValues.length == 0) {
                ExternalIdentityRef externalRef = new ExternalIdentityRef(userId, idpName);
                user.setProperty("rep:externalId",
                            valueFactory.createValue(externalRef.getString()));
            }

            // Get all group memberships
            Iterator<Group> groupIterator = user.declaredMemberOf();
            List<String> principalNames = new ArrayList<>();

            while (groupIterator.hasNext()) {
                Group group = groupIterator.next();
                String groupId = group.getID();

                // Skip system groups
                if ("everyone".equals(groupId)) {
                    continue;
                }

                // Add dynamic group principal
                String dynamicGroupPrincipal = groupId + ";" + idpName;
                principalNames.add(dynamicGroupPrincipal);
            }

            // Set rep:externalPrincipalNames
            if (!principalNames.isEmpty()) {
                Value[] newValues = new Value[principalNames.size()];
                for (int i = 0; i < principalNames.size(); i++) {
                    newValues[i] = valueFactory.createValue(principalNames.get(i));
                }
                user.setProperty("rep:externalPrincipalNames", newValues);
            }

            // Update timestamps to far future (workaround for OAK-12079)
            // Set to 10 years in the future to prevent premature cleanup of external group memberships
            // See: https://issues.apache.org/jira/browse/OAK-12079
            java.util.Calendar future = java.util.Calendar.getInstance();
            future.add(java.util.Calendar.YEAR, 10);
            user.setProperty("rep:lastDynamicSync", valueFactory.createValue(future));
            user.setProperty("rep:lastSynced", valueFactory.createValue(future));

        // Perform operations...
        serviceSession.save();
    } finally {
        if (serviceSession != null && serviceSession.isLive()) {
            serviceSession.logout();
        }
}    }
}

Usage:

curl -X POST "http://localhost:4503/bin/migration/step2?userId=john.doe&idpName=saml-idp"

Validation

Vous pouvez le valider en vérifiant que chaque utilisateur dispose des attributs rep:externalId et rep:externalPrincipalName avec le principalName de chaque groupe externe. Les utilisateurs sont membres des groupes locaux et des groupes externes.

Étape 3 : Supprimer les appartenances directes des utilisateurs step-3-remove-direct-user-memberships

Une fois l’appartenance à un groupe dynamique configurée pour les utilisateurs :

Exemple de point d’entrée de servlet :

@SlingServletPaths("/bin/migration/step3")
public class MigrationStep3Servlet extends SlingAllMethodsServlet {

    @Override
    protected void doPost(SlingHttpServletRequest request,
                          SlingHttpServletResponse response) {

        // Check if the caller is authorized to run the servlet
        isAuthorizedCaller(request, response);

        String groupPath = request.getParameter("groupPath");

        Authorizable localGroupAuth = userManager.getAuthorizableByPath(groupPath);
        Group localGroup = (Group) localGroupAuth;

        // Process each member
        Iterator<Authorizable> members = localGroup.getDeclaredMembers();

        while (members.hasNext()) {
            Authorizable member = members.next();

            // Remove only user members, keep group members
            if (!member.isGroup()) {
                localGroup.removeMember(member);
            }
        }

        session.save();
    }
}

Usage:

curl -X POST "http://localhost:4503/bin/migration/step3?groupPath=/home/groups/c/content-authors"

Validation

Workflow de migration migration-workflow

Liste de contrôle préalable à la migration pre-migration-checklist

Étapes d’exécution execution-steps

Validation après migration post-migration-validation

Vérifiez la migration :

Résolution des problèmes troubleshooting

Problèmes courants common-issues

Problème : erreurs d’autorisation lors de la définition de rep:externalId ou derep:externalPrincipalNames

Messages d’erreur :

Solution : la session doit être ouverte à l’aide d’un utilisateur de service correctement configuré et disposant d’autorisations lui permettant de contourner la protection sur les propriétés d’identité externes.

Étapes à résoudre :

Consultez Configuration utilisateur du service pour obtenir des instructions de configuration complètes.

Problème :OakConstraint0072: Property 'rep:externalPrincipalNames' requires 'rep:externalId' to be present

Solution : les utilisateurs doivent avoir rep:externalId définis avant de rep:externalPrincipalNames. Assurez-vous que l’étape 2 convertit d’abord les utilisateurs en utilisateurs externes.

Problème : les utilisateurs perdent leurs appartenances à un groupe après la migration

Solution : vérifiez que :

Problème : les appartenances à un groupe externe sont supprimées de manière inattendue après la connexion de l’utilisateur (OAK-12079)

Problème : en raison du bug Oak OAK-12079, le mécanisme de synchronisation d’Oak peut nettoyer prématurément les appartenances à des groupes externes en fonction des horodatages rep:lastSynced et rep:lastDynamicSync.

Solution : définissez les horodatages rep:lastSynced et rep:lastDynamicSync sur une date ultérieure éloignée (dans 10 ans) au lieu de l’heure actuelle. Cela empêche le processus de nettoyage de la synchronisation de supprimer les appartenances aux groupes externes.

Implémentation :

// Workaround for OAK-12079
// Set to 10 years in the future to prevent premature cleanup
// See: https://issues.apache.org/jira/browse/OAK-12079
java.util.Calendar future = java.util.Calendar.getInstance();
future.add(java.util.Calendar.YEAR, 10);
user.setProperty("rep:lastSynced", valueFactory.createValue(future));
user.setProperty("rep:lastDynamicSync", valueFactory.createValue(future));

Pourquoi cela fonctionne : en définissant la date et l’heure à une date ultérieure éloignée, la logique de synchronisation d’Oak traite ces utilisateurs comme « récemment synchronisés » et ne déclenche pas le processus de nettoyage qui supprimerait les noms principaux externes et les appartenances à un groupe.

Remarque : il s’agit d’une solution temporaire en attendant la résolution d’OAK-12079 dans une prochaine version d’Oak. Tous les exemples de code de ce document incluent déjà cette solution.

Problème : le groupe système « Tout le monde » provoque des erreurs

Solution : toujours ignorer le groupe système « Tout le monde » lors de la migration des utilisateurs (étape 2). Ce groupe est automatiquement géré par AEM.

Procédure de restauration rollback-procedure

Si la migration rencontre des problèmes :

Bonnes pratiques best-practices

Sécurisation des servlets de migration securing-migration-servlets

Les servlets de migration disposent de privilèges élevés pour créer et modifier des utilisateurs et des groupes. Il est essentiel de restreindre l’accès à ces points d’entrée pour empêcher tout accès non autorisé.

Approche recommandée : authentification du compte technique IMS recommended-approach-ims-technical-account

L’approche recommandée consiste à sécuriser ces servlets à l’aide de l’intégration Adobe IMS, en autorisant uniquement un compte technique autorisé à y accéder.

Étape 1 : Création d'un compte technique dans AEM Developer Console create-a-technical-account-in-aem-developer-console

Pour obtenir des instructions détaillées, voir Documentation sur la génération de jetons d’accès pour les API côté serveur.

Exemple de code pour vérifier si l’appelant est autorisé :

    private boolean isAuthorizedCaller(SlingHttpServletRequest request,
                                       SlingHttpServletResponse response) {

        Session session = request.getResourceResolver().adaptTo(Session.class);
        String callerId = session != null ? session.getUserID() : null;

        if (!ALLOWED_TECHNICAL_ACCOUNT.equals(callerId)) {
            LOG.warn("Unauthorized access attempt by user: '{}' (expected: '{}')", callerId,   ALLOWED_TECHNICAL_ACCOUNT);
            response.setStatus(SlingHttpServletResponse.SC_FORBIDDEN);
            return false;
        }

        return true;
    }

Défense en profondeur : restrictions basées sur IP defense-in-depth-ip-based-restrictions

Comme couche de sécurité supplémentaire, vous pouvez configurer des règles de réseau CDN pour restreindre l’accès aux points d’entrée de migration par adresse IP. Cela s’avère utile lorsque les migrations sont exécutées à partir d’une infrastructure connue.

Liste de contrôle de sécurité security-checklist

Avant de déployer les servlets de migration vers la production :

Ressources supplémentaires additional-resources