Crossing business boundaries with Azure Active Directory B2B API

Office 365 is fantastic for collaborating with colleagues within your company. But what if you need to work with people outside your organisation? It’s time to invite some guests over…

Azure Active Directory provides the foundation for managing user identities for Microsoft’s suite of online software-as-a-service products such as Office 365 and Dynamics 365. Although it is not exposed directly to end users each time someone logs into Office 365 to edit a document, looks up a colleague’s email address to send an email or sends a message to a group, it is Azure Active Directory powering these actions.

However, an increasingly important requirement is to allow collaboration with people at other organisations in a way that is as easy and efficient as collaboration within an organisation.

Meet Bob and Alice

Alice works for Fabrikam, and Bob works for Contoso. As both Fabrikam and Contoso use Office 365, there is an Azure Active Directory for each of these organisations, with Alice and Bob having User objects in the relevant directories:

Alice has no access to anything at Contoso and Bob has no access to anything at Fabrikam; even though they are both hosted on the same Microsoft infrastructure, Alice can’t look up Bob’s email address, as the two domains are completely separate.

Cross-border collaboration

So what if Alice wants to collaborate with Bob and give him access to edit a document she is working on?

Azure Active Directory supports that concept of a Guest User – a type of User object in a directory that references a User object in another directory. Guest Users behave like a slightly limited form of normal Users (for example, their ability to look up Users is restricted and the details they can look up are also limited). But, critically, they can be given access to applications like Office 365, and can be members of Groups to authorize how they access resources within applications.

Bob now has a Guest User object in the Fabrikam directory, meaning he can access documents in the Fabrikam Office 365 environment.

Authenticating Guests

An extremely important feature of Guest Users in Azure Active Directory is that the authentication of the User is still based on their identity in their own ‘home’ Directory. This has the advantage that Bob only has one set of credentials (i.e. username and password) for Contoso and Fabrikam. Administration is now much easier, as disabling Bob as a user in Contoso (if he leaves, for example) will also disable access to Fabrikam and any other directories where he is a guest.

So how are Guest Users created in Azure Active Directory? It could be done manually by an administrator, by directly adding the Guest User to the directory. But that is time-consuming for large numbers of users, and not accessible to end users like Alice.

Azure Active Directory has supported a B2B feature for a while that allows bulk creation of Guest Users by uploading a comma-separated values (CSV) file with the details of the users to be invited – their email address, display name and so on. Azure sends an email to the user being invited – Bob in our example – containing a link that will take them through a simple processing of joining the new directory as a guest.

The CSV file-based B2B feature still requires an administrator to create the file in the required format and manually upload it into the Azure portal… which is not ideal for a seamless experience!

Creating invitations programatically

Fortunately, Microsoft have announced a new API for Azure Active Directory, currently in preview, that allows invitations to be created programmatically. The snappily-titled Azure AD B2B API is a simple extension to the existing Microsoft Graph API. After authenticating, it requires an HTML POST of a JSON document similar to the following:

"invitedUserEmailAddress": "",
"invitedUserDisplayName": "Bob",
"inviteRedirectUrl":    "",
"sendInvitationMessage": true,
"customizedMessageBody": "Hello Bob – good to be working together again"

After POSTing this to the Microsoft Graph API at, the response is another JSON document that contains, in addition to lots of other details, the ID of the Guest User in the directory, which can also be seen in the Azure Portal:

As the ID of the Guest User is available, subsequent calls to Microsoft Graph can be made to add this User to any required Groups.

Letting the user know

One final thing to note about the request document is the sendInvitationMessage flag, which controls whether Azure sends an email directly to the user (true) inviting them to the Directory, or whether the calling application wants to do this itself (false). In the latter case, the application can create and send an email using the inviteRedeemUrl value from the response – this is the link the invited user has to click on to redeem the invitation, and is the same one that Azure would send in an email.

The B2B Invitation API will prove increasingly important, as it allows direct integration between applications, such as CRM systems, that can then expose this invitation functionality directly to end users.

Share this page

Leave a comment