Skip to main content
Version: Current

Troubleshooting: Entra ID SSO/Provisioning Setup Problems

Problem​

You are encountering issues while configuring or using Microsoft Entra ID (formerly Azure AD) for Single Sign-On (SSO) or User Provisioning with Zudello.

Examples:

  • Users receive errors when trying to log in via SSO.
  • Users added to the Entra ID group are not being created or activated in Zudello.
  • User details (name, manager) are not syncing correctly.
  • Configuration validation fails in Zudello or Entra ID.

Common Causes​

  1. Incorrect Configuration in Entra ID:
    • Wrong Application (client) ID or Directory (tenant) ID used.
    • Incorrect Client Secret value entered, or secret has expired.
    • Incorrect Zudello callback URL (https://auth.[cluster].zudello.io/ui/login/login/externalidp/callback) configured in App Registration Redirect URIs.
    • Required API Permissions (Microsoft Graph: email, profile, User.Read, openid) not granted or consented to.
    • Optional Claims (email, family_name, given_name, preferred_username for ID token) not added.
    • User not assigned to the Zudello application in Entra ID Enterprise Applications.
    • For Provisioning: Incorrect SCIM endpoint URL or Secret Token used in Entra ID Provisioning settings.
  2. Incorrect Configuration in Zudello:
    • Wrong Client ID, Client Secret, or Tenant ID entered in Organisation Settings > SSO & User Provisioning > Microsoft Entra.
    • Incorrect Entra ID Group Name or ID specified for provisioning.
    • Incorrect Zudello Team(s) selected for provisioning.
    • "User Provisioning" toggle not enabled when expected.
    • "Link Manager" toggle enabled, but manager attributes not syncing correctly from Entra ID or manager doesn't exist in Zudello.
  3. User Data Mismatches: Email address mismatch between Entra ID and an existing Zudello user prevents automatic linking during the first SSO login.
  4. Timing/Sync Delays: User provisioning syncs run on a schedule (e.g., every 10-40 minutes). Changes in Entra ID group membership may take time to reflect in Zudello. Manager/attribute updates often sync less frequently (e.g., nightly).
  5. Zitadel Configuration Issues (Staff Task): Problems with the underlying Identity Provider configuration in Zudello's authentication service (Zitadel).

Troubleshooting Steps​

  1. Verify Entra ID App Registration:
    • Go to Entra ID > App registrations. Find the Zudello app.
    • Double-check the Application (client) ID and Directory (tenant) ID match what's configured in Zudello.
    • Go to Certificates & secrets. Generate a new Client secret if expired or unsure, and update it in Zudello.
    • Go to Authentication. Ensure the Redirect URI for Web matches the Zudello callback URL exactly (https://auth.[cluster].zudello.io/ui/login/login/externalidp/callback).
    • Go to Token configuration. Ensure the required Optional Claims (email, family_name, given_name, preferred_username) are added for the ID token type.
    • Go to API permissions. Verify the required Microsoft Graph permissions (email, profile, User.Read, openid) are present and have admin consent granted.
  2. Verify Entra ID Enterprise Application:
    • Go to Entra ID > Enterprise applications. Find the Zudello app.
    • Go to Users and groups. Ensure the users/groups who need access are assigned.
    • (Provisioning Only): Go to Provisioning.
      • Check the Provisioning Status (should be On).
      • Verify the Admin Credentials (Tenant URL - Zudello SCIM endpoint, Secret Token). Test Connection.
      • Review Mappings. Ensure attributes like userPrincipalName, givenName, surname, manager are mapped correctly.
      • Check Provisioning Logs for specific errors.
  3. Verify Zudello Configuration:
    • Go to Organisation Settings > SSO & User Provisioning. Edit the Microsoft Entra configuration.
    • Double-check the Client ID, Client Secret, and Tenant ID.
    • (Provisioning Only): Verify the Entra ID Group Name/ID and selected Zudello Teams. Ensure the User Provisioning toggle is ON if required. Check the Link Manager setting.
  4. Check User Data: For linking issues on first SSO login, ensure the user's primary email in Entra ID matches their Zudello user email exactly.
  5. Wait for Sync: Allow time for provisioning sync cycles to complete after adding/removing users from the Entra ID group.
  6. Manual Sync (Provisioning): Use the Advanced > Synchronise Users option in Zudello's Entra configuration to trigger an immediate sync for user attributes (like manager, name updates).
  7. Check Zitadel (Staff Task): Zudello staff can verify the Identity Provider configuration within the organisation's Zitadel instance.

Need Help?​

Setting up SSO and provisioning involves multiple steps. If issues persist, contact Zudello support. Provide:

  • Screenshots of your Entra ID App Registration settings (Overview, Authentication, Token configuration, API permissions).
  • Screenshots of your Entra ID Enterprise Application settings (Users and groups, Provisioning logs if applicable).
  • Screenshots of your Zudello SSO & User Provisioning configuration.
  • Specific error messages encountered by users or shown in logs.