Feb 6, 2022 7 min read Getting Started

How to add Single Sign On (SSO) to Directus in 2 Steps

Use Facebook, Google, Microsoft/Azure AD and others to sign into your Directus system.

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. This article will show you how to add the settings into Directus for 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 Single Sign On (SSO) to Directus, obtain a client ID and client secret from your authentication provider and add them to your env configuration file along with the required parameters below.

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 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 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 app" 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"

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

In the example above anyone from Google can login to your Directus becuase Public Registration is set to true. Make sure to set the default role with permissions that is acceptable for public access. Alternatively, set the Public Registration to false and create the users manually in Directus with the email address set to @gmail.com and the password left empty. Only those whose email address matches a user account in Directus will be able to log in.

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

As stated above, Public Registration set to true will allow anyone to have an account. 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. Once again, new user accounts will adopt the Default Role ID.

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

As with Google, in the example above anyone from Facebook can login to your Directus becuase Public Registration is set to true. Make sure to set the default role with permissions that is acceptable for public access. Alternatively, set the Public Registration to false and create the users manually in Directus with the email address set to @gmail.com and the password left empty. Only those whose email address matches a user account in Directus will be able to log in.

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

Same again for this example, any Yahoo account can access you Directus with this configuration.

Not all websites support OpenID but still have OAuth. In this scenario, use the following code:

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

Note the Issuer URL parameter is now 3 URL parameters. This is the legacy method.

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.

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"

Example of Facebook icon options in font awesome brands

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.

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.