How to use OAuth 2.0 with Directus

OAuth 2.0 is a mechanism which allows you to login to Directus using an external provider such as Facebook, Google, Microsoft, Yahoo or Github 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. This article will show you how to add the settings into Directus for 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 OAuth 2 to Directus, obtain a client ID, client secret and URLs from your authentication provider and add them to your env configuration file along with the required parameters below.

• AUTH_<PROVIDER>_DRIVER=oauth2
• AUTH_<PROVIDER>_CLIENT_ID
• AUTH_<PROVIDER>_CLIENT_SECRET
• AUTH_<PROVIDER>_SCOPE (openid profile email)
• AUTH_<PROVIDER>_AUTHORIZE_URL
• AUTH_<PROVIDER>_ACCESS_URL
• AUTH_<PROVIDER>_PROFILE_URL
• 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)

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 and the supplier.

https://<YOUR DIRECTUS ADDRESS>/auth/login/<SUPPLIER>/callback

Examples:
https://directus.example.com/auth/login/google/callback
https://directus.example.com/auth/login/microsoft/callback
https://directus.example.com/auth/login/facebook/callback
https://directus.example.com/auth/login/yahoo/callback

I've collected guides for various providers:

• Microsoft/Azure AD
• Google
• Facebook (App ID & Secret is in Settings -> Basic)
• Yahoo

You can check other services by searching for "<service name> OAuth" in your favourite search engine.

It's Important to be aware and up to date with the changes for the providers you choose. Facebook are always changing their APIs and may require you to update your application version or risk loosing your login. Microsft have expiry dates on their Client ID and 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"

Oauth 2.0 Example

Here is an example of OAuth 2.0 for Github:

AUTH_PROVIDERS="github"

AUTH_GITHUB_DRIVER="oauth2"
AUTH_GITHUB_CLIENT_ID="99d3...c3c4"
AUTH_GITHUB_CLIENT_SECRET="34ae...f963"
AUTH_GITHUB_AUTHORIZE_URL="https://github.com/login/oauth/authorize"
AUTH_GITHUB_ACCESS_URL="https://github.com/login/oauth/access_token"
AUTH_GITHUB_PROFILE_URL="https://api.github.com/user"
AUTH_GITHUB_ICON="github"
AUTH_GITHUB_ALLOW_PUBLIC_REGISTRATION="true" # This allows users to be automatically created on logins. Use "false" if you want to create users manually
AUTH_GITHUB_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

This will add a button to the login screen to use Github as an authentication method.

OpenID

Some providers like Microsoft, Facebook and Google are adopting OpenID as a uniform standard for OAuth authentication. Instead of needing 3 URLs in your configuration, you only need 1.

OpenID Examples

This example is for Google:

AUTH_PROVIDERS="google"

AUTH_GOOGLE_DRIVER="openid"
AUTH_GOOGLE_CLIENT_ID="XXXX" # Replace XXXX with the App ID (Client ID)
AUTH_GOOGLE_CLIENT_SECRET="XXXX" # Replace XXXX with the App Secret (Client Secret)
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com"
AUTH_GOOGLE_IDENTIFIER_KEY="email"
AUTH_GOOGLE_ICON="google"
AUTH_GOOGLE_ALLOW_PUBLIC_REGISTRATION="true" # This allows users to be automatically created on logins. Use "false" if you want to create users manually
AUTH_GOOGLE_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

Another example for Microsoft:

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

Another example for Facebook:

AUTH_PROVIDERS="facebook"

AUTH_FACEBOOK_DRIVER="openid"
AUTH_FACEBOOK_CLIENT_ID="XXXX" # Replace XXXX with the App ID
AUTH_FACEBOOK_CLIENT_SECRET="XXXX" # Replace XXXX with the App Secret
AUTH_FACEBOOK_ISSUER_URL="https://www.facebook.com/.well-known/openid-configuration/"
AUTH_FACEBOOK_SCOPE="openid profile email"
AUTH_FACEBOOK_IDENTIFIER_KEY="sub"
AUTH_FACEBOOK_ICON="facebook"
AUTH_FACEBOOK_ALLOW_PUBLIC_REGISTRATION="true" # This allows users to be automatically created on logins. Use "false" if you want to create users manually
AUTH_FACEBOOK_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

Another example for Yahoo:

AUTH_PROVIDERS="yahoo"

AUTH_YAHOO_DRIVER="openid"
AUTH_YAHOO_CLIENT_ID="XXXX" # Replace XXXX with the App ID
AUTH_YAHOO_CLIENT_SECRET="XXXX" # Replace XXXX with the App Secret
AUTH_YAHOO_ISSUER_URL="https://api.login.yahoo.com/.well-known/openid-configuration"
AUTH_YAHOO_SCOPE="openid profile email"
AUTH_YAHOO_IDENTIFIER_KEY="sub"
AUTH_YAHOO_ICON="yahoo"
AUTH_YAHOO_ALLOW_PUBLIC_REGISTRATION="true" # This allows users to be automatically created on logins. Use "false" if you want to create users manually
AUTH_YAHOO_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

To find out the Issuer ID for a provider, search for the company name followed by openid well-known.

Here is the full documentation from Directus

Identifier Key

You will notice the Identifier Key on Google is set to email but Microsoft and the others are set to sub. This is up to you which one you prefer. The reason I prefer sub is becuase in Facebook, user's can change their email address. In this scenario, Directus will maintain the connection to their account. If it was set to email, a new account 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.

Login Icons

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_FACEBOOK_ICON="facebook"
# or
AUTH_FACEBOOK_ICON="facebook_f"

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.

To help resolve the issue, test one SSO provider at a time. It may be that a require parameter has not be added.

3rd Party Login Issues

If you configuration is valid and Directus is running, but when you try to login using one of the SSO providers, 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

Conclusion

We covered quite a lot in this article including where to create a client ID/Secret and what parameters to add to Directus. 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.