Feb 23, 2022 5 min read Getting Started

How to add Microsoft Azure Login to Directus

Adding Microsoft Azure login to Directus allows your organisation or other Azure members to login to Directus using their Microsoft Account.

Adding Microsoft Azure login to Directus allows your organisation or other Azure members to login to Directus using their Microsoft Account. This can be limited to your tenancy or open to anyone. This article will show you how to add the settings into Directus using OpenID and OAuth 2. For more information on OAuth 2, Amazon have a great range of books for beginners through to advanced usage - OAuth 2 on Amazon.

To add Microsoft Azure login to Directus, create a new enterprise app in the Azure Portal and obtain a client ID and client secret. Add these to your env configuration file along with the required parameters.

Required Parameters

AUTH_<PROVIDER>_DRIVER (oauth2 or openid)
AUTH_<PROVIDER>_CLIENT_ID
AUTH_<PROVIDER>_CLIENT_SECRET
AUTH_<PROVIDER>_SCOPE (openid profile email)
AUTH_<PROVIDER>_ISSUER_URL (location of /.well-known/openid-configuration)
AUTH_<PROVIDER>_IDENTIFIER_KEY (email or sub)
AUTH_<PROVIDER>_ICON (icon id from library)
AUTH_<PROVIDER>_ALLOW_PUBLIC_REGISTRATION (true or false)
AUTH_<PROVIDER>_DEFAULT_ROLE_ID (Role ID from Directus)

What is SSO?

Single Sign On (SSO) is a mechanism which allows you to login to Directus using an external provider such as Facebook, Google or Microsoft without the need to create new accounts. Since most devices will already be logged into one or more of these services, the user will be logged in automatically. When moving between multiple systems, this can save a lot of time and hassle.

What is OAuth 2.0

OAuth 2.0 (Open Authentication) is standard to allow websites to request user authentication from an external provider. It works by exchanging tokens between the website and the supplier along with some basic information about the user such as and email address and a name. It is up to the supplier if they share more information about their users but in most cases they will have a API for access to more information. OAuth is usually offered through the suppliers developer program. You can read more about OAuth 2 on Amazon - OAuth 2 on Amazon.

What is OpenID?

OpenID is an extension of OAuth to make the process simpler for developers. Instead of specifying all the endpoints required during the OAuth process, OpenID provides a configration file that contains all the settings.

1. Request Settings from Service Provider

In this step, you will need to create an application on the suppliers development portal which will give us the credentials for SSO, an Application ID and Secret. You will be asked for the Redirect URL or Callback URL, use the following URL but make sure to use your Directus address.

https://directus.example.com/auth/login/microsoft/callback

Here is the official guide from Microsoft to create a Client ID and Secret:

Microsoft/Azure AD Guide

It's Important to be aware and up to date with the changes for the providers you choose. Microsoft have expiry dates on their Client Secret which needs to be recreated periodically (~ 1 - 2 years). Please factor these into your development strategies.

Already have an OAuth App ID and Secret?

Some providers allow you to use one App ID and Secret across multiple websites as long as you supply the callback URLs within the application.

2. Configure Directus

Open your project folder where you installed Directus. There is a hidden file called .env. Open this with your preferred editor. I've include examples from some common providers.

Multiple Providers

If you want to have multiple providers, you need to add them all to the one AUTH_PROVIDERS parameter. All the other paramenter contain the providers name and can be listed after each other.

AUTH_PROVIDERS="google microsoft facebook yahoo"

Microsoft Parameters

Copy the code below and make sure to update the Client ID, Client Secret, Issuer URL and the default Role ID. Read the comments carefully.

AUTH_PROVIDERS="microsoft"

AUTH_MICROSOFT_DRIVER="openid"
AUTH_MICROSOFT_CLIENT_ID="XXXX" # Replace XXXX with the App ID (Client ID)
AUTH_MICROSOFT_CLIENT_SECRET="XXXX" # Replace XXXX with the App Secret (Client Secret)
AUTH_MICROSOFT_ISSUER_URL="https://login.microsoftonline.com/XXXX/v2.0/.well-known/openid-configuration" # Replace XXXX with your tenant ID or "common"
AUTH_MICROSOFT_SCOPE="openid profile email"
AUTH_MICROSOFT_IDENTIFIER_KEY="sub"
AUTH_MICROSOFT_ICON="microsoft"
AUTH_MICROSOFT_ALLOW_PUBLIC_REGISTRATION="true" # This allows users to be automatically created on logins. Use "false" if you want to create users manually
AUTH_MICROSOFT_DEFAULT_ROLE_ID="XXXX" # Replace XXXX with the role ID you would want for new users. If this is not properly configured, new users will not have access to Directus

When Public Registration is set to true, Directus will automatically create a user account for anyone. However, in Azure, we can limit our application to our own tenancy. For organisations and Universities, this will just allow your user's to have access. A new user account will adopt the Default Role ID. It's good practice to have a limited default role to prevent unwanted changes to your data. Users can always contact you for elevated privileges.

If you set Public Registration to false, only users that have an account that matches your Identifier Key will be allowed access. In this scenario it will be better to change the Identifier key to email.

Here is the full documentation from Directus

Identifier Key

You will notice the Identifier Key on Microsoft is set to sub. Alternatively this can be set to email. It's up to you which one you prefer. The reason I prefer sub is becuase user's may change their email address where as the sub is their account ID. If it was set to email, and the email address change on their account, a new account in Directus will be created or the login will return as unauthorised depending how Public Registration is set.

Scope

The scope is the same among all OpenID / OAuth providers. If you choose to remove the parameter, it will default to "openid profile email". If for any reason you need to change this, the option is there.

Directus uses the FontAwesome Brands library for the login buttons. You can view the library at fontawesome.com. Click Icons, then filter by brands. You can choose any icon from the collection but you must convert any hyphens (-) to underscore (_). As an example:

AUTH_MICROSOFT_ICON="microsoft"

Restart Directus

Now that you have finished, you need to restart the service that runs Directus.

Troubleshooting

Sometimes errors occur which will prevent Directus from starting. Check your Directus Status or manually run Directus with npx directus start. This will output where the error occured.

If you configuration is valid and Directus is running, but when you try to login, you get one of the connection errors. You will need to check the following:

The callback URL has been added to the Service Providers Developers portal. See Step 1.
Check the Client ID and Client Secret are correct, (aka App ID and App Secret)
Check the Scope and Identifier Key is supported by opening this URL https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration. Optional: replace common with your tenant ID

Conclusion

We covered how to add Microsoft Azure login to Directus and what settings you need to include. I'm hoping you can use what you've learned to include other service providers as needed such as Twitter and TikTok. I also covered potential issues with service provider credentials requiring maintenance and to be aware and plan for this.