Update: Oct 30 '18 Also see this post that adds support for Microsoft's updates to the Microsoft Graph to include additional information about Azure AD B2B Guest users.
Earlier this year Microsoft released the Microsoft Identity Manager Azure AD B2B Management Agent. I wrote about using it to write to Azure AD in this post here. As detailed in that post my goal was to write to Azure AD using the MA. I provided an incomplete example of doing that for Guests. This post fills in the gap and unlike the note preceding the post indicates, I’ve updated my MA to use the Graph API over the Azure AD PowerShell Module. It does though work in unison with the Microsoft Azure AD B2B Management Agent.
The process is;
- Using the Microsoft Azure B2B Management Agent connect to an Azure AD Tenant that contains users that you want to invite as Guests to your Tenant. Flow in the naming information for users and their email address and any other metadata that you need to drive the logic for who you wish to invite
- Use my Azure AD B2B Invitation Management Agent to automate Azure AD B2B Guest Invitations to your Azure AD Tenant
My Azure AD B2B Invitation Management Agent works in two phases;
- Invitation of Users as Guests
- Update of Guests with naming information (Firstname, Lastname, DisplayName)
The Azure AD B2B Invite Management Agent uses my favorite PowerShell Management Agent (the Granfeldt PSMA). I’ve posted many times on how to configure it. See these posts here if you are new to it.
Setting up an Azure AD User Account for the Management Agent
In your Azure AD create a New User that will be used by the Management Agent to invite users to your Azure AD. I named mine B2B Inviter as shown below.
You then want to assign them the Guest inviter role as shown below. This will be enough permissions to invite users to the Azure AD.
However depending on how you want these invitee’s to look, you probably also want their names to be kept consistent with their home Azure AD. To also enable the Management Agent to do that you need to also assign the User administrator role as shown below.
Now log in using that account to Azure AD and change the password. The account is now ready to go.
Management Agent Scripts
The Management Agent uses the Granfeldt PowerShell Management Agent. This is a cut down version of my MIM Azure AD Management Agent.
I’ve kept the schema small with just enough interesting info to facilitate the functionality required. Expand it if you need additional attributes and update the import.ps1 accordingly.
The Import script imports users from the Azure AD Tenant that you will be inviting remote Azure AD users too (as Guests).
- Change line 10 for your file path
- Change line 24 for the version of an AzureAD or AzureADPreview PowerShell Module that you have installed on the MIM Sync Server so that the AuthN Helper Lib can be used. Note if using a recent version you will also need to change the AuthN calls as well as the modules change. See this post here for details.
- Change line 27 for your tenant name
- Change line 47/48 for a sync watermark file
- The Import script also contains an attribute from the MA Schema named AADGuestUser that is a boolean attribute. I create the corresponding attribute in the MetaVerse and MIM Service Schemas for the Person/User objectClasses. This is used to determine when a Guest has been successfully created so their naming attributes can then be updated (using a second synchronisation rule).
The Export script handles the creation (invitation) of users from another azure AD Tenant as Guests as well synchronizing their naming data. It doesn’t include deletion logic, but that is simple enough include a deletion API call based on your MA Deprovisioning logic and requirements.
- By default I’m not sending invitation notifications. If you want to send invitation notifications change “sendInvitationMessage“= $false to $true on Line 129. You should then also change the Invitation Reply URL on line 55 to your Tenant/Application.
- Change Line 10 for the path for the debug logging
- Change Line 24 as per the Import Script if you are using a different version of the help lib
- Change Line 27 for your Azure AD Tenant Name
Declarative Sync Rules
I’m not going to cover import flow configurations on the MS Azure AD B2B MA here. See here for that. Below details how I’ve configured my Invitation MA for the Creation/Export functions. My join rule (configured in the Sync Engine Invitation MA Config) is email address as shown below. Not the best anchor as it isn’t immutable. But as we don’t know what the DN is going to be until after it is created this is the next best thing.
Creation Sync Rule
Here are the three attributes I’m syncing to the B2B Invite Management Agent to perform the invitation. I’m using the mail attribute for the DN as it matches the anchor for the schema. We don’t know what objectID will be assigned until the directory service does it. By using email/upn once created we will get the join and won’t end up with two objects on the MA for the same user.
For Inbound I’m flowing in the AADGuestUser boolean value. You will need to create this attribute in the MetaVerse and then the MIM Service. In the MIM Service allow the Sync Service Account to manage the attribute and change the MIM Service Filter Permissions to allow Admins to use the attribute in Sets. Also on the MIM Service MA add an Export flow from the MV to the MIM Service for AADGuestUser.
Naming Update Sync Rule
The second Sync Rule is to update the guests GivenName, Surname and DisplayName. This sync rule has a dependency on the creation sync rule and has a corresponding Set, Workflow and MPR associated with value of the AADGuestUser boolean attribute populated by the Import script. If True (which it will be after successful creation and the confirming import) the second synchronization rule will be applied.
I will trigger an export flow for the three naming attributes.
Example of Inviting Guests
In this example Rick Sanchez is a member of a guest organisation and meets the criteria of my rules to be invited as a guest to our Tenant. We then, that we get an Add for Rick on the B2B Invite MA.
On export Rick is created in our Azure AD as a Guest User
Rick appears in Azure AD as a Guest via the Azure Portal.
Following the confirming import our second sync rule fires and flows through an update to DisplayName and adds GivenName and Surname.
This naming attributes are then successfully exported.
Going to the Azure AD Portal we see that Rick has indeed been updated.
Azure AD B2B Guest Invitations Notification Email
If you enable notification emails a generic notification email is sent like shown below. The import.ps1 MA script has them disabled by default.
Using a combination of the Microsoft Azure AD B2B Management Agent and my Azure AD B2B Invitation Management Agent you can automate Azure AD B2B Guest Invitations to your Azure AD Tenant.