Skip to content

Update from code changes: document OAuth group claims #6887

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ethanpalm merged 3 commits into from
Aug 6, 2026
Merged

Update from code changes: document OAuth group claims #6887

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c6f9716
docs: document OAuth group claim delimiters
mintlify[bot] Aug 5, 2026
d56a399
docs: refine localized authentication pages
mintlify[bot] Aug 5, 2026
791305c
Apply suggestions from code review
ethanpalm Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 25 additions & 2 deletions deploy/authentication-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ You host your documentation at `docs.foo.com` and your entire team has access to
* **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.
* **Info API URL** (optional): Endpoint on your server that Mintlify calls to retrieve user info. Use this field for group-based access control. If omitted, 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**.
Expand All @@ -127,7 +127,7 @@ You host your documentation at `docs.foo.com` and your entire team has access to
1. Copy the **Redirect URL** from your [authentication settings](https://app.mintlify.com/products/authentication).
2. Add the redirect URL as an authorized redirect URL for your OAuth server.
</Step>
<Step title="Create your user info endpoint (optional).">
<Step title="Create your user info endpoint for group access (optional).">
To enable group-based access control, create an API endpoint that:
* Responds to `GET` requests.
* Accepts an `Authorization: Bearer <access_token>` header for authentication.
Expand All @@ -139,6 +139,29 @@ You host your documentation at `docs.foo.com` and your entire team has access to
</Step>
</Steps>

### Use groups from OAuth token claims

If your identity provider includes group membership in the ID token or access token, you can use those claims instead of an Info API URL. This option is available for OAuth configurations that use a client secret.

When configuring OAuth token claims for your deployment, use values such as:

```json
{
"source": "id_token",
"groupsClaim": "groups",
"groupsDelimiter": ","
}
```

* `source`: Selects `id_token` or `access_token`. If you select `id_token`, include the `openid` scope in your OAuth scopes.
* `groupsClaim`: Identifies the token claim that contains groups. Defaults to `groups`.
* `groupsDelimiter`: An optional delimiter from 1 to 4 characters. Mintlify uses it only to split string claim values. If the delimiter can be part of a group name, omit `groupsDelimiter`.

For example, with `"groups": "general,client"` and `groupsDelimiter` set to `","`, Mintlify uses `general` and `client` as separate groups.

Mintlify trims whitespace around each group and ignores empty segments. Without `groupsDelimiter`, the complete string is a single group. Array claims are always one group per string item and are not split.


### 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.
Expand Down
84 changes: 68 additions & 16 deletions es/deploy/authentication-setup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,15 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
La autenticación mediante contraseña proporciona únicamente control de acceso y **no** admite funciones específicas por usuario, como el control de acceso basado en grupos o el autocompletado previo del área de pruebas de la API.
</Info>

### Requisitos previos de la contraseña
<div id="password-prerequisites">
### Requisitos previos de la contraseña
</div>

* Tus requisitos de seguridad permiten compartir contraseñas entre usuarios.

### Configuración de la contraseña
<div id="password-setup">
### Configuración de la contraseña
</div>

<Steps>
<Step title="Crea una contraseña.">
Expand All @@ -63,19 +67,25 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
</Step>
</Steps>

### Ejemplo de contraseña
<div id="password-example">
### Ejemplo de contraseña
</div>

Alojas tu documentación en `docs.foo.com` y necesitas un control de acceso básico sin hacer seguimiento de usuarios individuales. Quieres evitar el acceso público sin complicar la configuración.

**Crea una contraseña segura** en tu dashboard. **Comparte las credenciales** con los usuarios autorizados.
</Tab>

<Tab title="Autenticación privada">
### Requisitos previos de la autenticación privada
<div id="private-authentication-prerequisites">
### Requisitos previos de la autenticación privada
</div>

* Todas las personas que necesiten acceder a tu sitio deben ser miembros de tu organización de Mintlify.

### Configuración de la autenticación privada
<div id="private-authentication-setup">
### Configuración de la autenticación privada
</div>

<Steps>
<Step title="Habilita la autenticación privada.">
Expand All @@ -94,7 +104,9 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
</Step>
</Steps>

### Ejemplo de autenticación privada
<div id="private-example">
### Ejemplo de autenticación privada
</div>

Alojas tu documentación en `docs.foo.com` y todo tu equipo tiene acceso a tu dashboard. Quieres restringir el acceso solo a los miembros del equipo.

Expand All @@ -104,12 +116,16 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
</Tab>

<Tab title="OAuth 2.0">
### Requisitos previos de OAuth 2.0
<div id="oauth-20-prerequisites">
### Requisitos previos de OAuth 2.0
</div>

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

### Configuración de OAuth 2.0
<div id="oauth-20-setup">
### Configuración de OAuth 2.0
</div>

<Steps>
<Step title="Configura tus ajustes de OAuth.">
Expand All @@ -125,7 +141,7 @@ 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.
* **Info API URL** (opcional): Endpoint en tu servidor al que Mintlify llama para obtener información del usuario. Usa este campo para el enfoque de Info API para el control de acceso basado en grupos. También puedes usar los claims de OAuth. Si no configuras ninguno de los dos, 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.

Expand All @@ -139,8 +155,8 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
2. Agrega la Redirect URL como una URL de redirección autorizada en tu servidor OAuth.
</Step>

<Step title="Crea tu endpoint de información de usuario (opcional).">
Para habilitar el control de acceso basado en grupos, crea un endpoint de API que:
<Step title="Crea tu endpoint de información de usuario para el acceso por grupos (opcional).">
Para usar el enfoque de Info API para el control de acceso basado en grupos, crea un endpoint de API que:

* Responda a solicitudes `GET`.
* Acepte un encabezado `Authorization: Bearer <access_token>` para la autenticación.
Expand All @@ -152,7 +168,35 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
</Step>
</Steps>

### Ejemplo de OAuth 2.0
<div id="use-groups-from-oauth-token-claims">
### Usa los grupos incluidos en los claims del token de OAuth
</div>

Si tu proveedor de identidad incluye la pertenencia a grupos en el token de ID o en el token de acceso, puedes usar esos claims en lugar de una URL de Info API. Esta opción está disponible para configuraciones de OAuth que usan un secreto de cliente.

Al configurar los claims del token de OAuth para tu implementación, usa valores como estos:

```json
{
"source": "id_token",
"groupsClaim": "groups",
"groupsDelimiter": ","
}
```

* `source`: Selecciona `id_token` o `access_token`. Si seleccionas `id_token`, incluye el scope `openid` en tus scopes de OAuth.
* `groupsClaim`: Identifica el claim del token que contiene los grupos. El valor predeterminado de `groupsClaim` es `groups`.
* `groupsDelimiter`: Delimitador opcional de 1 a 4 caracteres. Mintlify solo lo usa para dividir los valores de los claims que sean cadenas.

Por ejemplo, con `"groups": "general,clienta_eur"` y `groupsDelimiter` establecido en `","`, Mintlify usa `general` y `clienta_eur` como grupos separados.

Mintlify elimina los espacios en blanco alrededor de cada grupo e ignora los segmentos vacíos. Sin `groupsDelimiter`, la cadena completa se trata como un solo grupo. Los claims que son arrays siempre se tratan como un grupo por cada elemento de cadena y no se dividen.

Omite `groupsDelimiter` cuando el delimitador pueda formar parte del nombre de un grupo.

<div id="oauth-20-example">
### Ejemplo de OAuth 2.0
</div>

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

Expand Down Expand Up @@ -187,12 +231,16 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
</Tab>

<Tab title="JWT">
### Requisitos previos de JWT
<div id="jwt-prerequisites">
### Requisitos previos de JWT
</div>

* Un sistema de autenticación que pueda generar y firmar JWT.
* Un servicio de backend que pueda crear URL de redirección.

### Configuración de JWT
<div id="jwt-setup">
### Configuración de JWT
</div>

<Steps>
<Step title="Genera una clave privada.">
Expand All @@ -217,7 +265,9 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
</Step>
</Steps>

### Ejemplo de JWT
<div id="jwt-example">
### Ejemplo de JWT
</div>

Alojas tu documentación en `docs.foo.com` con un sistema de autenticación existente en `foo.com`. Quieres ampliar tu flujo de inicio de sesión para conceder acceso a la documentación manteniéndola separada de tu dashboard (o no tienes un dashboard).

Expand Down Expand Up @@ -291,7 +341,9 @@ Usa esta comparación para elegir el método que se adapte a tu caso de uso. Con
```
</CodeGroup>

### Redirigir a usuarios no autenticados
<div id="redirect-unauthenticated-users">
### Redirigir a usuarios no autenticados
</div>

Cuando un usuario no autenticado intenta acceder a una página protegida, la redirección a tu URL de inicio de sesión conserva el destino previsto del usuario.

Expand Down
Loading
Loading