# Seamless SSO

> Seamless SSO is a setup to allow logging in without the user ever seeing Directus' login page.

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**

```sh
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:

```html
<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 className="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>

<div className="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();
```

</div>
</tabs>

<callout icon="i-lucide-info">

**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.

</callout>

## 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:

```sh
SESSION_COOKIE_SECURE="false"
SESSION_COOKIE_SAME_SITE="lax"
```

Note that no  `SESSION_COOKIE_DOMAIN` value is set.

<callout icon="i-lucide-triangle-alert" 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.

</callout>