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>_SCOPE (openid profile email)
- 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 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.
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
- Facebook (App ID & Secret is in Settings -> Basic)
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.
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.
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.
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
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.
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_FACEBOOK_ICON="facebook" # or AUTH_FACEBOOK_ICON="facebook_f"
Now that you have finished, you need to restart the service that runs Directus.
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
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.