Seamless SSO

While sometimes you want your users to directly have access to the Directus project, in other cases you may need to fetch private data from Directus in your application using external providers.

Implementing Seamless SSO

Set up an external provider. You'll find some examples further down below. Allow the cookie to be accessible across domains. There are two authentication mechanisms for this.

Authentication Mode: session

AUTH_<PROVIDER>_MODE="session"
SESSION_COOKIE_DOMAIN="XXXX"
SESSION_COOKIE_SECURE="true"
SESSION_COOKIE_SAME_SITE="None"

Replace XXXX for either of these modes with the domain of your Directus instance. For example "directus.myserver.com"

On your client, the login button should conform to the following format:

<a
  href="https://directus.myserver.com/auth/login/google?redirect=https://client.myserver.com/login"
  >Login</a
>

Replace https://directus.myserver.com with the address of your Directus instance, while https://client.myserver.com/login should be the address of your client application. The /login path is not necessary, but helps to separate concerns.

On your login page, following the example of https://client.myserver.com/login, you need to call the refresh endpoint either via REST API or via SDK in order to have a session cookie or an access_token. Here are some examples:

::tabs ::div{class="pr-6"}

label: Via REST API / Fetch

```js
await fetch("https://directus.myserver.com/auth/refresh", {
  method: "POST",
  credentials: "include",
  headers: {
    Accept: "application/json",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ mode: "session" }),
});
```

In the above, `credentials` is required in order to send the refresh/session token cookie. This is using `'session'` mode, but it can also be 'cookie' or 'json'.

::

::div{class="pr-6"}

label: Via SDK in session Authentication Mode

```js
import { createDirectus, authentication } from "@directus/sdk";

const client = createDirectus("https://directus.myserver.com").with(
  authentication("session", { credentials: "include" })
);

await client.refresh();
```

:: ::

::callout{icon="material-symbols:info-outline"} Redirect Allow List To allow Directus to redirect to external domains like https://client.myserver.com/ used above, you'll need to include it in the AUTH_<PROVIDER>_REDIRECT_ALLOW_LIST security setting. ::

Testing Seamless SSO Locally

Locally, Directus won't be served under a valid SSL certificate, which is a requirement for "Secure" cookies. Instead, for local testing purposes (and local testing purposes only), the following configuration can be used when using session authentication:

SESSION_COOKIE_SECURE="false"
SESSION_COOKIE_SAME_SITE="lax"

Note that no SESSION_COOKIE_DOMAIN value is set.

::callout{icon="material-symbols:warning-rounded" color="warning"} Disabling Secured Cookies The configuration disables secured cookies and should only be used in local environment. Using it in production exposes your instance to CSRF attacks. ::