Edit

Share via

Change your organization connection to a different Microsoft Entra ID

  • Article

Azure DevOps Services

This article explains how to switch your organization's connection from one Microsoft Entra ID to another. When you change directories, your project resources remain unaffected.

You might want to switch to a different directory to align with organizational changes, such as mergers or acquisitions, or to consolidate multiple directories for better management and security.

For more information about using Microsoft Entra ID with Azure DevOps, see the conceptual overview.

Prerequisites

  • Permissions: Be a member of the Project Collection Administrator group for the organization.

  • Access:

  • User management:

    • Confirm there are 100 or fewer users in your organization. If your organization has more than 100 users, contact Support to resolve any disconnected users. You can map them to their Microsoft Entra identities in the new tenant.
    • Don't add the users from the destination Microsoft Entra ID into the Azure DevOps organization.

  • SSH keys: Request that SSH keys get manually cleared by Support before you switch directories. You can find the steps for how to recreate SSH keys further in this article. For more information, see the FAQ.

Custom domains

If you add any new custom domains to your Microsoft Entra directory, contact Support before you migrate customers over to the new custom domain as this action breaks the mapping for existing identities.

Important

After the transfer, users and groups who inherit membership and permissions from a Microsoft Entra group no longer inherit those permissions. Microsoft Entra groups added to your Azure DevOps organization won't be transferred and cease to exist in your organization when the Microsoft Entra connection is changed. All permissions and membership relationships associated with these Microsoft Entra groups also cease to exist after the transfer.

Change the Microsoft Entra connection

  1. Sign into your organization (https://dev.azure.com/{yourorganization}).

  2. Select gear icon Organization settings.

    Screenshot showing highlighted Organization settings button.

  3. Select Microsoft Entra ID, and then Switch directory.

    Screenshot showing Switch directory button emphasized.

  4. Select a directory from the dropdown menu, and then select Connect.

    Screenshot showing Microsoft Entra dropdown menu, and then Connect button emphasized.

    If you can't find your directory, contact your Microsoft Entra administrator to request to get added as a member to the Microsoft Entra ID.

  5. Select Sign out.

    Screenshot showing Sign out button emphasized.

    Your organization connects to your Microsoft Entra ID.

  6. Confirm that the process is complete by signing out. Open your browser in a private session and sign in to your organization using your Microsoft Entra ID or work credentials.

  7. If some of your members are disconnected during this process, an error message like the following example appears on the Microsoft Entra page. Choose Resolve to map the disconnected users. For more information, see FAQs.

    Screenshot showing Resolve button emphasized.

    Screenshot showing Resolve disconnected users dialog.

Inform users of the completed Microsoft Entra change

When you inform your users of the completed change, provide them with the following tasks to do:

  1. Sign out of Azure DevOps.

  2. Clear browser cache. If you use Visual Studio or the Git command-line too, clear the cache for the Git Credential Manager. Delete the %LocalAppData%\GitCredentialManager\tenant.cache file on each client machine.

  3. Sign in to Azure DevOps using Microsoft Entra ID or work credentials.

  4. Reconfigure any personal access tokens (PATs) or SSH keys, if necessary.

    1. In Azure DevOps, open your profile, and then select Security from the resulting dropdown menu.

    Screenshot showing Security selection emphasized.

    1. Select SSH public keys, and then select Add.

    Screenshot that shows adding an SSH public key.

    1. Enter a description and key data, and then select Save.

    Screenshot showing info dialog for creating SSH key.

    1. Copy your key and put it in a safe place, since you can't view it again.

  5. Rename your Microsoft account (MSA). Rename your MSA to a different email that doesn't conflict with your Microsoft Entra identity. Doing so ensures that you aren't prompted to choose between accounts.

  6. (Optional) Adjust your visual Studio (VS) subscription. If the UPN used inside your organization changed, adjust your Visual Studio subscription. You can reassign the subscription to your new UPN, or set that UPN as the alternate account inside the subscription. For more information, see how to add an alternate account to your subscription.