Inviting Microsoft Account users to your Azure AD-secured VSTS tenant

I've done a lot of external invite management for VSTS after the last few years, and generally without fail we'll have issues getting everyone on-boarded easily. This blog post is a reference for me (and I guess you too) to understand the invite process and document the experience the invited user has.

There are two sections to this blog post:

Admin instructions to invite users.
Invited user instructions.

Select whichever one applies to you.

The starting point for this post is that external user hasn't yet been invited to your Azure AD tenant. The user doing in the inviting is also not an Azure AD Global Admin, but I has rights in an Azure tenant.

The Invite to Azure AD

These steps assume your Azure AD user has the "Guest Inviter" role and that your Azure AD administrators have enabled guest invites for your Directory.

The Short Way

Log into an Azure subscription using your Azure AD account and then browse to the Directory that is tied to your VSTS subscription. At the top of the screen click on the "New guest user" link and enter the email address of the user you are inviting.

The Long Way

Log into an Azure subscription using your Azure AD account and select Subscriptions. Ideally this shouldn't be a production tenant!

I am going to start by inviting this user to my Azure tenant as a Reader-level user which means they will receive an Azure AD invite. I will later revoke this access once they have accepted my invite.

Click "Add" on the IAM blade for the Subscription.

Ensure you set the role to "Reader" which provides no ability to execute changes.

![Set Role]/static/images/2017/subscription03.png)

Now enter the user's email address. Note you can add multiple email addresses if you want. Click "Save" button to apply the change.

Once I click "Save" the portal will say it is inviting the user. A short while later the invitee will receive an invite email in their inbox. See later in the blog post for their experience.

Add Invited User to VSTS

Now the invited user is in your Azure AD tenant they will show up in the User Search Dialog in VSTS. You must be a VSTS Admin to manage users.

Log into your VSTS tenant and navigate to Users and then search for the newly added user and assign them the license you want them to use.

Click "Send Invitation" which will be enabled once you select the invitee's account from the drop-down. Note that VSTS won't actually send this user an invite.

At this stage the user now has access to your VSTS tenant, but not any projects it contains - make sure you add them to some!

Let's take a look and see what the invited user sees.

Invited User Experience

If I log in to the invited user's Outlook.com mailbox I will see an Azure AD invite awaiting.

The invited user should click the "Get Started" button to accept the invite. Unless they complete this process they won't have access to VSTS.

This will open a web browser on the invited tenant's redemption page that will be branded with any extended branding the Azure AD tenant has.

The user must click 'Next' on this screen to accept the invite.

It will take a few moments to setup the Microsoft Account in the Azure AD tenant.

Once done the user will end up at the default "My Apps" screen but will see nothing at this point as they have not be granted access to anything.

Invited User Accesses VSTS

The invited user can now navigate to your VSTS tenant in a browser - https://tenantname.visualstudio.com/

If they aren't already logged into their Microsoft Account they will be prompted to login and then directed to VSTS.

As this is their first time logging in they will be asked to enter some information which will auto-populated, but editable.

They then get dropped to the home page for VSTS and are ready to work. If you didn't add them to any existing projects and haven't granted them additional privileges they might see the screen below.

Make sure they bookmark your VSTS tenant and that they use their invited Microsoft Account each time they want to access it.

If the user logs out or their session times out they will be directed to your Azure AD tenant login page firstly, as this is what VSTS is configured to use when you attach an Azure AD tenant to it.

The invited user should enter their Microsoft Account into the email address box and when the username box loses focus they will be redirected to the Microsoft Account login screen.

This step quite often catches people out as they aren't expecting the redirect, particularly if they haven't used Office 365 or similar systems.

At the Microsoft Account login page (shown below) they enter their password and they will be directed back to VSTS.

Don't forget!

If you're the inviting Admin you can now remove the invited user as a reader from your Azure tenant.

If you want extra security, get the Microsoft Account user's to turn on two-step verification which will require them to enter a code to login.

Happy coding!

Post credit-roll Admin bonus!

If you find out that some of the users you invited didn't have a mailbox attached to their Microsoft Account and therefore didn't get the original invite you can resend the invite. Log into your Azure tenant, open Azure Active Directory and then find the invited user.

Open their profile and click on the 'Resend invitation' button - it is greyed out but will work just fine :).