> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.another-horizon.eu/llms.txt
> Use this file to discover all available pages before exploring further.
# Configuración de autenticación
> Controla el acceso a tu documentación mediante la autenticación de usuarios.
[Los planes Pro](https://mintlify.com/pricing?ref=authentication) incluyen autenticación por contraseña.
[Los planes personalizados](https://mintlify.com/pricing?ref=authentication) incluyen todos los métodos de autenticación.
La autenticación exige que los usuarios inicien sesión antes de acceder a tu documentación.
## Modos de Autenticación
Elige entre los modos de autenticación completa o parcial según tus necesidades de control de acceso.
**Autenticación completa**: Todas las páginas están protegidas. Los usuarios deben iniciar sesión antes de acceder a cualquier contenido.
**Autenticación parcial**: Algunas páginas son públicas, mientras que otras requieren autenticación. Los usuarios pueden navegar el contenido público libremente y autenticarse solo al acceder a páginas protegidas.
Al configurar cualquiera de los métodos de handshake a continuación, seleccionarás **Autenticación completa** o **Autenticación parcial** en la configuración de tu dashboard.
## Configurar la autenticación
Selecciona el método de handshake que quieres configurar.
La Autenticación con contraseña solo proporciona control de acceso y **no** admite la personalización de contenido.
### Requisitos previos
* Tus políticas de seguridad permiten compartir contraseñas entre usuarios.
### Implementación
1. En tu dashboard, ve a [Autenticación](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Selecciona **Autenticación completa** o **Autenticación parcial**.
3. Selecciona **Contraseña**.
4. Ingresa una contraseña segura.
5. Selecciona **Guardar cambios**.
Comparte de forma segura la contraseña y la URL de la documentación con los usuarios autorizados.
### Ejemplo
Tu documentación está alojada en `docs.foo.com` y necesitas control de acceso básico sin rastrear a usuarios individuales. Quieres impedir el acceso público manteniendo una configuración sencilla.
**Crea una contraseña segura** en tu dashboard. **Comparte las credenciales** con los usuarios autorizados. ¡Listo!
### Requisitos previos
* Toda persona que necesite acceder a tu documentación debe ser miembro de tu organización de Mintlify.
### Implementación
1. En tu dashboard, ve a [Authentication](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Selecciona **Full Authentication** o **Partial Authentication**.
3. Selecciona **Mintlify Auth**.
4. Selecciona **Enable Mintlify Auth**.
1. En tu dashboard, ve a [Members](https://dashboard.mintlify.com/settings/organization/members).
2. Agrega a cada persona que deba tener acceso a tu documentación.
3. Asigna los roles correspondientes según sus permisos de edición.
### Ejemplo
Tu documentación está alojada en `docs.foo.com` y todo tu equipo tiene acceso a tu dashboard. Quieres restringir el acceso solo a los miembros del equipo.
**Habilita la autenticación de Mintlify** en la configuración de tu dashboard.
**Verifica el acceso del equipo** comprobando que todos los miembros del equipo estén agregados a tu organización.
### Requisitos previos
* Un servidor OAuth u OIDC que admita el flujo Authorization Code.
* Posibilidad de crear un endpoint de API accesible mediante tokens de acceso de OAuth (opcional, para habilitar funciones de personalización).
### Implementación
1. En tu dashboard, ve a [Autenticación](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Selecciona **Autenticación completa** o **Autenticación parcial**.
3. Selecciona **OAuth** y configura estos campos:
* **Authorization URL**: Tu endpoint de OAuth.
* **Client ID**: Tu identificador de cliente de OAuth 2.0.
* **Client Secret**: Tu secreto de cliente de OAuth 2.0.
* **Scopes**: Permisos a solicitar. Copia la cadena de ámbitos **completa** (por ejemplo, para un ámbito como `provider.users.docs`, copia el `provider.users.docs` completo). Usa múltiples ámbitos si necesitas diferentes niveles de acceso.
* **Token URL**: Tu endpoint de intercambio de tokens de OAuth.
* **Info API URL** (opcional): Endpoint en tu servidor que Mintlify llama para obtener información del usuario para la personalización. Si se omite, el flujo de OAuth solo se usará para verificar la identidad y la información del usuario estará vacía.
* **Logout URL**: La URL de cierre de sesión nativa de tu proveedor de OAuth. Si tu proveedor tiene un parámetro `returnTo` o similar, redirígelo de vuelta a la URL de tu documentación.
4. Selecciona **Guardar cambios**.
1. Copia la **Redirect URL** desde tu [configuración de autenticación](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Agrega la Redirect URL como una URL de redirección autorizada en tu servidor OAuth.
Para habilitar funciones de personalización, crea un endpoint de API que:
* Acepte tokens de acceso de OAuth para la autenticación.
* Devuelva datos de usuario en el formato `User`. Consulta [Formato de datos de usuario](/es/deploy/personalization-setup#user-data-format) para más información.
Agrega la URL de este endpoint al campo **Info API URL** en tu [configuración de autenticación](https://dashboard.mintlify.com/settings/deployment/authentication).
### Ejemplo
Tu documentación está alojada en `foo.com/docs` y tienes un servidor OAuth existente en `auth.foo.com` que admite el flujo Authorization Code.
**Configura los detalles de tu servidor OAuth** en tu dashboard:
* **Authorization URL**: `https://auth.foo.com/authorization`
* **Client ID**: `ydybo4SD8PR73vzWWd6S0ObH`
* **Scopes**: `['provider.users.docs']`
* **Token URL**: `https://auth.foo.com/exchange`
* **Info API URL**: `https://api.foo.com/docs/user-info`
* **Logout URL**: `https://auth.foo.com/logout?returnTo=https%3A%2F%2Ffoo.com%2Fdocs`
**Crea un endpoint de información de usuario** en `api.foo.com/docs/user-info`, que requiere un token de acceso de OAuth con el ámbito `provider.users.docs` y devuelve:
```json theme={null}
{
"content": {
"firstName": "Jane",
"lastName": "Doe"
},
"groups": ["engineering", "admin"]
}
```
**Configura tu servidor OAuth para permitir redirecciones** a tu URL de devolución de llamada.
### Requisitos previos
* Un sistema de autenticación que pueda generar y firmar JWT.
* Un servicio de backend que pueda crear URL de redirección.
### Implementación
1. En tu dashboard, ve a [Autenticación](https://dashboard.mintlify.com/settings/deployment/authentication).
2. Selecciona **Autenticación completa** o **Autenticación parcial**.
3. Selecciona **JWT**.
4. Ingresa la URL de tu flujo de inicio de sesión existente y selecciona **Guardar cambios**.
5. Selecciona **Generate new key**.
6. Almacena tu clave de forma segura donde tu backend pueda acceder a ella.
Modifica tu flujo de inicio de sesión existente para incluir estos pasos después de la autenticación del usuario:
* Crea un JWT que contenga la información del usuario autenticado en el formato `User`. Consulta [Formato de datos de usuario](/es/deploy/personalization-setup#user-data-format) para más información.
* Firma el JWT con tu clave secreta, usando el algoritmo EdDSA.
* Crea una URL de redirección de vuelta a la ruta `/login/jwt-callback` de tu documentación, incluyendo el JWT como hash.
### Ejemplo
Tu documentación está alojada en `docs.foo.com` con un sistema de autenticación existente en `foo.com`. Quieres ampliar tu flujo de inicio de sesión para otorgar acceso a la documentación mientras mantienes tu documentación separada de tu dashboard (o no tienes un dashboard).
Crea un endpoint de inicio de sesión en `https://foo.com/docs-login` que extienda tu autenticación existente.
Después de verificar las credenciales del usuario:
* Genera un JWT con los datos del usuario en el formato de Mintlify.
* Firma el JWT y redirige a `https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}`.
```ts TypeScript theme={null}
import * as jose from 'jose';
import { Request, Response } from 'express';
const TWO_WEEKS_IN_MS = 1000 * 60 * 60 * 24 * 7 * 2;
const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA');
export async function handleRequest(req: Request, res: Response) {
const user = {
expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // Expiración de sesión de 2 semanas
groups: res.locals.user.groups,
content: {
firstName: res.locals.user.firstName,
lastName: res.locals.user.lastName,
},
};
const jwt = await new jose.SignJWT(user)
.setProtectedHeader({ alg: 'EdDSA' })
.setExpirationTime('10 s') // Expiración del JWT de 10 segundos
.sign(signingKey);
return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
}
```
```python Python theme={null}
import jwt # pyjwt
import os
from datetime import datetime, timedelta
from fastapi.responses import RedirectResponse
private_key = os.getenv(MINTLIFY_JWT_PEM_SECRET_NAME, '')
@router.get('/auth')
async def return_mintlify_auth_status(current_user):
jwt_token = jwt.encode(
payload={
'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # Expiración del JWT de 10 segundos
'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # Expiración de sesión de 1 semana
'groups': ['admin'] if current_user.is_admin else [],
'content': {
'firstName': current_user.first_name,
'lastName': current_user.last_name,
},
},
key=private_key,
algorithm='EdDSA'
)
return RedirectResponse(url=f'https://docs.foo.com/login/jwt-callback#{jwt_token}', status_code=302)
```
### Redirigir a usuarios no autenticados
Cuando un usuario no autenticado intenta acceder a una página protegida, su destino previsto se conserva en la redirección a tu URL de inicio de sesión:
1. El usuario intenta visitar una página protegida: `https://docs.foo.com/quickstart`.
2. Redirige a tu URL de inicio de sesión con un parámetro query de redirección: `https://foo.com/docs-login?redirect=%2Fquickstart`.
3. Después de la autenticación, redirige a `https://docs.foo.com/login/jwt-callback?redirect=%2Fquickstart#{SIGNED_JWT}`.
4. El usuario llega a su destino original.
## Hacer públicas las páginas
Cuando uses autenticación parcial, todas las páginas están protegidas de forma predeterminada. Puedes hacer que páginas específicas sean visibles sin autenticación a nivel de página o de grupo con la propiedad `public`.
### Páginas individuales
Para hacer pública una página, agrega `public: true` al frontmatter de la página.
```mdx Public page example theme={null}
---
title: "Página pública"
public: true
---
```
### Grupos de páginas
Para hacer públicas todas las páginas de un grupo, añade `"public": true` debajo del nombre del grupo en el objeto `navigation` de tu `docs.json`.
```json Public group example theme={null}
{
"navigation": {
"groups": [
{
"group": "Grupo público",
"public": true,
"icon": "play",
"pages": [
"quickstart",
"installation",
"settings"
]
},
{
"group": "Grupo privado",
"icon": "pause",
"pages": [
"private-information",
"secret-settings"
]
}
]
}
}
```
## Controla el acceso con groups
Cuando usas OAuth o autenticación con JWT (JSON Web Token), puedes restringir páginas específicas a ciertos grupos de usuarios. Esto es útil cuando quieres que distintos usuarios vean contenido diferente según su rol o atributos.
Los grupos se gestionan mediante los datos del usuario enviados durante la autenticación.
```json Example user info highlight={2} theme={null}
{
"groups": ["admin", "beta-users"],
"content": {
"firstName": "Jane",
"lastName": "Doe"
}
}
```
Especifica qué groups pueden acceder a páginas determinadas usando la propiedad `groups` en el frontmatter.
```mdx Example page restricted to the admin group highlight={3} theme={null}
---
title: "Panel de administración"
groups: ["admin"]
---
```
Los usuarios deben pertenecer al menos a uno de los groups enumerados para acceder a la página. Si un usuario intenta acceder a una página sin el group requerido, recibirá un error 404.
### Interacción con los modos de autenticación
groups funcionan de manera diferente según tu modo de Autenticación.
**Autenticación completa con groups:**
* Todas las páginas requieren Autenticación.
* Las páginas sin la propiedad `groups` son accesibles para todos los usuarios autenticados.
* Las páginas con la propiedad `groups` solo son accesibles para usuarios autenticados que pertenezcan a esos groups.
**Autenticación parcial con groups:**
* Las páginas requieren Autenticación a menos que las hagas públicas.
* Las páginas con `public: true` y sin `groups` son accesibles para todos.
* Las páginas con `groups` (con o sin `public: true`) solo son accesibles para usuarios autenticados que pertenezcan a esos groups.
```mdx Anyone can view this page theme={null}
---
title: "Guía pública"
public: true
---
```
````mdx Only authenticated users can view this page theme={null}
---
title: "Referencia de API"
---
```mdx Solo los usuarios autenticados en los grupos pro o enterprise pueden ver esta página
---
title: "Configuraciones avanzadas"
groups: ["pro", "enterprise"]
---
````