Connect VSTS account to Azure Active Directory (Azure AD)
Azure AD users - you can connect your existing Azure AD tenant to VSTS, even if you started with a Microsoft account for your VSTS instance.
If your VSTS account was created with a Microsoft account, you can connect your VSTS account to your organization's directory (tenant) in Azure Active Directory (Azure AD). You can then sign in to VSTS with the same username and password that you use with these Microsoft services. You can also enforce conditional access policies for accessing your team's critical resources and key assets.
If your users are being asked to choose between signing in to VSTS with their personal or work or school account, you will benefit from connecting your VSTS account to your organization's Azure AD.
For more information, see the conceptual overview for using Azure AD with VSTS.
Understand where you're starting from
While the steps to connect your VSTS account to Azure AD are consistent, it's important to understand where you're starting from before connecting your VSTS account to your target Azure AD tenant.
One of the following scenarios likely applies to your situation. For example, "yourname"@fabrikam.com is replaced with firstname.lastname@example.org:
|You use an MSA for VSTS||and you want to connect to the target Azure AD||So do this|
|email@example.com||using the SAME ID firstname.lastname@example.org||Follow this document|
|email@example.com||using a DIFFERENT ID firstname.lastname@example.org||Create a new support ticket|
|email@example.com||replacing with different tenant ID firstname.lastname@example.org||Create a new support ticket|
When you're creating your new support ticket, use the >following: Problem type: Configuring Team Services, Category: Configuring with Azure Active Directory]
Overview of the connection process
The following steps outline the high-level process of connecting VSTS to Azure AD.
- Ensure all VSTS users are in the target Azure AD tenant, either as members or Business-to-Business (B2B) guests.
- Inform your users of the upcoming change and ask them to check in all code changes before the process begins.
- Connect your VSTS account to your organization's directory.
- Inform users of the completed change and that they should sign in with their Azure AD credentials from now on.
Ensure all VSTS users are in the target Azure AD tenant
All users of the VSTS must exist in the target Azure AD tenant. Any user that is not in the tenant will be a "historic" user, unable to log in, however their history is retained.
Sign in to your VSTS account and go to the Users tab.
Compare the VSTS list of emails against the list in your target Azure AD tenant.
If any users exist on the VSTS Users page, but are missing from your target Azure AD tenant, add them as B2B guests.
These guests can be external to your organization (User@othercompany.com) or existing Microsoft account (MSA) users (email@example.com or firstname.lastname@example.org).
If you are notified that you do not have permissions to invite users, verify that your user account is authorized to invite external users under User Settings.
If you have recently modified these settings or assigned the Guest Inviter role to a user, there might be a 15- 60-minute delay before the changes take effect.
If no paid Azure AD license exists in the tenant, every invited user gets the rights that the Azure AD Free edition offers.
If users exist, but their email addresses are different from their Microsoft accounts, work with CSS to help with the migration by creating a new support ticket.
Inform users of the upcoming change
While there is no downtime, users will be affected by this change, so it's best to let them know before you begin this process. Let them know ahead of time that there will be a short series of steps for each user to complete and that as the organization transitions from Microsoft to Azure AD identities and the emails match, users' benefits will continue to work with their new Azure AD identity.
Determine which user is performing the connection of VSTS to Azure AD
Ensure the following about the user performing the connection. This user:
- Exists in the target Azure AD tenant as a guest or member.
- Is an owner of the VSTS account.
- Is not using the Microsoft account identity that matches the Azure AD identity, for example, the Microsoft account you currently use is JamalHarnett@fabrikam.com and the Azure AD identity you will use after connecting is also JamalHarnett@fabrikam.com. You must use a single identity that spans both applications (MSA that's in the target Azure AD tenant), rather than two separate identities using the same email.
If the emails are the same, then follow these steps, otherwise continue on to Connect your VSTS account to your organization directory.
Sign in to your VSTS account (as a Project Collection Administrator) and add the new user as a member of the account.
Sign in to the Azure portal and add the new user as a B2B guest of the target Azure AD tenant and an email invitation sent to the new account.
Go to your email invitations from Azure and choose the Call-To-Action in each email. You will be required to choose Next/Continue on a few screens to fully register the new user.
Sign in to your VSTS account as the new user.
Go to Settings in VSTS (as a Project Collection Administrator) and change the owner of the account to the new user, only after the new user has logged in.
Use this new user to complete the migration.
Connect your VSTS account to your organization directory
Sign in to the Azure portal with the Microsoft account chosen in the previous step.
The target tenant is selected in the upper right corner of the Azure portal.
Browse to your VSTS account by entering Team services accounts into the Search box, and choosing Team Services accounts.
Select your VSTS account. If you don't see your account, check to make sure you are using the expected tenant in the upper right of the Azure portal and confirm that you are logged in with a Microsoft account that is the owner of the VSTS account in question.
- If Connect is greyed out:
- You are either already connected to a tenant (disconnect is enabled) or
- Your VSTS account may not be linked to Azure AD (link would be enabled). Learn more about linking to set up billing.
- If Connect is greyed out:
Choose Yes to confirm.
Your account is now connected to your organization's directory.
To confirm that the process has been completed, open your favorite browser in a private session and sign in to your VSTS account with your Azure AD/work credentials.
- If you created a temporary user to complete the migration, change the owner of the VSTS account back to the initial user and delete the temporary Microsoft account, as it is no longer needed.
Inform users of the completed change
Visual Studio subscription administrators assign subscriptions to a user's corporate email so that they can get the welcome email and notifications about the subscription. If the email of the identity and the subscription match, the user will be able to access the benefits of that subscription. As your organization transitions from Microsoft to Azure AD identities and the emails match, your user's benefits will continue to work with their new Azure AD identity.
When you inform your users of the completed change, include the following tasks that each user in the VSTS account must complete:
If you use the Git command line tool, the tenant cache for the Git Credential Manager may need to be cleared.
Deleting the %LocalAppData%\GitCredentialManager\tenant.cache file on each client machine will resolve the issue.
If you use alternate authentication tokens used by tools or scripts, regenerate new tokens for the Azure AD user.
a. On your VSTS page, in the upper right, choose your profile image and choose Security.
b. On the Personal access tokens page, choose Add. Enter a description. Scroll to the bottom of the page and choose Create token.
c. When the token is created, make a note of it as it cannot be viewed again. Copy it from the browser into the clipboard.
If you don't want to be prompted to choose between accounts, rename your Microsoft account to a different email that does not conflict with your Azure AD identity or simply close your Microsoft account if it's no longer needed.
If you used a Microsoft account to sign up for a Visual Studio with MSDN subscription that includes VSTS as a benefit, you can add a work or school account that's managed by Azure Active Directory to your subscription. Learn how to link work or school accounts to Visual Studio with MSDN subscriptions.
(Optional) Close the temporary MSA (if you created one)
- Go to the Settings page in VSTS and change the owner of the account back to yourself.
- Go to the Users page in VSTS and remove the temporary new user.
- Go to the Azure portal and remove the new user from the Azure AD tenant.
Close the temporary MSA you created.
Q: Will my users still retain their existing Visual Studio subscriptions?
A: Visual Studio subscription administrators typically assign subscriptions to a user's corporate email so that they can get the welcome email and notifications about the subscription. If the email of the identity and the subscription match, the user will be able to access the benefits of that subscription. As your organization transitions from Microsoft to Azure AD identities and the emails match, your user's benefits will continue to work with their new Azure AD identity. If the email that the subscription is assigned to differs from your Azure AD identity's email, then your subscription administrator will need to reassign the subscription, or the user will need to add an alternate identity to their Visual Studio subscription.
Q: What if my SSH token is no longer valid?
A: Complete the following steps:
- On your VSTS page, in the upper right, choose your profile image and then choose Security.
- On the Personal access tokens page, choose Add.
- Enter a description and go to the bottom of the page and choose Create token.
- When the token is created, make a note of it as it cannot be viewed again. Copy it from the browser into the clipboard.
- Work with CSS to help with the migration of your existing SSH tokens by creating a new support ticket.
Q: What if sign-in is required when using the identity picker?
A: Clear the browser cache and delete any cookies for the session.
Q What if my work items are indicating that the users aren't valid?
A: Clear the browser cache and delete any cookies for the session.
Q Why can't I make purchases after connecting to a directory?
A: By changing the directory associated with your Azure subscription to the directory your VSTS account uses, you'll be able to make purchases again. Learn more.