mintlify__docs/es/deploy/authentication-setup.mdx

---
title: "Configuración de autenticación"
description: "Controla el acceso a tu documentación mediante la autenticación de usuarios."
keywords: ['authentication', 'auth', 'OAuth', 'JWT', 'password']
---

<Info>
  [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.
</Info>

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

<div id="authentication-modes">
  ## Modos de Autenticación
</div>

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.

<div id="configure-authentication">
  ## Configurar la autenticación
</div>

Selecciona el método de handshake que quieres configurar.

<Tabs>
  <Tab title="Contraseña">
    <Info>
      La Autenticación con contraseña solo proporciona control de acceso y **no** admite la personalización de contenido.
    </Info>

    ### Requisitos previos

    * Tus políticas de seguridad permiten compartir contraseñas entre usuarios.

    ### Implementación

    <Steps>
      <Step title="Crea una contraseña.">
        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**.
      </Step>

      <Step title="Distribuye el acceso.">
        Comparte de forma segura la contraseña y la URL de la documentación con los usuarios autorizados.
      </Step>
    </Steps>

    ### 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!
  </Tab>

  <Tab title="Dashboard de Mintlify">
    ### Requisitos previos

    * Toda persona que necesite acceder a tu documentación debe ser miembro de tu organización de Mintlify.

    ### Implementación

    <Steps>
      <Step title="Habilita la autenticación del Dashboard de Mintlify.">
        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**.
      </Step>

      <Step title="Agrega usuarios autorizados.">
        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.
      </Step>
    </Steps>

    ### 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.
  </Tab>

  <Tab title="OAuth 2.0">
    ### 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

    <Steps>
      <Step title="Configura los ajustes de OAuth.">
        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**.
      </Step>

      <Step title="Configura tu servidor OAuth.">
        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.
      </Step>

      <Step title="Crea tu endpoint de información de usuario (opcional).">
        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).
      </Step>
    </Steps>

    ### 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
    {
      "content": {
        "firstName": "Jane",
        "lastName": "Doe"
      },
      "groups": ["engineering", "admin"]
    }
    ```

    **Configura tu servidor OAuth para permitir redirecciones** a tu URL de devolución de llamada.
  </Tab>

  <Tab title="JWT (JSON Web Token)">
    ### 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

    <Steps>
      <Step title="Genera una clave privada.">
        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.
      </Step>

      <Step title="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 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.
      </Step>
    </Steps>

    ### 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}`.

    <CodeGroup>
      ```ts 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), // 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
      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)
      ```
    </CodeGroup>

    ### 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.
  </Tab>
</Tabs>

<div id="make-pages-public">
  ## Hacer públicas las páginas
</div>

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

<div id="individual-pages">
  ### Páginas individuales
</div>

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

```mdx Public page example
---
title: "Página pública"
public: true
---
```

<div id="groups-of-pages">
  ### Grupos de páginas
</div>

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
{
  "navigation": {
    "groups": [
      {
        "group": "Grupo público",
        "public": true,
        "icon": "play",
        "pages": [
          "quickstart",
          "installation",
          "settings"
        ]
      },
      {
        "group": "Grupo privado",
        "icon": "pause",
        "pages": [
          "private-information",
          "secret-settings"
        ]
      }
    ]
  }
}
```

<div id="control-access-with-groups">
  ## Controla el acceso con groups
</div>

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}
{
  "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}
---
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.

<div id="interaction-with-authentication-modes">
  ### Interacción con los modos de autenticación
</div>

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
---
title: "Guía pública"
public: true
---
```

````mdx Only authenticated users can view this page
---
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"]
---
````