Office 365 Custom Provisioning
The default Office 365 setup will include Active Directory and DirSync/Azure AD Sync Services to synchronize and provision your AD users in Azure AD for SSO. Auth0 will then be configured to be an identity provider which is providing Single Sign-on (SSO) for these users.
All of this is fine when you want SSO for your own users living in your AD. But for scenarios where you want to allow contractors, partners or even customers to access your Office 365 environment (eg: SharePoint) this approach is not optimal since these users would need to be created in your own AD environment. This is why Auth0 allows custom provisioning of Azure AD users from our rules. This would allow you to create users in Azure AD (and effectively Office 365) just as they login from any connection available in Auth0 (in that case your rule will take over DirSync's task for any type of connection where DirSync would not work). This will allow you to offer Facebook, LinkedIn, G Suite, ... logins to your Office 365 environment.
Configuring Office 365
The Office 365 tutorial explains how to register a custom domain and how to configure Office 365 as a third party application in Auth0. This step is required before custom provisioning can be configured.
Configuring Azure AD
Custom provisioning uses the Azure AD Graph API to provision new users in Azure AD. In order to access the Azure AD Graph API an application must be created within the Azure AD Directory that has been linked to the Office 365 subscription.
- Log into the Azure Portal.
- Choose Azure Active Directory in the left navigation.
- Select App registrations in the new menu.
- Click on New application registration.
- Fill the form:
- Input a name for the application (such as
- Select Web app / API as the Application type.
- Insert a sign-on URL. Any valid url as this won't be really used.
- Input a name for the application (such as
- The recently created app will appear in the App registrations list. Select it.
- In the Settings blade (Microsoft call these sections as blade), choose Keys.
- Input a Description (like
Auth0 Provision) and choose a Duration for the new key. If you choose to issue non-permanent key, take note of the expiration date and create a reminder to replace the key with a new one before it expires.
- Click on save the key and copy the App Key. This key will be shown only once and it's needed for the Auth0 rule.
- Choose Required permissions and click Add in the new blade.
- Select the Microsoft Graph API and then check
Read and write directory dataunder Application Permissions.
- Back in the Required permissions, click on the Grant Permissions button and then click Yes to grant the requested permissions.
Azure AD Provisioning Rule
The following rule shows the provisioning process:
- If the user comes from the AD connection, skip the provisioning process (because this will be handled by DirSync)
- If the user was already provisioned in Azure AD, just continue with the login transaction.
- Get an Access Token of the Graph API using the Azure AD Client ID and Key
- Create a user in Azure AD
- Assign a license to the user.
- Continue with the login transaction.
The username is generated with the
createAzureADUser function, which by default generates a username in the format
email@example.com. You can change this to whatever you like, just make sure this value is unique for all your users.
Make sure you set the correct values for the
AAD_APPLICATION_API_KEY values in your configuration object to make the values available in your rule code.
In the code you'll also see that the rule will wait about 15 seconds after the user is provisioned. This is because it takes a few seconds before the provisioned user is available for Office 365.
The easiest way for your external users to authenticate is by using IdP initiated login: Using smart links or IdP initiated authentication with Office 365.
You will basically need to redirect your users to the following URL (eg: using a "smart link" like
AUTH0_OFFICE365_CLIENT_ID value can be obtained from the URL when working with the Dashboard. When viewing or editing the settings for the Office 365 SSO Integration in Auth0, you will see a URL in the form of
YOUR_CLIENT_ID is the value you need here.
This will show them the Auth0 login page after which they'll be redirected to Office 365. It will be important to explain external users that this is the only way they can authenticate, since the Office 365 login page does not support Home Realm Discover for these external users. This also means that, when they try to open a link, they'll need to visit the smart link first before the can access the link they tried to open.
In this example Fabrikam enabled a few social accounts and a database connection for their Office 365 Third Party application in Auth0.
Certain implementations might require deep linking to SharePoint Online for example. In that case a smart link needs to be constructed which starts on the Office 365 login page:
The first parameter,
YOUR_CUSTOM_DOMAIN should be the domain you've configured in Azure AD for Single Sign-on (SSO) (e.g.,
fabrikam.com). By specifying this as the
whr, Azure AD will know it needs to redirect to Auth0 instead of showing the login page.
DEEP_LINK parameter should be an encoded url within Office 365 (like a page in SharePoint Online, Exchange, ...).