Update from code changes: document OAuth token claims for groups

deploy/authentication-setup.mdx

@@ -99,7 +99,7 @@
 ### OAuth 2.0 prerequisites
 
 * An OAuth or OIDC server that supports the Authorization Code Flow.
-* Ability to create an API endpoint accessible by OAuth access tokens (optional, to enable group-based access control).
+* For group-based access control, either an OAuth or OIDC server that returns groups in the `id_token` or `access_token`, or the ability to create an API endpoint accessible by OAuth access tokens.
 
 ### OAuth 2.0 setup
 
@@ -116,7 +116,8 @@
       * **Scopes** (optional): Permissions to request. Copy the **entire** scope string (for example, for a scope like `provider.users.docs`, copy the complete `provider.users.docs`). Use multiple scopes if you need different access levels.
       * **Additional authorization parameters** (optional): Additional query parameters to add to the initial authorization request.
       * **Token URL**: Your OAuth token exchange endpoint.
-      * **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info. Required for group-based access control. If omitted, the OAuth flow only verifies identity.
+      * **Token claims** (optional): Derive user groups directly from the JWT returned by your token endpoint, instead of hosting a separate user info endpoint. See [Derive groups from token claims](#derive-groups-from-token-claims).
+      * **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info. Use this for group-based access control if your provider does not return groups in the `id_token` or `access_token`. If you omit both **Token claims** and **Info API URL**, the OAuth flow only verifies identity.
       * **Logout URL** (optional): The native logout URL for your OAuth provider. When users log out, Mintlify validates the logout redirect against this configured URL for security. The redirect only succeeds if it exactly matches the configured `logoutUrl`. If you do not configure a logout URL, users redirect to `/login`. Mintlify redirects users with a `GET` request and does not append query parameters, so include any parameters (for example, `returnTo`) directly in the URL.
       * **Redirect URL** (optional): The URL to redirect users to after authentication.
     6. Click **Save changes**.
@@ -139,6 +140,51 @@
   </Step>
 </Steps>
 
+### Derive groups from token claims
+
+If your OAuth or OIDC provider already returns group membership in the `id_token` or `access_token`, you can skip hosting a user info endpoint and let Mintlify read groups directly from the token that your token endpoint returns.
+
+When you configure **Token claims**, Mintlify:
+
+* Decodes the configured token from the token endpoint response.
+* Extracts the configured claim and normalizes it into a list of groups.
+* Uses those groups to enforce [group-based access control](#control-access-with-groups).
+* Skips any request to your **Info API URL** for group data.
+
+Configure these fields under **Token claims**:
+
+* **Source**: The token to read groups from. Choose `id_token` (the default) or `access_token`. If you use `id_token`, include `openid` in your OAuth **Scopes**.
+* **Groups claim**: The claim to read groups from. You can use a top-level claim name, a namespaced URI claim, or a dotted path into nested claims. For example:
+  * `groups` for a top-level array claim.
+  * `https://your-domain.example.com/groups` for an Auth0 namespaced claim.
+  * `realm_access.roles` for a Keycloak realm role claim.
+
+Mintlify accepts the claim value as either a JSON array of strings or a single string.
+
+<Warning>
+  Group derivation from token claims is fail-closed. If the configured token is missing from the token response (for example, requesting `id_token` without the `openid` scope), Mintlify blocks the sign-in instead of logging the user in with no groups.
+</Warning>
+
+#### Token claims example
+
+For a provider that returns an `access_token` containing a `groups` claim:
+
+```json
+{
+  "source": "access_token",
+  "groupsClaim": "groups"
+}
+```
+
+For a Keycloak provider that returns roles in a nested claim:
+
+```json
+{
+  "source": "id_token",
+  "groupsClaim": "realm_access.roles"
+}
+```
+
 ### OAuth 2.0 example
 
 You host your documentation at `docs.foo.com` and you have an existing OAuth server at `auth.foo.com` that supports the Authorization Code Flow.

es/deploy/authentication-setup.mdx

@@ -107,7 +107,7 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
     ### Requisitos previos de OAuth 2.0
 
     * Un servidor OAuth u OIDC que admita el flujo de código de autorización (Authorization Code Flow).
-    * Capacidad para crear un endpoint de API accesible mediante tokens de acceso OAuth (opcional, para habilitar el control de acceso basado en grupos).
+    * Para el control de acceso basado en grupos, un servidor OAuth u OIDC que devuelva los grupos en el `id_token` o el `access_token`, o la capacidad para crear un endpoint de API accesible mediante tokens de acceso OAuth.
 
     ### Configuración de OAuth 2.0
 
@@ -125,7 +125,8 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
         * **Scopes** (opcional): Permisos que se van a solicitar. Copia la cadena de scope **completa** (por ejemplo, para un scope como `provider.users.docs`, copia el `provider.users.docs` completo). Usa varios scopes si necesitas diferentes niveles de acceso.
         * **Additional authorization parameters** (opcional): Parámetros de consulta adicionales que se agregarán a la solicitud de autorización inicial.
         * **Token URL**: Tu endpoint de intercambio de tokens de OAuth.
-        * **Info API URL** (opcional): Endpoint en tu servidor al que Mintlify llama para obtener información del usuario. Obligatorio para el control de acceso basado en grupos. Si se omite, el flujo de OAuth solo verifica la identidad.
+        * **Token claims** (opcional): Deriva los grupos de usuario directamente del JWT que devuelve tu endpoint de tokens, en lugar de alojar un endpoint independiente de información de usuario. Consulta [Derivar grupos a partir de claims del token](#derive-groups-from-token-claims).
+        * **Info API URL** (opcional): Endpoint en tu servidor al que Mintlify llama para obtener la información del usuario. Usa esta opción para el control de acceso basado en grupos si tu proveedor no devuelve los grupos en el `id_token` o el `access_token`. Si se omiten tanto **Token claims** como **Info API URL**, el flujo de OAuth solo verifica la identidad.
         * **Logout URL** (opcional): La URL de cierre de sesión nativa de tu proveedor de OAuth. Cuando los usuarios cierran sesión, Mintlify valida la redirección de cierre de sesión frente a esta URL configurada por motivos de seguridad. La redirección solo se completa si coincide exactamente con el `logoutUrl` configurado. Si no configuras una Logout URL, los usuarios se redirigen a `/login`. Mintlify redirige a los usuarios con una solicitud `GET` y no agrega parámetros de consulta, por lo que debes incluir cualquier parámetro (por ejemplo, `returnTo`) directamente en la URL.
         * **Redirect URL** (opcional): La URL a la que se redirigirá a los usuarios después de la autenticación.
 
@@ -152,6 +153,51 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
       </Step>
     </Steps>
 
+    ### Derivar grupos a partir de claims del token
+
+    Si tu proveedor de OAuth u OIDC ya devuelve la pertenencia a grupos en el `id_token` o el `access_token`, puedes evitar alojar un endpoint de información de usuario y dejar que Mintlify lea los grupos directamente del token que devuelve tu endpoint de tokens.
+
+    Cuando configuras **Token claims**, Mintlify:
+
+    * Decodifica el token configurado a partir de la respuesta del endpoint de tokens.
+    * Extrae el claim configurado y lo normaliza en una lista de grupos.
+    * Usa esos grupos para aplicar el [control de acceso basado en grupos](#control-access-with-groups).
+    * Omite cualquier solicitud a tu **Info API URL** para obtener datos de grupos.
+
+    Configura estos campos en **Token claims**:
+
+    * **Source**: El token del que se leerán los grupos. Elige `id_token` (el valor predeterminado) o `access_token`. Si usas `id_token`, incluye `openid` en los **Scopes** de OAuth.
+    * **Groups claim**: El claim del que se leerán los grupos. Puedes usar el nombre de un claim de nivel superior, un claim con URI con espacio de nombres o una ruta con puntos hacia claims anidados. Por ejemplo:
+      * `groups` para un claim de arreglo de nivel superior.
+      * `https://your-domain.example.com/groups` para un claim con espacio de nombres de Auth0.
+      * `realm_access.roles` para un claim de rol de realm de Keycloak.
+
+    Mintlify acepta el valor del claim como un arreglo JSON de cadenas o como una única cadena.
+
+    <Warning>
+      La derivación de grupos a partir de claims del token es fail-closed. Si el token configurado no está presente en la respuesta del token (por ejemplo, si se solicita `id_token` sin el scope `openid`), Mintlify bloquea el inicio de sesión en lugar de iniciar sesión al usuario sin grupos.
+    </Warning>
+
+    #### Ejemplo de Token claims
+
+    Para un proveedor que devuelve un `access_token` que contiene un claim `groups`:
+
+    ```json
+    {
+      "source": "access_token",
+      "groupsClaim": "groups"
+    }
+    ```
+
+    Para un proveedor Keycloak que devuelve roles en un claim anidado:
+
+    ```json
+    {
+      "source": "id_token",
+      "groupsClaim": "realm_access.roles"
+    }
+    ```
+
     ### Ejemplo de OAuth 2.0
 
     Alojas tu documentación en `docs.foo.com` y tienes un servidor OAuth existente en `auth.foo.com` que admite el flujo de código de autorización (Authorization Code Flow).

fr/deploy/authentication-setup.mdx

@@ -107,7 +107,7 @@ Utilisez ce comparatif pour choisir la méthode adaptée à votre cas d'usage. C
     ### Prérequis OAuth 2.0
 
     * Un serveur OAuth ou OIDC qui prend en charge le flux Authorization Code (Authorization Code Flow).
-    * Capacité à créer un endpoint d'API accessible via des jetons d'accès OAuth (facultatif, pour activer le contrôle d'accès basé sur les groupes).
+    * Pour le contrôle d'accès basé sur les groupes, soit un serveur OAuth ou OIDC qui renvoie les groupes dans l'`id_token` ou l'`access_token`, soit la capacité à créer un endpoint d'API accessible via des jetons d'accès OAuth.
 
     ### Configuration OAuth 2.0
 
@@ -125,7 +125,8 @@ Utilisez ce comparatif pour choisir la méthode adaptée à votre cas d'usage. C
         * **Scopes** (facultatif) : Autorisations à demander. Copiez la chaîne de scope **entière** (par exemple, pour un scope comme `provider.users.docs`, copiez l’intégralité de `provider.users.docs`). Utilisez plusieurs scopes si vous avez besoin de niveaux d’accès différents.
         * **Additional authorization parameters** (facultatif) : Paramètres de requête supplémentaires à ajouter à la requête d’autorisation initiale.
         * **Token URL** : Votre endpoint d’échange de jeton OAuth.
-        * **Info API URL** (facultatif) : Endpoint sur votre serveur que Mintlify appelle pour récupérer les informations utilisateur. Requis pour le contrôle d’accès basé sur les groupes. S’il est omis, le flux OAuth vérifie uniquement l’identité.
+        * **Token claims** (facultatif) : Dérivez les groupes d’utilisateurs directement depuis le JWT renvoyé par votre endpoint de jeton, au lieu d’héberger un endpoint d’informations utilisateur distinct. Voir [Dériver les groupes à partir des revendications du jeton](#derive-groups-from-token-claims).
+        * **Info API URL** (facultatif) : Endpoint sur votre serveur que Mintlify appelle pour récupérer les informations utilisateur. Utilisez ce champ pour le contrôle d’accès basé sur les groupes si votre fournisseur ne renvoie pas les groupes dans l’`id_token` ou l’`access_token`. Si **Token claims** et **Info API URL** sont tous deux omis, le flux OAuth vérifie uniquement l’identité.
         * **Logout URL** (facultatif) : L’URL de déconnexion native de votre fournisseur OAuth. Lorsque les utilisateurs se déconnectent, Mintlify valide la redirection de déconnexion par rapport à l’URL configurée, pour des raisons de sécurité. La redirection ne réussit que si elle correspond exactement à la valeur de `logoutUrl` configurée. Si vous ne configurez pas d’URL de déconnexion, les utilisateurs sont redirigés vers `/login`. Mintlify redirige les utilisateurs avec une requête `GET` et n’ajoute aucun paramètre de requête. Incluez donc directement tous les paramètres (par exemple, `returnTo`) dans l’URL.
         * **Redirect URL** (facultatif) : L’URL vers laquelle rediriger les utilisateurs après l’authentification.
 
@@ -152,6 +153,51 @@ Utilisez ce comparatif pour choisir la méthode adaptée à votre cas d'usage. C
       </Step>
     </Steps>
 
+    ### Dériver les groupes à partir des revendications du jeton
+
+    Si votre fournisseur OAuth ou OIDC renvoie déjà l’appartenance aux groupes dans l’`id_token` ou l’`access_token`, vous pouvez éviter d’héberger un endpoint d’informations utilisateur et laisser Mintlify lire les groupes directement depuis le jeton renvoyé par votre endpoint de jeton.
+
+    Lorsque vous configurez **Token claims**, Mintlify :
+
+    * Décode le jeton configuré à partir de la réponse de l’endpoint de jeton.
+    * Extrait la revendication configurée et la normalise en une liste de groupes.
+    * Utilise ces groupes pour appliquer le [contrôle d’accès basé sur les groupes](#control-access-with-groups).
+    * Ignore toute requête vers votre **Info API URL** pour les données de groupes.
+
+    Configurez ces champs sous **Token claims** :
+
+    * **Source** : Le jeton dans lequel lire les groupes. Choisissez `id_token` (valeur par défaut) ou `access_token`. Si vous utilisez `id_token`, incluez `openid` dans vos **Scopes** OAuth.
+    * **Groups claim** : La revendication depuis laquelle lire les groupes. Vous pouvez utiliser un nom de revendication de premier niveau, une revendication d’URI avec espace de noms, ou un chemin en notation pointée vers des revendications imbriquées. Par exemple :
+      * `groups` pour une revendication de tableau de premier niveau.
+      * `https://your-domain.example.com/groups` pour une revendication Auth0 avec espace de noms.
+      * `realm_access.roles` pour une revendication de rôle de realm Keycloak.
+
+    Mintlify accepte la valeur de la revendication sous la forme d’un tableau JSON de chaînes ou d’une chaîne unique.
+
+    <Warning>
+      La dérivation des groupes à partir des revendications du jeton fonctionne en mode « fail-closed ». Si le jeton configuré est absent de la réponse de jeton (par exemple, en demandant `id_token` sans le scope `openid`), Mintlify bloque la connexion au lieu de connecter l’utilisateur sans aucun groupe.
+    </Warning>
+
+    #### Exemple de Token claims
+
+    Pour un fournisseur qui renvoie un `access_token` contenant une revendication `groups` :
+
+    ```json
+    {
+      "source": "access_token",
+      "groupsClaim": "groups"
+    }
+    ```
+
+    Pour un fournisseur Keycloak qui renvoie les rôles dans une revendication imbriquée :
+
+    ```json
+    {
+      "source": "id_token",
+      "groupsClaim": "realm_access.roles"
+    }
+    ```
+
     ### Exemple OAuth 2.0
 
     Vous hébergez votre documentation sur `docs.foo.com` et vous disposez d’un serveur OAuth existant sur `auth.foo.com` qui prend en charge le flux « Authorization Code ».