Update managed SCIM email addresses

Deleting the user in our SCIM DB via Atlassian Account ID (AAID) will apply to all directories in that org matching that AAID. This only works for managed users. If reprovisioning a user after it has been deleted, you will need to reprovision its group memberships separately.

This API primarily facilitates the unblocking of unlinked managed accounts via SCIM so it can be managed locally in Atlassian. This eliminates the need to contact support for resolving issues related to incorrect emails associated with different users.

Common use cases include:

• Changing which account is synced for a specific user.
• Unlinking an account that is no longer assigned to the Atlassian Cloud app or no longer exists in your identity provider.

API for how to delete user only in SCIM DB.

Use Case Scenarios and Resolution

To reprovision a user after deletion, make sure to unassign and reassign the user via the Atlassian Cloud app or there may be consequences using your IdP’s force push.

There are two typical flows:

Right account is synced with wrong email, wrong account is also synced to SCIM (Use Case A):

• Syncing users via SCIM using a single IdP and the IdP creates a new user instead of updating the existing user.

• Commonly occurs when a user is transitioned from a “Guest user” or “Consumer user” to a “Work account” in Microsoft Entra ID, or when an end user is re-hired but a new IdP user record is created instead of their original record being reused.

• Syncing users via SCIM using multiple IdPs and the user is synced via both IdPs under different emails, but needs to only be synced under IdP1 as the email synced via IdP2.

Resolving the issue:

In this use case, we will assume:

• AAID1 is synced as old.email@domain.com with historical data; attempts to update email via SCIM fail because new.email@domain.com is already in use.

• AAID2 is also synced, using new.email@domain.com but no/limited historical data

To resolve the email being attached to the wrong AAID:

1. Call API to unlink AAID2 (or see cookbook for scripts)

   a. The user record is deleted from Atlassian SCIM side for AAID2

2. Update email for AAID2 from new.email@domain.com to a value not used (either via UI or UM API)

3. Re-push the email update that’s failing for that user in their IdP to provision the user and successfully update email on AAID1 to new.email@domain.com

Note that in this use case, the troubleshooting log for: Resource [USER]: with email[{value}] already exists is typically emitted. If this troubleshooting log is not emitted, then the fix is to unlink both accounts from SCIM, and follow the steps in scenario B.

Wrong account is synced to right email (Use Case B):

• Users are migrated from on-prem to the cloud under one set of emails but are synced via SCIM using a different set of emails.

• Users are created or invited under one email but are synced via SCIM under a different email.

• This is a common scenario for mergers/acquisitions. How the users were originally created/invited is immaterial, but may have been manually created by an Admin, created via SCIM by an IdP that’s no longer connected (or by an org that doesn’t currently manage the domain), or simply invited to Atlassian (by an end user or admin, regardless of whether the account was ever activated/verified).

Resolving the issue:

In this use case, we will assume:

• AAID1 isn’t synced, using old.email@domain.com with historical data.

• AAID2 is synced as new.email@domain.com without historical data.

To resolve the issue with the wrong account synced to the correct email:

1. Run API to unlink AAID2 (or see cookbook for scripts)

   a. The user record from Atlassian SCIM side for AAID2

2. Update email for AAID2 from new.email@domain.com to a value that is not used (either via UI or UM API)

3. Update email for AAID1 from old.email@domain.com to new.email@domain.com (either via UI or UM API)

4. Unassign and then Reassign the user to the Atlassian Cloud app in their IdP to reprovision the user and sync them with AAID1.

Changing the Email for a Managed User

To change the email for a managed user via UI (once the account is no longer SCIM managed), follow the steps here

Change Atlassian account email addresses | Atlassian Cloud | Atlassian Documentation

To use the UM API, use the following API:

The User management REST API REST API

Potential Consequences

Once the User has been deleted in Atlassian SCIM DB, the group syncs will have to be resynced for that user once the user is reprovisioned and it may take some time for that user to be readded to groups.

If the user is not unassigned and reassigned via the Atlassian Cloud App some errors may occur. Some errors that we know of that may occur if the procedure is not followed are listed below. We highly recommended following the procedure of unassigning and reassigning via Atlassian Cloud App.

Authentication

Authentication is implemented via an API key. Use the API Key as a Bearer access token to authenticate the script and manage your organization. The Organization ID is used as a unique identifier in the path parameter for the organization. Copy the Organization ID and API key and keep them in a safe place. We won’t show them to you again.

See here for more info.

Note that this is strictly different than your scim directory api token as this follows a different API path.

Example Scripts to Call API

See examples in cookbook.