Auth0 Directory Sync: Resolving Group Name Collision Errors

When a group with the same name already exists in the Auth0 tenant, Auth0 Directory Sync fails with a group synchronization error. This occurs due to a name collision between groups during synchronization. Identifying the conflicting group and renaming or removing it in Auth0 or the source directory prevents the name collision, resolving the issue. When this issue occurs, the connection's scheduled Directory Sync repeatedly fails with the following error message:

An error occurred while synchronizing groups with the Auth0 Groups API. The sync will automatically retry on the next scheduled interval (if automatic synchronization is enabled). If the issue persists, contact Auth0 Support.

• Auth0 Directory Sync
• Google Workspace Connection
• Auth0 Groups API

This error occurs when Auth0 Directory Sync attempts to create or associate a group during synchronization and discovers that a group with the same name already exists in the target directory. The synchronization process fails because group names must remain unique within the Auth0 tenant.

Common scenarios that trigger this error include:

• A group with the same name exists in both the source directory and the Auth0 tenant.
• A previously deleted group's name is being reused in the source directory.
• Manual group creation in Auth0 conflicts with incoming synced groups.
• Naming conventions between the source and target directories overlap unexpectedly.

How do administrators resolve group synchronization errors?

Review the tenant logs to identify the conflicting group, locate the group in the Auth0 Dashboard, resolve the name collision, and verify the synchronization.

1. Review Tenant Logs
   1. Log in to the Auth0 Dashboard.
   2. Navigate to Logs to identify the specific group name causing the collision.
   3. Look for sync-related error entries that contain the conflicting group name.
2. Locate the Conflicting Group
   1. In the Auth0 Dashboard, go to User Management > Groups.
   2. Search for the group name identified in the logs.
   3. Note any duplicate or similarly-named groups.
3. Resolve the Name Collision by Choosing One of the Following Below
   • Option A: Rename the existing group in Auth0.
     1. Select the conflicting group.
     2. Click the edit option and change the group name to something unique.
     3. Ensure the new name doesn't conflict with any other groups.
   • Option B: Delete the existing group in Auth0.
     1. Select the conflicting group.
     2. Remove it.
        • NOTE: This may affect group memberships and permissions.
   • Option C: Rename the group in the source directory.
     1. Access the source directory system (for example, Google Workspace).
     2. Locate and rename the group to ensure uniqueness. This approach maintains Auth0 group integrity.
4. Verify Synchronization
   1. Trigger a manual Directory Sync by going to Connections and selecting the connection.
   2. Click Try Connection or use the sync trigger option if available.
   3. Alternatively, wait for the next scheduled synchronization interval.
   4. Confirm that the sync completes successfully without errors.

Review the Key Considerations and Best Practices for Group Synchronization

Review the following considerations and best practices to prevent group name collisions and ensure successful Directory Sync operations.

Key Considerations

• Group Naming: Ensure group names are unique within the Auth0 tenant and source directory before synchronizing.
• Documentation: Document any group renames or deletions for audit purposes.
• Testing: Test the synchronization in a non-production environment first, if possible.
• Timing: Manual sync triggers may take a few moments to complete; monitor the logs for confirmation.
• Support: If the issue persists after following these steps, contact Auth0 Support with the specific error message and group name from the logs.

Best Practices

• Establish a group naming convention that prevents naming conflicts.
• Regularly review synced groups to identify duplicates or orphaned groups.
• Before renaming groups, verify there are no dependent processes or integrations.
• Schedule Directory Sync during low-traffic periods to minimize impact.
• Maintain regular backups of group configurations.