Configuración de autenticación

Controla la privacidad de tu documentación mediante la autenticación de usuarios

Los planes Pro incluyen autenticación con contraseña.

Los planes Enterprise incluyen todos los métodos de autenticación.

La autenticación requiere que los usuarios inicien sesión antes de acceder a tu documentación.

​

Modos de Autenticación

Elige entre 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, selecciona Autenticación completa o Autenticación parcial en la configuración de tu dashboard.

​

Configuración de la autenticación

Selecciona el método de enlace (handshake) que deseas configurar.

Contraseña

La autenticación con contraseña solo proporciona control de acceso y no admite la personalización de contenido.

​

Requisitos previos

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

​

Implementación

1. Crea una contraseña.

   1. En tu dashboard, ve a Autenticación.
   2. Selecciona Autenticación completa o Autenticación parcial.
   3. Selecciona Contraseña.
   4. Ingresa una contraseña segura.
   5. Selecciona Guardar cambios.
2. Distribuye el acceso.

   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 un 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!

Dashboard de Mintlify

​

Requisitos previos

• Tus usuarios de la documentación también son tus editores.

​

Implementación

1. Enable Mintlify dashboard authentication.

   1. En tu dashboard, ve a Authentication.
   2. Selecciona Full Authentication o Partial Authentication.
   3. Selecciona Mintlify Auth.
   4. Selecciona Enable Mintlify Auth.
2. Add authorized users.

   1. En tu dashboard, ve a Members.
   2. Agrega a cada persona que deba tener acceso a tu documentación.
   3. Asigna los roles adecuados según sus permisos de edición.

​

Ejemplo

Tu documentación está alojada en docs.foo.com y tu equipo usa el dashboard para editarla. 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 estén agregados a tu organización.

OAuth 2.0

​

Requisitos previos

• Un servidor OAuth u OIDC que admita el Authorization Code Flow.
• Capacidad para crear un endpoint de API accesible mediante tokens de acceso de OAuth (opcional, para habilitar funciones de personalización).

​

Implementación

1. Configure your OAuth settings.

   1. En tu dashboard, ve a Autenticación.
   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 scope completa (por ejemplo, para un scope como provider.users.docs, copia el provider.users.docs completo). Usa varios scopes si necesitas distintos niveles de acceso.
   • Token URL: Tu endpoint de intercambio de tokens de OAuth.
   • Info API URL (opcional): Endpoint para obtener información del usuario para 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, haz que apunte de vuelta a la URL de tu documentación.

   4. Selecciona Guardar cambios.
2. Configure your OAuth server.

   1. Copia la Redirect URL desde tu configuración de autenticación.
   2. Agrega la redirect URL como una URL de redirección autorizada en tu servidor OAuth.
3. Create your user info endpoint (optional).

   Para habilitar funciones de personalización, crea un endpoint de API que:

   • Acepte tokens de acceso de OAuth para autenticación.
   • Devuelva datos de usuario en el formato User. Consulta 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.

​

Ejemplo

Tu documentación está alojada en foo.com/docs y tienes un servidor OAuth existente en auth.foo.com que admite el 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%2Ffoo.com%2Fdocs

Crea un endpoint de información de usuario en api.foo.com/docs/user-info, que requiera un token de acceso de OAuth con el scope provider.users.docs y que devuelva:

{
  "content": {
    "firstName": "Jane",
    "lastName": "Doe"
  },
  "groups": ["engineering", "admin"]
}

Configura tu servidor de OAuth para permitir redirecciones a tu URL de callback.

JWT (JSON Web Token)

​

Requisitos previos

• Un sistema de autenticación que pueda generar y firmar JWT (JSON Web Token).
• Un servicio de backend que pueda crear URL de redirección.

​

Implementación

1. Genera una clave privada.

   1. En tu dashboard, ve a Autenticación.
   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 Generar nueva clave.
   6. Almacena tu clave de forma segura donde tu backend pueda acceder a ella.
2. Integra la autenticación de Mintlify en tu flujo de inicio de sesión.

   Modifica tu flujo de inicio de sesión existente para incluir estos pasos después de autenticar al usuario:

   • Crea un JWT que contenga la información del usuario autenticado en el formato User. Consulta Formato de datos de usuario 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 extender tu flujo de inicio de sesión para conceder 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 datos del usuario en el formato de Mintlify.
• Firma el JWT y redirige a https://docs.foo.com/login/jwt-callback#{SIGNED_JWT}.

TypeScript

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), // 2 week session expiration
    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') // 10 second JWT expiration
    .sign(signingKey);

  return res.redirect(`https://docs.foo.com/login/jwt-callback#${jwt}`);
}

​

Redirección de 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 de 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 se utiliza la 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, ya sea a nivel de página o de grupo, con la propiedad public.

​

A nivel de página

Para hacer que una página sea pública, agrega public: true al frontmatter de la página.

Public page example

---
title: "Página pública"
public: true
---

​

Nivel de grupo

Para hacer públicas todas las páginas de un grupo, agrega "public": true debajo del nombre del grupo en el objeto navigation de tu docs.json.

Public group example

{
  "navigation": {
    "groups": [
      {
        "group": "Grupo público",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "Grupo privado",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}