Authentication & SSO

:partial{content="config-env-vars"}

Directus offers a variety of authentication methods, including local email/password, OAuth 2.0, OpenID, LDAP, and SAML.

For each of the auth providers listed, you must provide the following configuration (variable name must be uppercase in these options):

::callout{icon="material-symbols:info-outline"} Cookie and session configuration settings such as REFRESH_TOKEN_COOKIE_*, SESSION_COOKIE_*, and related security parameters can be found in Security & Limits. ::

Based on your configured drivers, you must also provide additional variables, where <PROVIDER> is the capitalized name of the item in the AUTH_PROVIDERS value.

::callout{icon="material-symbols:warning-rounded" color="warning"} PUBLIC_URL and AUTH_ALLOWED_PUBLIC_URLS

• Our oauth2, openid and saml SSO drivers rely on PUBLIC_URL for redirection, with oauth2 and openid also using it for the callback URL generation. If set incorrectly, the login process for these drivers may behave unexpectedly.
• In environments where the API is accessible from multiple domains, AUTH_ALLOWED_PUBLIC_URLS should be configured for the domains you wish to support SSO sign-in. When a request's origin matches an entry, the corresponding PUBLIC_URL is used for the login flow. If no match is found, the default PUBLIC_URL is used instead.

Example:

PUBLIC_URL="https://<your_primary_domain>"
AUTH_ALLOWED_PUBLIC_URLS="https://<your_secondary_domain>,https://<your_tertiary_domain>"

Cookie Limitations

• Subdomains of the same parent domain: Since they share a common parent domain (e.g. api.example.com and admin.example.com), the cookie domain should be set to the parent domain prefixed by . (e.g .example.com) so the session will be shared across both subdomains. Loggins in on one subdomain will result in a session valid for all subdomains.
• Different domains: Because they are separate domains (e.g. example.com and example.org), the cookie domain should be left unset. Due to browser security restrictions, cookies cannot be shared across different domains. Each domain will maintain its own independent session, logging in on one domain will not result in a valid session on the other.

::

Local (local)

The default Directus email/password authentication flow. No additional configuration required.

OAuth 2.0

^[1] When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".

^[2] As Directus only allows one role per user, evaluating stops after the first match. An OAuth user that is member of both e.g. developer and admin groups may be assigned different roles depending on the order that you specify your role-mapping in: In the following example said OAuth user will be assigned the role directus_developer_role_id

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "developer": "directus_developer_role_id", "admin": "directus_admin_role_id" }"

Whereas in the following example the OAuth user will be assigned the role directus_admin_role_id:

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "admin": "directus_admin_role_id", "developer": "directus_developer_role_id" }"

OpenID Connect

OpenID Connect (OIDC) is an authentication protocol built on OAuth 2.0, and should be preferred over standard OAuth 2.0 where possible.

^[1] To ensure correct parsing the env must be prefixed with json:.

^[2] When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".

^[3] sub represents a unique user identifier defined by the OIDC provider. For users not relying on PUBLIC_REGISTRATION it is recommended to use a human-readable identifier, such as email.

^[4] As Directus only allows one role per user, evaluating stops after the first match. An OIDC user that is member of both e.g. developer and admin groups may be assigned different roles depending on the order that you specify your role-mapping in: In the following example said OIDC user will be assigned the role directus_developer_role_id

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "developer": "directus_developer_role_id", "admin": "directus_admin_role_id" }"

Whereas in the following example the OIDC user will be assigned the role directus_admin_role_id:

AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "admin": "directus_admin_role_id", "developer": "directus_developer_role_id" }"

LDAP (ldap)

LDAP allows Active Directory users to authenticate and use Directus without having to be manually configured. User information and roles will be assigned from Active Directory.

^[1] The bind user must have permission to query users and groups to perform authentication. Anonymous binding can by achieved by setting an empty value for BIND_DN and BIND_PASSWORD.

^[2] The scope defines the following behaviors:

• base: Limits the scope to a single object defined by the associated DN.
• one: Searches all objects within the associated DN.
• sub: Searches all objects and sub-objects within the associated DN.

^[3] If GROUP_DN is specified, the user's role will always be updated on authentication to a matching group configured in AD, or fallback to the DEFAULT_ROLE_ID.

SAML

SAML is an open-standard, XML-based authentication framework for authentication and authorization between two entities without a password.

• Service provider (SP) agrees to trust the identity provider to authenticate users.
• Identity provider (IdP) authenticates users and provides to service providers an authentication assertion that indicates a user has been authenticated.

^[1] When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".

The SP_metadata and IDP_metadata variables should be set to the XML metadata provided by the service provider and identity provider respectively.

:::callout{icon="material-symbols:warning-rounded" color="warning"} SAML Attribute Keys

Most identity providers send simple attribute names like email rather than the full XML schema URIs shown as defaults above. Set IDENTIFIER_KEY and EMAIL_KEY to match your identity provider's attribute names. Make sure to check the attribute statements in your IdP's SAML configuration.

