Skip to content

Commit 69acd11

Browse files
hola-soy-milkhola-soy-milk
committed
Finish tightening SSO docs
1 parent 2b0bd06 commit 69acd11

File tree

2 files changed

+69
-115
lines changed

2 files changed

+69
-115
lines changed

‎content/4.auth/7.sso/1.index.md‎

Lines changed: 0 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -29,55 +29,6 @@ Here are the configurations allowed for each one: [SSO configuration](/configura
2929

3030
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.
3131

32-
### OpenID
33-
34-
In this section, we provide some guides to help you set up SSO with OpenID.
35-
36-
#### Google
37-
38-
To be able to use Google OpenID as your external provider you'll need to:
39-
40-
1. Go into [Google Cloud Console](https://console.cloud.google.com)
41-
2. Select or Create a new project
42-
3. Go to [APIs & Services -> OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent) on side
43-
bar
44-
1. Select the access you desire
45-
- Select **Internal** if you only want people within your organization to be able to access
46-
- Select **External** to allow everyone with a Google account
47-
2. Fill the fields according to your preferences
48-
- The **Authorized domains** add an extra layer of security, but it is not required. In case you fill it, should
49-
be the domain where your Directus instance is
50-
3. On Scopes, you need to choose `.../auth/userinfo.email`, `.../auth/userinfo.profile` and `openid`
51-
4. On side bar, go to [Credentials](https://console.cloud.google.com/apis/credentials)
52-
5. Click on [Create Credentials -> OAuth Client ID](https://console.cloud.google.com/apis/credentials/oauthclient)
53-
1. Choose `Web Application` on **Application Type**
54-
2. The **Authorized JavaScript origins** adds an extra layer of security, but it is not required. In case you fill
55-
it, should be the address of your Directus instance. For example, `https://directus.myserver.com`
56-
3. On **Authorized redirect URIs** put your Directus instance address plus `/auth/login/google/callback`. For
57-
example, you should put `https://directus.myserver.com/auth/login/google/callback` where
58-
`https://directus.myserver.com` should be the address of your Directus instance. If you are testing locally you
59-
should add `http://localhost:8055/auth/login/google/callback` too
60-
6. On click **Create**, a modal will appear with **Client ID** and **Client Secret**. Save both somewhere to use later.
61-
62-
7. Now on Directus side, you need to add the following configuration to your `.env` file located on root folder of your
63-
project:
64-
65-
```sh
66-
AUTH_PROVIDERS="google"
67-
68-
AUTH_GOOGLE_DRIVER="openid"
69-
AUTH_GOOGLE_CLIENT_ID="XXXX" # Replace XXXX with the Client ID from Step 6
70-
AUTH_GOOGLE_CLIENT_SECRET="XXXX" # Replace XXXX with the Client Secret from Step 6
71-
AUTH_GOOGLE_ISSUER_URL="https://accounts.google.com"
72-
AUTH_GOOGLE_IDENTIFIER_KEY="email"
73-
AUTH_GOOGLE_ICON="google"
74-
AUTH_GOOGLE_LABEL="Google"
75-
AUTH_GOOGLE_ALLOW_PUBLIC_REGISTRATION="true" # This allows users to be automatically created on logins. Use "false" if you want to create users manually
76-
AUTH_GOOGLE_DEFAULT_ROLE_ID="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX" # Replace this with the Directus Role ID you would want for new users. If this is not properly configured, new users will not have access to Directus
77-
```
78-
79-
8. Now you can see a nice functional `Login with Google` button on Directus login page.
80-
8132
## SSO with Directus behind Proxy
8233

8334
If Directus is running behind an HTTP(S) proxy, the instance might not be able to reach the configured SSO provider. In

‎content/4.auth/7.sso/2.seamless.md‎

Lines changed: 69 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -4,98 +4,101 @@ description:
44

55
# Seamless SSO
66

7-
While sometimes you want your users to directly have access to the Directus Application, in other cases you may need to
7+
While sometimes you want your users to directly have access to the Directus project, in other cases you may need to
88
fetch private data from Directus in your client using external providers. For such cases, a special configuration is
9-
required to work across domains:
9+
required to work across domains.
1010

11-
1. Setup an external provider. You'll find some examples under [Supported SSO mechanisms](#supported-sso-mechanisms).
12-
2. Allow the cookie to be accessible across domains. For that, use the following configuration:
11+
## Implementing Seamless SSO
1312

14-
**Authentication Mode: session**
13+
Setup 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.
1514

16-
```sh
17-
AUTH_<PROVIDER>_MODE="session"
18-
SESSION_COOKIE_DOMAIN="XXXX" # Replace XXXX with the domain of your Directus instance. For example "directus.myserver.com"
19-
SESSION_COOKIE_SECURE="true"
20-
SESSION_COOKIE_SAME_SITE="None"
21-
```
15+
**Authentication Mode: session**
16+
17+
```sh
18+
AUTH_<PROVIDER>_MODE="session"
19+
SESSION_COOKIE_DOMAIN="XXXX"
20+
SESSION_COOKIE_SECURE="true"
21+
SESSION_COOKIE_SAME_SITE="None"
22+
```
23+
24+
**Authentication Mode: cookie (legacy)**
25+
26+
```sh
27+
AUTH_<PROVIDER>_MODE="cookie"
28+
REFRESH_TOKEN_COOKIE_DOMAIN="XXXX" #
29+
REFRESH_TOKEN_COOKIE_SECURE="true"
30+
REFRESH_TOKEN_COOKIE_SAME_SITE="None"
31+
```
2232

23-
**Authentication Mode: cookie (legacy)**
33+
Replace XXXX for either of these modes with the domain of your Directus instance. For example "directus.myserver.com"
2434

25-
```sh
26-
AUTH_<PROVIDER>_MODE="cookie"
27-
REFRESH_TOKEN_COOKIE_DOMAIN="XXXX" # Replace XXXX with the domain of your Directus instance. For example "directus.myserver.com"
28-
REFRESH_TOKEN_COOKIE_SECURE="true"
29-
REFRESH_TOKEN_COOKIE_SAME_SITE="None"
30-
```
35+
On your client, the login button should conform to the following format:
3136

32-
3. On your client, the login button should conform to the following format:
37+
```html
38+
<a
39+
href="https://directus.myserver.com/auth/login/google?redirect=https://client.myserver.com/login"
40+
>Login</a
41+
>
42+
```
3343

34-
```html
35-
<a
36-
href="https://directus.myserver.com/auth/login/google?redirect=https://client.myserver.com/login"
37-
>Login</a
38-
>
39-
```
44+
In the above, `https://directus.myserver.com` should be 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.
4045

41-
- Where `https://directus.myserver.com` should be the address of your Directus instance
42-
- While `https://client.myserver.com/login` should be the address of your client application. The `/login` path is
43-
not necessary, but helps to separate concerns.
46+
On your login page, following the example of `https://client.myserver.com/login`, you need to call the refresh
47+
endpoint either via REST API or via SDK in order to have a session cookie or an `access_token`. Here are some
48+
examples:
4449

45-
4. On your login page, following the example of `https://client.myserver.com/login`, you need to call the refresh
46-
endpoint either via REST API or via SDK in order to have a session cookie or an `access_token`. Here are some
47-
examples:
50+
**Via REST API / Fetch**
4851

49-
- via REST API / fetch
52+
```js
53+
await fetch("https://directus.myserver.com/auth/refresh", {
54+
method: "POST",
55+
credentials: "include",
56+
headers: {
57+
Accept: "application/json",
58+
"Content-Type": "application/json",
59+
},
60+
body: JSON.stringify({ mode: "session" }),
61+
});
62+
```
5063

51-
```js
52-
await fetch("https://directus.myserver.com/auth/refresh", {
53-
method: "POST",
54-
credentials: "include", // this is required in order to send the refresh/session token cookie
55-
headers: {
56-
Accept: "application/json",
57-
"Content-Type": "application/json",
58-
},
59-
body: JSON.stringify({ mode: "session" }), // using 'session' mode, but can also be 'cookie' or 'json'
60-
});
61-
```
64+
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'.
6265

63-
- via SDK in `session` authentication mode
66+
**Via SDK in `session` Authentication Mode**
6467

65-
```js
66-
import { createDirectus, authentication } from "@directus/sdk";
68+
```js
69+
import { createDirectus, authentication } from "@directus/sdk";
6770

68-
const client = createDirectus("https://directus.myserver.com").with(
69-
authentication("session", { credentials: "include" })
70-
);
71+
const client = createDirectus("https://directus.myserver.com").with(
72+
authentication("session", { credentials: "include" })
73+
);
7174

72-
await client.refresh();
73-
```
75+
await client.refresh();
76+
```
7477

75-
- via SDK in legacy `cookie` authentication mode
78+
**Via SDK in Legacy `cookie` Authentication Mode**
7679

77-
```js
78-
import { createDirectus, authentication } from "@directus/sdk";
80+
```js
81+
import { createDirectus, authentication } from "@directus/sdk";
7982

80-
const client = createDirectus("https://directus.myserver.com").with(
81-
authentication("cookie", { credentials: "include" })
82-
);
83+
const client = createDirectus("https://directus.myserver.com").with(
84+
authentication("cookie", { credentials: "include" })
85+
);
8386

84-
await client.refresh();
85-
```
87+
await client.refresh();
88+
```
8689

87-
::: tip Redirect Allow List
90+
::callout{type="info" title="Redirect Allow List"}
8891

8992
To allow Directus to redirect to external domains like `https://client.myserver.com/` used above, you'll need to include
9093
it in the `AUTH_<PROVIDER>_REDIRECT_ALLOW_LIST` security setting.
9194

92-
:::
95+
::
9396

94-
### Testing Seamless SSO locally
97+
## Testing Seamless SSO locally
9598

9699
The above `REFRESH_TOKEN_*` configuration will likely fail for local testing, as usually Directus won't be served under
97-
a valid SSL certificate, which is a requirement for "Secure" cookies. Instead, for local testing purposes (**and local
98-
testing purposes only**), the following configuration can be used:
100+
a valid SSL certificate, which is a requirement for "Secure" cookies. Instead, for local testing purposes (and local
101+
testing purposes only), the following configuration can be used:
99102

100103
**Authentication Mode: session**
101104

@@ -113,9 +116,9 @@ REFRESH_TOKEN_COOKIE_SAME_SITE="lax"
113116

114117
Note that no `REFRESH_TOKEN_COOKIE_DOMAIN` or `SESSION_COOKIE_DOMAIN` value is set.
115118

116-
::: warning Disabling secured cookies
119+
::callout{type="warning" title="Disabling secured cookies"}
117120

118121
The configuration disables secured cookies and should only be used in local environment. Using it in production exposes
119122
your instance to CSRF attacks.
120123

121-
:::
124+
::

0 commit comments

Comments
 (0)