I have had several customers in recently who were focused on adding their own approval processes to inviting external users either for Office 365 or their own custom applications. In both cases, external users are within the realm of Azure Active Directory. Azure AD is the identity store of Office 365. Working with Azure AD at an API level leads us to the set of REST endpoints exposed by Microsoft Graph. This article documents my exploration of using the Graph API to invite external users. In part 2, we will use the knowledge gained here to add an approval process using Microsoft Flow, Azure Logic Apps, and Microsoft Forms.
Most folks focus on getting their on-prem Active Directory account information into Azure AD. This must be done if you would like your users to use the same sign in information for Office 365 as they do for resources on your network. In this article, we are going to disregard your internal users and instead focus on the ways we can leverage Azure AD to control users outside (vendors, partners, customers, etc). Ideally, we don’t want to be in the business of maintaining credentials where we don’t have to. So instead, we will make use of Azure’s B2B (Business to Business) capability whenever we can. When we are inviting users with a business email address, we simply want the service to connect to the identity in that user’s organization’s directory. We don’t want to have to manage these identities, set passwords, or disable accounts based on what is going on in the other organization.
This is all pretty easy to do as an admin in Azure’s portal. But to meet our goal, we will need to be able to automate those steps. Earlier, I stated that the Microsoft Graph is an API endpoint for accessing many of Microsoft’s cloud services and Azure AD is within its scope. To explore these APIs, I leveraged the Graph Explorer. This is a utility that you can log into, grant yourself permissions, and test queries to make sure your requests are well formed.
In the above picture, I am using the Graph Explorer to create a HTTP post to the invitations endpoint (which is what you use to invite an external user). The endpoint in this case is https://graph.microsoft.com/v1.0/invitations. The body has the details including the email address of the external user, the fact that I do want a invitation message to be sent, and a redirect URL as to where I want to user to be directed after accepting the invitation. This is more for the scenario where I am using Azure AD to protect a custom application. In all, the body looks like this for inviting my Microsoft corp identity into my demo tenant. You can find all the options on the API at this URL which including customizing the invitation: https://docs.microsoft.com/en-us/graph/api/invitation-post?view=graph-rest-1.0
{
“invitedUserEmailAddress”: “edhild@microsoft.com
“inviteRedirectUrl”: “https://myapp.com",
“sendInvitationMessage”: true
}
Once the user has been invited, listing the tenant’s Azure AD users, you should see that the email address you specified is an “Invited User”.
The invited user then gets an invitation. Again you can customize this, but the default looks like this:
In this case, my corporate credentials are already in a separate Azure AD tenant from my demo environment. So when I click the link, I get a confirmation dialog that I am sharing basic information with the demo directory.
After accepting, I am redirected to the URL specified in the invitation. This is a custom app URL in demo. Now that the process is complete, looking back at Azure AD, the previously invited user is listed as being in an “External Azure Active Directory”.
With business email addresses, Azure B2B takes care of all of the complexity. If the partner organization doesn’t use Azure AD, the guest user in Azure AD is still created. The requirements are that they redeem their invitation and Azure AD verifies their email address. This arrangement is also called a just-in-time (JIT) tenancy or a “viral” tenancy (read more about this here).
But what about the scenario where we invite an external user that couldn’t be in another Azure AD. Such a user could have an personal email address like gmail, yahoo, outlook, etc. In this case, the default behavior is to have that user use that email address for a Microsoft Account. Once the invitation process is complete, you can see in Azure AD that account listed as type “Microsoft Account”.
But wait there is more. Notice in the above picture, that this sequence involved inviting a gmail account to prove the scenario of an invitation to a user who couldn’t be in another Azure AD. As it turns out, Google is able to be configured as an Identity Provider for Azure AD’s B2B service. You can find out more about how to configure this option here: https://docs.microsoft.com/en-us/azure/active-directory/b2b/google-federation.
Once completed, rerunning the scenario for a Gmail account as the invited user results in a slightly different flow as the user is logging into Google.
After the process is complete, in the tenant’s Azure AD you will see a user having a user of type “Google”.
Now that we have an idea of how Azure AD B2B works and the Graph API’s that can kick it off, in the next part of this blog, I will look at using out of the box tools such as Microsoft Forms, Microsoft Flow, and Azure Logic Apps to provide a way to automate the process adding human approval points.
Just to be complete, there are a few other topics related to this that you might find interesting. If this is for a custom application, you may be interested in learning how to brand Azure AD’s sign in pages: https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/customize-branding
Plus if personal email accounts are more in your scope (they weren’t for my customers), I recommend looking into Azure AD’s B2C service in addition to B2B.