Unlike OAuth 2.0, there is no fallback from IDENTIFIER_KEY to EMAIL_KEY. If the configured identifier key is not found in the SAML response, authentication will fail. :::

Multiple Auth Providers

You can configure multiple providers for handling authentication in Directus. This allows for different options when logging in. To do this, provide a comma-separated list of provider names, and a config block for each provider. For example;

AUTH_PROVIDERS="google,facebook"

AUTH_GOOGLE_DRIVER="openid"
AUTH_GOOGLE_CLIENT_ID="830d...29sd"
AUTH_GOOGLE_CLIENT_SECRET="la23...4k2l"
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com/.well-known/openid-configuration"
AUTH_GOOGLE_IDENTIFIER_KEY="email"
AUTH_GOOGLE_ICON="google"
AUTH_GOOGLE_LABEL="Google"

AUTH_FACEBOOK_DRIVER="oauth2"
AUTH_FACEBOOK_CLIENT_ID="830d...29sd"
AUTH_FACEBOOK_CLIENT_SECRET="jd8x...685z"
AUTH_FACEBOOK_AUTHORIZE_URL="https://www.facebook.com/dialog/oauth"
AUTH_FACEBOOK_ACCESS_URL="https://graph.facebook.com/oauth/access_token"
AUTH_FACEBOOK_PROFILE_URL="https://graph.facebook.com/me?fields=email"
AUTH_FACEBOOK_ICON="facebook"
AUTH_FACEBOOK_LABEL="Facebook"

::callout{icon="material-symbols:info-outline"} Multiple Providers Directus users can only authenticate using the auth provider they are created with. It is not possible to authenticate with multiple providers for the same user. ::

Example Auth Provider Configurations

Below is a collection of example Directus configurations for integrating with various OpenID, OAuth 2.0 and SAML platforms. Due to the large number of available SSO platforms, this list will only cover the most common configurations. Contributions to expand and maintain the list are encouraged.

OpenID

Apple

AUTH_APPLE_DRIVER="openid"
AUTH_APPLE_CLIENT_ID="..."
AUTH_APPLE_CLIENT_SECRET="..."
AUTH_APPLE_ISSUER_URL="https://appleid.apple.com/.well-known/openid-configuration"
AUTH_APPLE_SCOPE="name email"
AUTH_APPLE_IDENTIFIER_KEY="email"
AUTH_APPLE_PARAMS="{"response_mode":"form_post"}"

Auth0

AUTH_AUTH0_DRIVER="openid"
AUTH_AUTH0_CLIENT_ID="..."
AUTH_AUTH0_CLIENT_SECRET="..."
AUTH_AUTH0_ISSUER_URL="https://<your_auth0_domain>/.well-known/openid-configuration"
AUTH_AUTH0_IDENTIFIER_KEY="email"

Google

AUTH_GOOGLE_DRIVER="openid"
AUTH_GOOGLE_CLIENT_ID="..."
AUTH_GOOGLE_CLIENT_SECRET="..."
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com/.well-known/openid-configuration"
AUTH_GOOGLE_IDENTIFIER_KEY="email"

Keycloak

AUTH_KEYCLOAK_DRIVER="openid"
AUTH_KEYCLOAK_CLIENT_ID="..."
AUTH_KEYCLOAK_CLIENT_SECRET="..."
# For Keycloak < 18.0.0
AUTH_KEYCLOAK_ISSUER_URL="http://<your_keycloak_domain>/auth/realms/<your_keycloak_realm>/.well-known/openid-configuration"
# For Keycloak >= 18.0.0
AUTH_KEYCLOAK_ISSUER_URL="http://<your_keycloak_domain>/realms/<your_keycloak_realm>/.well-known/openid-configuration"
AUTH_KEYCLOAK_IDENTIFIER_KEY="email"

Microsoft Azure

AUTH_MICROSOFT_DRIVER="openid"
AUTH_MICROSOFT_CLIENT_ID="..."
AUTH_MICROSOFT_CLIENT_SECRET="..."
AUTH_MICROSOFT_ISSUER_URL="https://login.microsoftonline.com/<your_tenant_id>/v2.0/.well-known/openid-configuration"
AUTH_MICROSOFT_IDENTIFIER_KEY="email"

Okta

AUTH_OKTA_DRIVER="openid"
AUTH_OKTA_CLIENT_ID="..."
AUTH_OKTA_CLIENT_SECRET= "..."
AUTH_OKTA_ISSUER_URL="https://<your_okta_domain>/.well-known/openid-configuration"
AUTH_OKTA_IDENTIFIER_KEY="email"

Twitch

