This post is provided by Senior App Dev Manager Nick McCollum, who introduces us to Azure Active Directory B2B collaboration.

Azure Active Directory Business to Business (B2B) Collaboration enables your business partners to selectively access your corporate applications. In the original release of the product the invitation experience required a user to craft a comma-separated value (.csv) file containing the email addresses of the business partner users to be invited to use an application. This file was uploaded to Azure Active Directory via the Azure management portal and email invitations were sent to the users contained in the file. The email invitations contained a link that allowed the user to redeem their invitation and gain access to the associated application(s). While this approach provided the basic functionality required it limited the ability to create advanced scenarios such as self-registration. In addition, the original release did not support inviting users with social media email addresses such as Facebook and Google. This prevented sharing corporate applications with small business partners who may have been leveraging social media services for email, collaboration, and document management.

The latest release of Azure AD B2B Collaboration provides many updates to address the shortcomings of the original release including a new REST API for managing the invitation process. The features of the new invitation manager API will be the focus of this article.

Accessing the Azure AD B2B Invitation Manager API

The Azure AD B2B invitation manager API is accessed via the Microsoft Graph. To create an invitation you send an HTTP POST to https://graph.microsoft.com/v1.0/invitations. The body of the HTTP POST contains a JSON representation of the invitation as follows.

{

“invitedUserDisplayName”: “string”,

“invitedUserEmailAddress”: “string”,

“invitedUserMessageInfo”: {“@odata.type”: “microsoft.graph.invitedUserMessageInfo”},

“sendInvitationMessage”: false,

“inviteRedirectUrl”: “string”

}

A description of each property of the invitation is given below.

At a minimum you must provide an invitedUserEmailAddress and an inviteRedirectUrl to create an invitation.

The invitedUserMessageInfo property can be used to customize certain aspects of the invitation email message. A description of each property of the microsoft.graph.invitedUserMessageInfo type is given below.

By default the sendInvitationMessage property is false. To have the invitation manager API send the email message on behalf of your application set this property to true. Otherwise, you can retrieve the redemption URL from the create invitation response and send out the email invitation yourself through whatever mechanism you choose (SMTP, Exchange, SendGrid, etc.). Using this approach allows you some additional control over the registration process in a self-registration scenario where an approval is required internally before an invitation is sent.

Sending an Invitation

The example code below demonstrates how to send an invitation using the Azure AD B2B invitation manager API. As with all graph operations you will need to provide a bearer token in the Authorization header of the HTTP POST request to the invitation manager API. The sample code uses the Active Directory Authentication Library (ADAL) to obtain an access token for the Microsoft Graph prior to calling the invitation manager API. A simple class is created that contains the properties of the invitation discussed earlier. In the example, the invitedUserEmailAddress and inviteRedirectUrl are populated and the sendInvitationMessage property is set to true indicating that we want the invitation manager to send the email invitation to the user immediately. ClientCredential credential = new ClientCredential(clientId, clientSecret); AuthenticationResult authResult = authenticationContext.AcquireTokenAsync(resourceUrl, credential).Result;

InvitationModel invite = new InvitationModel();

invite.invitedUserEmailAddress = emailAddress;

invite.inviteRedirectUrl = redirectUrl;

invite.sendInvitationMessage = true;

using (HttpClient client = new HttpClient())

{

client.BaseAddress = new Uri(resourceUrl);

client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken);

HttpResponseMessage response = client.PostAsJsonAsync<InvitationModel>("v1.0/invitations", invite).Result;

dynamic inviteResult = response.Content.ReadAsAsync<dynamic>().Result;

if (inviteResult.status != “Error”)

{

// Invite successfully sent

}

}

A dynamic object is used to store the response of the create invitation request. A JSON representation of the response is show below.

{

“invitedUserDisplayName”: “string”,

“invitedUserEmailAddress”: “string”,

“invitedUserMessageInfo”: {“@odata.type”: “microsoft.graph.invitedUserMessageInfo”},

“sendInvitationMessage”: false,

“inviteRedirectUrl”: “string”,

“inviteRedeemUrl”: “string”,

“status”: “string”,

“invitedUser”: [{“@odata.type”: “microsoft.graph.user”}]

}

The response to a create invitation request contains all of the properties described earlier in the invitation as well as these additional properties.

An example of the default email invitation message the user will receive is shown below. The user can click the redemption link contained in the email message to redeem their invitation and access the associated application(s).

Once the invitation has been sent a guest user account is created in your organization’s Azure Active Directory to represent the invited user. If you search Azure AD through the Azure management portal, you can find this user and examine its profile as shown below.

The profile will indicate that the user is a Guest and they are an Invited User.

Wrapping Up

This post has provided you with the basic information needed to get started with the Azure AD B2B invitation manager API. In a subsequent post we will discuss how to leverage other APIs in the Microsoft Graph to assign a user to a particular application role when they register.

Premier Support for Developers provides strategic technology guidance, critical support coverage, and a range of essential services to help teams optimize development lifecycles and improve software quality.  Contact your Application Development Manager (ADM) or email us to learn more about what we can do for you.