From bd394f5058328115ab3cba428516afc93d8cf1d5 Mon Sep 17 00:00:00 2001
From: Carmen Huidobro <hola@carmenh.dev>
Date: Mon, 27 Jan 2025 21:36:53 +0100
Subject: [PATCH] Add missing OpenID vars (#143)

---
 content/configuration/8.auth-sso.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/content/configuration/8.auth-sso.md b/content/configuration/8.auth-sso.md
index 454425e3..e0813edb 100644
--- a/content/configuration/8.auth-sso.md
+++ b/content/configuration/8.auth-sso.md
@@ -75,11 +75,25 @@ OpenID is an authentication protocol built on OAuth 2.0, and should be preferred
 | `AUTH_<PROVIDER>_LABEL`                     | Text to be presented on SSO button within the Data Studio.                                                | `<PROVIDER>`           |
 | `AUTH_<PROVIDER>_PARAMS`                    | Custom query parameters applied to the authorization URL.                                                 |                        |
 | `AUTH_<PROVIDER>_REDIRECT_ALLOW_LIST`       | A comma-separated list of external URLs (including paths) allowed for redirecting after successful login. |                        |
+| `AUTH_<PROVIDER>_ROLE_MAPPING`                    | A JSON object in the form of `{ "openid_group_name": "directus_role_id" }` that you can use to map OpenID groups to Directus roles <sup>[3]</sup>. If not specified, falls back to `AUTH_<PROVIDER>_DEFAULT_ROLE_ID` URL.                                                 |                        |
+| `AUTH_<PROVIDER>_GROUP_CLAIM_NAME`       | The name of the OIDC claim that contains your user's groups. |  `groups`                      |
 
 <sup>[1]</sup> When authenticating, Directus will match the identifier value from the external user profile to a Directus users "External Identifier".
 
 <sup>[2]</sup> `sub` represents a unique user identifier defined by the OpenID provider. For users not relying on `PUBLIC_REGISTRATION` it is recommended to use a human-readable identifier, such as `email`.
 
+<sup>[3]</sup> As Directus only allows one role per user, evaluating stops after the first match. An OpenID user that is member of both e.g. developer and admin groups may be assigned different roles depending on the order that you specify your role-mapping in: In the following example said OpenID user will be assigned the role `directus_developer_role_id`
+
+```
+AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "developer": "directus_developer_role_id", "admin": "directus_admin_role_id" }"
+```
+
+Whereas in the following example the OpenID user will be assigned the role `directus_admin_role_id`:
+
+```
+AUTH_<PROVIDER>_ROLE_MAPPING: json:{ "admin": "directus_admin_role_id", "developer": "directus_developer_role_id" }"
+```
+
 ## LDAP (`ldap`)
 
 LDAP allows Active Directory users to authenticate and use Directus without having to be manually configured. User information and roles will be assigned from Active Directory.