> ## Documentation Index > Fetch the complete documentation index at: https://adminroletesting-justin-client-exports.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Configuración de autenticación > Configura la autenticación de usuarios con OAuth, JWT, contraseña o Mintlify Auth para controlar el acceso a páginas y referencias de API. La autenticación con Mintlify Auth está disponible en todos los planes. La autenticación por contraseña, OAuth y JWT requiere un [plan Enterprise](https://mintlify.com/pricing?ref=authentication). La autenticación exige que los usuarios inicien sesión antes de acceder a tu contenido. Puedes configurar autenticación completa para todas las páginas o autenticación parcial en la que algunas páginas son públicas y otras están protegidas. La autenticación solo está disponible para sitios alojados en un dominio personalizado o subdominio de Mintlify. Por ejemplo, `docs.ejemplo.com` o `ejemplo.mintlify.site`. La autenticación **no es compatible** para sitios con una [subruta personalizada](/es/deploy/docs-subpath). Por ejemplo, `ejemplo.com/docs`.
## Configurar la autenticación
Selecciona el método de handshake que quieres configurar. 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. ### Requisitos previos de la contraseña * Tus requisitos de seguridad permiten compartir contraseñas entre usuarios. ### Configuración de la contraseña 1. En tu dashboard, ve a [Authentication](https://dashboard.mintlify.com/products/authentication). 2. En la sección **Authentication method**, establece la visibilidad del sitio en **Private**. 3. Haz clic en **Password**. 4. Introduce una contraseña segura. 5. Haz clic en **Save changes**. Después de guardar, tu sitio se vuelve a implementar automáticamente. Cuando la implementación haya finalizado, cualquiera que visite tu sitio deberá introducir la contraseña para acceder a tu contenido. Comparte de forma segura la contraseña y la URL de la documentación con los usuarios autorizados. ### Ejemplo de contraseña 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. ### Requisitos previos de Mintlify Auth * Todas las personas que necesiten acceder a tu documentación deben ser miembros de tu organización de Mintlify. ### Configuración de Mintlify Auth 1. En tu dashboard, ve a [Authentication](https://dashboard.mintlify.com/products/authentication). 2. En la sección **Authentication method**, establece la visibilidad del sitio en **Private**. 3. Haz clic en **Authenticated**. 4. Haz clic en **Save changes**. Después de guardar, tu sitio se vuelve a implementar automáticamente. Una vez que finalice la implementación, cualquier persona que visite tu sitio deberá iniciar sesión en tu organización de Mintlify para acceder a tu contenido. 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 apropiados según sus permisos de edición. ### Ejemplo de Mintlify Auth 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. **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 activos en tu organización. ### 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). ### Configuración de OAuth 2.0 1. En tu dashboard, ve a [Authentication](https://dashboard.mintlify.com/products/authentication). 2. En la sección **Authentication method**, establece la visibilidad del sitio en **Private**. 3. Haz clic en **Custom** 4. Haz clic en **OAuth**. 5. 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** (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. * **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. 5. Haz clic en **Guardar cambios**. Después de configurar tus ajustes de OAuth, tu sitio se vuelve a implementar. Cuando finalice la implementación, cualquier persona que visite tu sitio deberá iniciar sesión en tu proveedor de OAuth para acceder a tu contenido. 1. Copia la **Redirect URL** de tus [ajustes de autenticación](https://dashboard.mintlify.com/products/authentication). 2. Agrega la Redirect URL como una URL de redirección autorizada en tu servidor OAuth. Para habilitar el control de acceso basado en grupos, crea un endpoint de API que: * Responda a solicitudes `GET`. * Acepte un encabezado `Authorization: Bearer ` para la autenticación. * Devuelva los datos de usuario en el formato `User`. Consulta [Formato de datos de usuario](#user-data-format) para obtener más información. Mintlify llama a este endpoint con el token de acceso de OAuth para obtener la información del usuario. No se envían parámetros de consulta adicionales. Agrega la URL de este endpoint al campo **Info API URL** en tus [ajustes de autenticación](https://dashboard.mintlify.com/products/authentication). ### 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). **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%2Fdocs.foo.com` **Crea un endpoint de información de usuario** en `api.foo.com/docs/user-info`, que requiera un token de acceso OAuth con el scope `provider.users.docs`, y devuelva: ```json theme={null} { "groups": ["engineering", "admin"], "expiresAt": 1735689600, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer user_abc123" } } } ``` Controla la duración de la sesión con el campo `expiresAt` en la respuesta de información de usuario. Este es un timestamp Unix (segundos desde el inicio de la época Unix) que indica cuándo debe expirar la sesión. Consulta [Formato de datos de usuario](#user-data-format) para más detalles. **Configura tu servidor OAuth para permitir redirecciones** a tu URL de callback. ### Requisitos previos de JWT * 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 1. En tu dashboard, ve a [Authentication](https://dashboard.mintlify.com/products/authentication). 2. En la sección **Authentication method**, establece la visibilidad del sitio en **Private**. 3. Haz clic en **Custom** 4. Haz clic en **JWT**. 5. Introduce la URL de tu flujo de inicio de sesión existente. 6. Haz clic en **Save changes**. 7. Haz clic en **Generate new key**. 8. Almacena tu clave de forma segura donde tu backend pueda acceder a ella. Después de generar una clave privada, tu sitio se vuelve a implementar automáticamente. Cuando la implementación haya finalizado, cualquier persona que visite tu sitio debe iniciar sesión en tu sistema de autenticación JWT para acceder a tu contenido. 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](#user-data-format) para obtener 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 el hash. ### Ejemplo de JWT 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). Crea un endpoint de inicio de sesión en `https://foo.com/docs-login` que amplíe 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 DOCS_HOST = 'docs.example.com'; const signingKey = await jose.importPKCS8(process.env.MINTLIFY_PRIVATE_KEY, 'EdDSA'); export async function handleRequest(req: Request, res: Response) { const user = { host: DOCS_HOST, // Debe coincidir con la URL de tu documentación expiresAt: Math.floor((Date.now() + TWO_WEEKS_IN_MS) / 1000), // vencimiento de la sesión de 2 semanas groups: res.locals.user.groups, apiPlaygroundInputs: { header: { "Authorization": `Bearer ${res.locals.user.apiKey}`, }, }, }; const jwt = await new jose.SignJWT(user) .setProtectedHeader({ alg: 'EdDSA' }) .setExpirationTime('10 s') // vencimiento del JWT de 10 segundos .sign(signingKey); return res.redirect(`https://${DOCS_HOST}/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, '') DOCS_HOST = 'docs.example.com' @router.get('/auth') async def return_mintlify_auth_status(current_user): jwt_token = jwt.encode( payload={ 'host': DOCS_HOST, # Debe coincidir con la URL de tu documentación 'exp': int((datetime.now() + timedelta(seconds=10)).timestamp()), # vencimiento del JWT de 10 segundos 'expiresAt': int((datetime.now() + timedelta(weeks=2)).timestamp()), # vencimiento de la sesión de 2 semanas 'groups': ['admin'] if current_user.is_admin else [], 'apiPlaygroundInputs': { 'header': { 'Authorization': f'Bearer {current_user.api_key}', }, }, }, key=private_key, algorithm='EdDSA' ) return RedirectResponse(url=f'https://{DOCS_HOST}/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, la redirección a tu URL de inicio de sesión conserva el destino previsto del usuario. 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 de consulta llamado `redirect`: `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, 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. Administra los grupos mediante los datos del usuario enviados durante la autenticación. Consulta [Formato de datos de usuario](#user-data-format) para más detalles. ```json Example user info theme={null} { "groups": ["admin", "beta-users"], "expiresAt": 1735689600 } ``` 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.
### Cómo interactúan los groups con las páginas públicas
* Todas las páginas requieren Autenticación de forma predeterminada. * Las páginas con una propiedad `groups` solo son accesibles para usuarios autenticados dentro de esos groups. * Las páginas sin la propiedad `groups` son accesibles para todos los usuarios autenticados. * Las páginas con `public: true` y sin la propiedad `groups` son accesibles para cualquier persona. ```mdx Public page theme={null} --- title: "Guía pública" public: true --- ``` ```mdx Protected page theme={null} --- title: "Referencia de API" --- ``` ```mdx Protected page with groups theme={null} --- title: "Configuraciones avanzadas" groups: ["pro", "enterprise"] --- ```
## Formato de datos de usuario
Cuando utilices autenticación OAuth o JWT, tu sistema devolverá datos de usuario que controlan la duración de la sesión, la pertenencia a grupos y la [personalización de contenido](/es/create/personalization). ```tsx Format theme={null} type User = { host?: string; expiresAt?: number; groups?: string[]; content?: Record; apiPlaygroundInputs?: { server?: Record; header?: Record; query?: Record; cookie?: Record; path?: Record; }; }; ``` ```json Ejemplo theme={null} { "host": "docs.example.com", "expiresAt": 1735689600, "groups": ["admin", "beta-users"], "content": { "firstName": "Jane", "company": "Acme Corp" }, "apiPlaygroundInputs": { "header": { "Authorization": "Bearer user_abc123" }, "server": { "baseUrl": "https://api.foo.com" } } } ``` **Obligatorio para la autenticación JWT.** El nombre de host de tu sitio de documentación. La cadena debe coincidir exactamente con el dominio donde implementas tu documentación. Mintlify valida que el host del JWT coincida con el host de la solicitud para evitar la reutilización de tokens entre diferentes sitios. Momento de expiración de la sesión en segundos desde el epoch. Cuando la hora actual supera este valor, el usuario debe volver a autenticarse. **Para JWT:** Esto es diferente del claim `exp` del JWT, que determina cuándo un JWT se considera inválido. Configura el claim `exp` del JWT con una duración corta (10 segundos o menos) por seguridad. Usa `expiresAt` para la duración real de la sesión (de horas a semanas). Lista de los grupos a los que pertenece el usuario. Las páginas cuyo frontmatter tenga un `groups` coincidente son accesibles para este usuario. **Ejemplo**: Un usuario con `groups: ["admin", "engineering"]` puede acceder a páginas etiquetadas con los grupos `admin` o `engineering`. Datos personalizados accesibles en páginas MDX mediante la variable `user` para [contenido personalizado](/es/create/personalization#dynamic-mdx-content). Rellena previamente los campos del área de pruebas de la API con valores específicos del usuario. Cuando un usuario se autentica, estos valores rellenan los campos de entrada correspondientes en el área de pruebas de la API. Los usuarios pueden sobrescribir los valores rellenados previamente, y sus cambios persisten en el almacenamiento local. Solo se aplican los valores que coinciden con el esquema de seguridad del endpoint actual. Valores de encabezado que se van a rellenar previamente, indexados por nombre de encabezado. Valores de parámetros de búsqueda que se van a rellenar previamente, indexados por nombre de parámetro. Valores de cookies que se van a rellenar previamente, indexados por nombre de cookie. Valores de variables de servidor que se van a rellenar previamente, indexados por nombre de variable. Valores de parámetros de ruta que se van a rellenar previamente, indexados por nombre de parámetro.
## Disponibilidad de funciones
Algunas funciones se comportan de manera diferente o no están disponibles cuando habilitas la autenticación. Mintlify no admite el alojamiento público de archivos arbitrarios en un sitio autenticado. Todos los archivos alojados, incluidos `llms.txt`, `llms-full.txt` y `skill.md`, están sujetos a los mismos requisitos de autenticación que las páginas de tu documentación. | Función | Público | Totalmente autenticado (todas las páginas protegidas) | Parcialmente autenticado (algunas páginas públicas) | | :-------------------------------------------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | | [llms.txt and llms-full.txt](/es/ai/llmstxt) | Compatibilidad completa | Disponible tras autenticación, por lo que es posible que las herramientas de IA no puedan acceder a los archivos | Disponible tras autenticación, por lo que es posible que las herramientas de IA no puedan acceder a los archivos | | [Servidor MCP](/es/ai/model-context-protocol) | Compatibilidad completa | Requiere autenticación para conectarse | Disponible sin autenticación para páginas públicas y con autenticación para páginas protegidas | | [Exportación a Markdown](/es/ai/markdown-export) | Compatibilidad completa | Compatibilidad completa, respeta los grupos de usuarios | Compatibilidad completa, respeta los grupos de usuarios | | [Exportación a PDF](/es/optimize/pdf-exports) | Compatibilidad completa | Compatibilidad completa, respeta los grupos de usuarios. Las páginas autenticadas se exportan con imágenes y recursos incluidos. | Compatibilidad completa, respeta los grupos de usuarios. Las páginas autenticadas se exportan con imágenes y recursos incluidos. | | [Búsqueda](/es/assistant/index) | Compatibilidad completa | Compatibilidad completa, respeta los grupos de usuarios | Compatibilidad completa, respeta los grupos de usuarios | | [Assistant](/es/assistant/index) | Compatibilidad completa | Compatibilidad completa, respeta los grupos de usuarios | Compatibilidad completa, respeta los grupos de usuarios | | [skill.md](/es/ai/skillmd) | Compatibilidad completa | No compatible | No compatible | | [Mapa del sitio](/es/optimize/seo#sitemaps-and-robotstxt-files) | Compatibilidad completa | Disponible tras autenticación, pero excluye las páginas en groups | Disponible tras autenticación, pero excluye las páginas en groups | | [robots.txt](/es/optimize/seo#sitemaps-and-robotstxt-files) | Compatibilidad completa | Disponible tras autenticación | Disponible tras autenticación |