Getting Started with the Azure AD B2B Invite API


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.

Property

Type

Description

invitedUserDisplayName

String

User’s full name

invitedUserEmailAddress

String

User’s email address

invitedUserMessageInfo

invitedUserMessageInfo

Customized invitation message details

sendInvitationMessage

Boolean

Indicates if the invitation API should send the email invitation. Default value is false.

inviteRedirectUrl

String

The URL to redirect the user to following successful redemption of the invitation

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.

Property

Type

Description

ccRecipients

Array of Recipient

An array of additional recipients the invitation email message should be sent to. Currently only 1 additional recipient is supported.

customizedMessageBody

String

Customized message body you would like to send rather than the default message

messageLanguage

String

ISO 639 language format. Default is en-US. Ignored if the customizedMessageBody property is populated.

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.

Property

Type

Description

inviteRedeemUrl

String

The URL the user can use to redeem his invitation

status

String

The status of the invitation. Possible values include Completed, In Progress, and Error.

invitedUser

User

The guest user created in Azure AD as part of the invitation creation

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).

clip_image002

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.

clip_image004

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.

Comments (3)

  1. P Bose says:

    Where can I find resources on AWS to Azure Migration tips?

  2. Flynn says:

    Hi there,

    Nice post! 🙂

    Im doing something very similar but I have an additional step after sending the invite to the user – Im trying to add them to a specific security group in Ad using the ‘https://graph.microsoft.com/v1.0/groups/{0}/members/$ref’ endpoint.

    In your example above, the response from the post has an “invitedUser” member, with an ‘id’ sub-property. In my example, I also get the same type of response, with a valid guid as the id. If I go and look in Azure AD, it sometimes takes up to 30 seconds for this new user to show up (and they do indeed have that same guid as their user id), even though the POST may only take 1-2 seconds to get a response.

    Is there any explanation for this delay?

    This actually creates a bit of a problem for me in the second step when I try and add them to an AD group. The initial invite seems successful, but the add to a group doesnt work unless I add an arbitrary delay of 30 seconds say….

    Any idea what the issue here is? I can’t find any mention of delays etc in the msdn documentation.

    Thanks,

Skip to main content