Skip to main content

SCIM & SSO Configuration Common FAQ & Troubleshooting Steps

Avery
Updated

Here is the updated and expanded FAQ article, incorporating the new sections, enhancements, and title.

Troubleshooting Local Admin Access & SCIM Provisioning Conflicts

1. I enabled SSO (OIDC) and can no longer log in as my local Admin user. How do I access the local login form?

Issue:
When SSO is enabled, navigating to the root URL of your DataHub instance (e.g., https://your-instance.acryl.io/) automatically redirects you to your Identity Provider (e.g., Okta, Entra ID). This prevents access to the local username/password login form needed for the root admin account or service accounts that cannot use SSO.

Solution:
You can bypass the automatic SSO redirect by navigating directly to the /login endpoint.

  • URL: https://your-instance.acryl.io/login

This page will render the native login form, allowing you to sign in with your local administrator credentials to perform tasks such as configuring Group-to-Role mappings.

Tip: Bookmark this URL before enabling SSO to ensure you always have quick access to the native login screen.

2. How do I generate a System/Service API Token for SCIM provisioning?

Issue:
DataHub does not currently support creating "System" API keys that are independent of a specific user. However, using a personal user’s token for infrastructure setup (like SCIM) is not recommended best practice.

Recommended Workaround:
Create a dedicated "Service User" in DataHub to act as the SCIM provisioner.

  1. Create a User: Create a new user in DataHub (e.g., scim-provisioner).
  2. Assign Privileges: Grant this user the "Manage Users & Groups" privilege (or full Admin).
  3. Generate Token: You can either log in as that user and generate a token via the UI, or use GraphQL to generate a token for that user from your current admin account.

GraphQL Mutation for Token Generation:
Requires "Manage All Access Tokens" privilege.

mutation {
  createAccessToken(
    input: {
      type: PERSONAL
      actorUrn: "urn:li:corpuser:scim-provisioner" 
      duration: ONE_YEAR  # Options: ONE_MONTH, THREE_MONTHS, SIX_MONTHS, ONE_YEAR
      name: "Okta SCIM Provisioning Token"
      description: "Token used by IdP for SCIM user/group provisioning"
    }
  ) {
    accessToken
    metadata {
      id
      name
      description
    }
  }
}

3. I am receiving a "Conflict: Resource already exists" error when pushing users via SCIM. Why?

Issue:
This error occurs when the Identity Provider (IdP) attempts to provision a user via SCIM who already exists as a local user in DataHub (e.g., your local admin account). This conflict happens if either the email address or username matches an existing record.

DataHub does not currently support "Soft-Matching" or automatic linking of existing local users to incoming SCIM identities. To prevent SCIM from accidentally overwriting local admin accounts, the system rejects the request.

Solutions:

  • Option 1: Delete and Recreate (Recommended)
    1. Log in as a different Admin user.
    2. Navigate to Settings -> Users & Groups.
    3. Delete the conflicting local user (e.g., Deepak.Uppalapati@morningstar.com).
    4. Retry the push from your IdP. SCIM will recreate the user, and they will now be properly managed by SSO.
    • CAUTION: Before deleting your local user, ensure you have another valid Admin account (either local or SSO-based) to prevent locking yourself out of the instance.
    • Note: This will remove the user's history, ownerships, and custom permissions. You will need to re-assign roles after the user is recreated.
  • Option 2: Exclude User from SCIM
    If you cannot delete the local user, configure your Identity Provider (Okta/Entra) to exclude that specific user from the SCIM application assignment. You will continue to manage that specific account locally while using SCIM for all other users.

4. What happens when a user is removed from my Identity Provider? Will they be deleted from DataHub?

Issue:
Customers often ask about SCIM deprovisioning behavior and data retention.

Details:

  • Soft Deletion: When a user is unassigned from the DataHub app in your IdP, SCIM sends a deactivation request. DataHub marks the user as "Inactive" (Status: CORP_USER_STATUS_INACTIVE).
  • Access: Inactive users cannot log in.
  • Data Retention: The user is NOT hard-deleted. Their ownership history, metadata contributions, audit trail, and domain associations remain intact to preserve governance history.
  • Permanent Deletion: If you wish to permanently remove the user and their history, you must delete them manually via the DataHub UI (Settings -> Users & Groups).

5. Should I use SCIM provisioning or Just-In-Time (JIT) provisioning?

Issue:
Customers may be unsure which provisioning method best suits their needs.

Comparison:

  • Just-In-Time (JIT) Provisioning:
    • How it works: Users are auto-created the very first time they log in via SSO.
    • Pros: Simpler setup; no API tokens to manage.
    • Cons: Users are not visible in DataHub until they log in at least once; Group syncing is difficult or impossible.
  • SCIM Provisioning:
    • How it works: The IdP pushes users and groups to DataHub periodically, before they ever log in.
    • Pros: Groups sync automatically; Users are searchable/visible immediately (allowing for pre-assignment of roles); Supports deprovisioning.
    • Cons: Requires SCIM token generation and maintenance.

Recommendation:
Use SCIM if you need Group-based access control or want to manage roles via your IdP. If you only need simple user authentication, JIT is sufficient.

6. How do I map Identity Provider groups to DataHub Roles?

Issue:
You want to automatically assign DataHub roles (like Admin or Editor) based on Okta/Entra group membership.

Steps:

  1. Ensure your groups are present in DataHub (via SCIM sync) or available via OIDC token claims (groups claim).
  2. Navigate to Settings → SSO → Configure Group Mappings.
  3. Map the IdP Group Name to the desired DataHub Role.
    • Example: Map IdP Group "DataHub-Admins" → DataHub Role "Admin".
  4. Changes will take effect the next time the user logs in.

7. My SCIM token expired. How do I rotate it without breaking provisioning?

Issue:
Tokens expire based on the duration set during creation, causing sync failures in your IdP.

Steps to Rotate:

  1. Generate a new token for your service user (using the same GraphQL mutation referenced in FAQ #2).
  2. Log in to your IdP (e.g., Okta).
  3. Navigate to the DataHub application → Provisioning → Integration settings.
  4. Paste the new token into the API Token field.
  5. Test the connection to ensure it works.
  6. Save the configuration.
  7. (Optional) You may now revoke the old token in DataHub.

8. How do I test my SSO configuration without locking myself out?

Issue:
Fear of misconfiguration leading to a complete lockout of the instance.

Safe Testing Strategy:

  1. Do not delete your initial local admin account; keep it as a backup.
  2. Bookmark the /login endpoint so you can always bypass SSO.
  3. Open an Incognito/Private browser window to test the SSO flow. Keep your existing Admin session open in your main window.
  4. If the SSO test fails, you can use your open Admin window to fix settings, or use the bookmarked /login page to sign in with local credentials.

9. Which SSO providers does DataHub support?

DataHub supports OIDC (OpenID Connect) and SAML. Common providers successfully deployed include:

  • Okta
  • Microsoft Entra ID (formerly Azure AD)
  • Google Workspace
  • Keycloak
  • PingIdentity

10. Where can I troubleshoot SCIM sync failures?

If users are not appearing or updates are failing:

  1. Check IdP Logs: Look at the Provisioning Logs in Okta or Entra ID. They will usually provide a specific error code (e.g., 409 Conflict, 401 Unauthorized).
  2. Check DataHub Logs: Look for the SCIM keyword in the GMS (Metadata Service) logs.
  3. Common Issues:
    • Token expiration (401).
    • Incorrect Base URL (ensure it ends in /gms/api/scim/v2).
    • User Conflict (409 - see FAQ #3).

11. Can I have users from multiple email domains?

Yes. SCIM and SSO are not restricted to a single domain. SCIM will sync any user assigned to the DataHub application in your IdP, regardless of their email domain (e.g., @company.com and @contractors.com), provided your IdP is configured to allow those assignments.

Related to

Related articles