Single Sign-On - Directus

Single Sign-On (SSO) is a mechanism which allows to use external providers to login into systems. For example, you can use your Google or Facebook account to authenticate without the need to create a new registration.

::callout{icon="material-symbols:info-outline"} Session Based Authentication In Directus version 10.10.0 the cookie mode has been replaced by the new session mode. The API still supports cookie mode logins for compatibility, however the Data Studio no longer supports cookie mode for logging in. ::

Supported SSO Mechanisms

Directus supports four SSO mechanisms:

::callout{icon="material-symbols:info-outline" to="/configuration/auth-sso"} Check out specific SSO configuration variables for different mechanisms. ::

In order to use these mechanisms you need to create an application/configuration on your preferred external provider, set the environment variables to configure the external provider and, optionally, set the environment variables to configure cookies.

SSO with Directus Behind a Proxy

If Directus is running behind an HTTP(S) proxy, the instance might not be able to reach the configured SSO provider. In such a case, you may want to use the global-agent package, allowing you to configure the corresponding proxy settings.

In this guide, you'll learn how to set up the global-agent package by extending the Directus Docker Image.

::callout{icon="material-symbols:warning-rounded" color="warning"} Security Concerns Due to the fact that the global-agent package needs to intercept all external requests, it can be regarded as a potential attack surface. Especially in critical environments, it's therefore recommended to thoroughly evaluate the impact of such a setup beforehand. ::

Create a patch file to adjust the pm2 configuration file so that global-agent is registered at startup:

diff

diff --git a/ecosystem.config.cjs b/ecosystem.config.cjs
index 5218fda853..4c53cabc80 100644
--- a/ecosystem.config.cjs
+++ b/ecosystem.config.cjs
@@ -10,6 +10,7 @@ module.exports = [
 		name: 'directus',
 		script: 'cli.js',
 		args: ['start'],
+		node_args: ['-r', 'global-agent/bootstrap'],

 		// General
 		instances: process.env.PM2_INSTANCES ?? 1,

In the same directory, create a Dockerfile. Extend the Directus Image, install the global-agent package, and apply the previously created patch file:

dockerfile

FROM directus/directus:11.1.1

USER root
RUN corepack enable
USER node

RUN pnpm install global-agent@3

COPY ecosystem-global-agent.patch .

USER root
RUN <<EOF
	apk add --no-cache patch
	patch -p1 < ecosystem-global-agent.patch || exit 1
	rm ecosystem-global-agent.patch
	apk del patch
EOF
USER node

A new Docker Image can now be built from this customized Dockerfile, and can then be used with the following environment variables to control the proxy configuration:

GLOBAL_AGENT_HTTP_PROXY
GLOBAL_AGENT_HTTPS_PROXY