# Single Sign-On

> Single Sign-On is a mechanism which allows to use external providers to login into systems.

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="i-lucide-info">

**Session Based Authentication**
In [Directus version 10.10.0](/releases/breaking-changes) 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.

</callout>

## Supported SSO Mechanisms

Directus supports four SSO mechanisms:

- [OpenID](https://openid.net/specs/openid-connect-core-1_0.html)
- [OAuth 2.0](https://www.ietf.org/rfc/rfc6750.txt)
- [LDAP](https://datatracker.ietf.org/doc/html/rfc4511)
- [SAML](https://datatracker.ietf.org/doc/html/rfc7522)

<callout icon="i-lucide-info" to="/configuration/auth-sso">

Check out specific SSO configuration variables for different mechanisms.

</callout>

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`](https://www.npmjs.com/package/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="i-lucide-triangle-alert" 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.

</callout>

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

```diff [ecosystem-global-agent.patch]
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`