AUTH_TWITCH_DRIVER="openid"
AUTH_TWITCH_CLIENT_ID="..."
AUTH_TWITCH_CLIENT_SECRET="..."
AUTH_TWITCH_ISSUER_URL="https://id.twitch.tv/oauth2/.well-known/openid-configuration"
AUTH_TWITCH_SCOPE="openid user:read:email"
AUTH_TWITCH_PARAMS__CLAIMS="string:{"id_token":{"email":null}}"
AUTH_TWITCH_IDENTIFIER_KEY="email"

OAuth 2.0

Discord

AUTH_DISCORD_DRIVER="oauth2"
AUTH_DISCORD_CLIENT_ID="..."
AUTH_DISCORD_CLIENT_SECRET="..."
AUTH_DISCORD_AUTHORIZE_URL="https://discord.com/api/oauth2/authorize"
AUTH_DISCORD_ACCESS_URL="https://discord.com/api/oauth2/token"
AUTH_DISCORD_PROFILE_URL="https://discord.com/api/users/@me"

Facebook

AUTH_FACEBOOK_DRIVER="oauth2"
AUTH_FACEBOOK_CLIENT_ID="..."
AUTH_FACEBOOK_CLIENT_SECRET="..."
AUTH_FACEBOOK_AUTHORIZE_URL="https://www.facebook.com/dialog/oauth"
AUTH_FACEBOOK_ACCESS_URL="https://graph.facebook.com/oauth/access_token"
AUTH_FACEBOOK_PROFILE_URL="https://graph.facebook.com/me?fields=email"

GitHub

AUTH_GITHUB_DRIVER="oauth2"
AUTH_GITHUB_CLIENT_ID="..."
AUTH_GITHUB_CLIENT_SECRET="..."
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"

::callout{icon="material-symbols:warning-rounded" color="warning"}

If the authenticating user has not marked their email as "public" in GitHub, it will not be accessible by Directus.

::

Twitter

AUTH_TWITTER_DRIVER="oauth2"
AUTH_TWITTER_CLIENT_ID="..."
AUTH_TWITTER_CLIENT_SECRET="-..."
AUTH_TWITTER_AUTHORIZE_URL="https://twitter.com/i/oauth2/authorize"
AUTH_TWITTER_ACCESS_URL="https://api.twitter.com/2/oauth2/token"
AUTH_TWITTER_PROFILE_URL="https://api.twitter.com/2/users/me"
AUTH_TWITTER_IDENTIFIER_KEY="data.username"
AUTH_TWITTER_SCOPE="tweet.read users.read"

::callout{icon="material-symbols:warning-rounded" color="warning"}

Twitter does not provide "email" so we define "username" as the identifier.

::

SAML

AWS

AUTH_AWS_DRIVER="saml"
AUTH_AWS_IDP_metadata="{Your IAM Identity Center SAML metadata file}"
AUTH_AWS_SP_metadata=""
AUTH_AWS_ALLOW_PUBLIC_REGISTRATION="true"
AUTH_AWS_DEFAULT_ROLE_ID="{Needs to be a valid role on the instance}"
AUTH_AWS_IDENTIFIER_KEY="email"
AUTH_AWS_EMAIL_KEY="email"

::callout{icon="material-symbols:warning-rounded" color="warning"} Metadata

• AWS IAM Docs are not that verbose. Users have found that the SP_metadata environment variable can be supplied empty.
• Users have found that replacing <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://your-soo-portal-url"/> in the IAM Identity Center SAML metadata file with your AWS Portal URL is a fix for getting the 'Login With SSO' button on Directus to work, rather the default redirect from AWS.
• Directus expects <?xml version="1.0" encoding="UTF-8"?> to be removed from the start of the XML.

::

Mapping:

Maps the email address into Directus as external_identifier:

Config:

• Relay state: admin/login
• Application ACS URL: https://your-directus-instance/auth/login/aws/acs

Google

AUTH_GOOGLE_DRIVER="saml"
AUTH_GOOGLE_IDP_metadata="{Your SAML metadata file from Google}"
AUTH_GOOGLE_SP_metadata="{Create your own SAML metadata file, see example below}"
AUTH_GOOGLE_ALLOW_PUBLIC_REGISTRATION="true"
AUTH_GOOGLE_DEFAULT_ROLE_ID="{Needs to be a valid role on the instance}"
AUTH_GOOGLE_IDENTIFIER_KEY="email"
AUTH_GOOGLE_EMAIL_KEY="email"

::callout{icon="material-symbols:warning-rounded" color="warning"} SP Metadata

• The entityID should be the same as the one configured in Google in the EntityDescriptor tag
• The Location should be the ACS URL of your Directus instance in the format of https://your-directus-instance/auth/login/google/acs
• Directus expects <?xml version="1.0" encoding="UTF-8"?> to be removed from the start of the XML.

Example

<EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="SHOULD_MATCH_GOOGLE_CONFIG">
  <SPSSODescriptor WantAssertionsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService isDefault="true" index="0" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="YOUR_DOMAIN/auth/login/google/acs"/>
  </SPSSODescriptor>
</EntityDescriptor>

::