> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación OIDC

<Info>
  Esta funcionalidad ha sido desarrollada por [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Aquí ofrecemos documentación para tu configuración.
</Info>

### Configuración

Internamente, el módulo OIDC de Overleaf utiliza la biblioteca [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect). Si tienes problemas para configurar OpenID Connect, vale la pena leer el README de `passport-openidconnect` para hacerte una idea de la configuración que espera.

La variable de entorno `EXTERNAL_AUTH` es necesaria para habilitar el módulo de autenticación OIDC. Esta variable de entorno especifica qué métodos de autenticación externa se activan. Su valor es una lista. Si la lista incluye `oidc`, se activará la autenticación OIDC.

Por ejemplo: `EXTERNAL_AUTH=ldap oidc`

Al utilizar el método de autenticación OIDC, el usuario es redirigido al sitio de autenticación del proveedor de identidad (IdP). Si el IdP autentica correctamente al usuario, se busca en la base de datos de usuarios de Overleaf un registro que contenga un campo `thirdPartyIdentifiers` con la siguiente estructura:

```text theme={null}
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

El `externalUserId` debe coincidir con el ID de usuario del perfil devuelto por el servidor del IdP (consulta la variable de entorno `OVERLEAF_OIDC_USER_ID_FIELD`), y `providerId` debe coincidir con el ID del proveedor OIDC (consulta `OVERLEAF_OIDC_PROVIDER_ID`).

Si no se encuentra ningún registro coincidente, se busca en la base de datos un usuario cuya dirección de correo electrónico principal coincida con el correo del perfil de usuario del IdP:

* Si se encuentra dicho usuario, se actualiza el campo `thirdPartyIdentifiers`.
* Si no se encuentra ningún usuario coincidente y la creación de cuentas JIT no está deshabilitada, se crea un nuevo usuario con la dirección de correo electrónico y los `thirdPartyIdentifiers` del perfil del IdP.

En ambos casos, se dice que el usuario está "vinculado" al usuario OIDC externo. El usuario puede desvincularse del proveedor OIDC en la página `/user/settings`.

#### Encontrar los valores con el documento de descubrimiento

Todo proveedor de OpenID (OP) publica un documento de descubrimiento en `<issuer>/.well-known/openid-configuration`. Copia los valores de ahí en lugar de escribirlos a mano; basta un carácter incorrecto para que el inicio de sesión falle.

<Steps>
  <Step title="Encontrar la URL de descubrimiento">
    Tu OP la muestra en la página del cliente (proveedor) que creaste para Overleaf. En Authentik, abre **Applications > Providers**, selecciona el proveedor y busca **OpenID Configuration URL** y **OpenID Configuration Issuer**:

    <Frame caption="Authentik: la URL de descubrimiento y el emisor de un proveedor (instancia de prueba)">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-provider.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=e3cb5603d959665472b53e39b58b2775" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-provider.png" />
    </Frame>

    La URL suele tener este aspecto:

    * Keycloak: `https://keycloak.example.com/realms/<realm>/.well-known/openid-configuration`
    * Authentik: `https://authentik.example.com/application/o/<application-slug>/.well-known/openid-configuration`
  </Step>

  <Step title="Leer los valores">
    Abre la URL en un navegador o ejecuta en el servidor de Overleaf:

    ```shell theme={null}
    curl -s https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration \
      | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint}'
    ```

    La respuesta de Authentik tiene este aspecto:

    ```json theme={null}
    {
      "issuer": "https://authentik.example.com/application/o/overleaf/",
      "authorization_endpoint": "https://authentik.example.com/application/o/authorize/",
      "token_endpoint": "https://authentik.example.com/application/o/token/",
      "userinfo_endpoint": "https://authentik.example.com/application/o/userinfo/",
      "end_session_endpoint": "https://authentik.example.com/application/o/overleaf/end-session/"
    }
    ```

    Authentik también muestra estas URL más abajo en la página del proveedor:

    <Frame caption="Authentik: los endpoints de un proveedor (instancia de prueba)">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-endpoints.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=55d130cbbbf27fd11aebafa1ab3f090c" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-endpoints.png" />
    </Frame>
  </Step>

  <Step title="Copiarlos en `variables.env`">
    | Campo del documento de descubrimiento | Variable de entorno |
    | - | - |
    | `issuer` | `OVERLEAF_OIDC_ISSUER` |
    | `authorization_endpoint` | `OVERLEAF_OIDC_AUTHORIZATION_URL` |
    | `token_endpoint` | `OVERLEAF_OIDC_TOKEN_URL` |
    | `userinfo_endpoint` | `OVERLEAF_OIDC_USER_INFO_URL` |
    | `end_session_endpoint` | `OVERLEAF_OIDC_LOGOUT_URL` |

    ```dotenv theme={null}
    OVERLEAF_OIDC_ISSUER=https://authentik.example.com/application/o/overleaf/
    OVERLEAF_OIDC_AUTHORIZATION_URL=https://authentik.example.com/application/o/authorize/
    OVERLEAF_OIDC_TOKEN_URL=https://authentik.example.com/application/o/token/
    OVERLEAF_OIDC_USER_INFO_URL=https://authentik.example.com/application/o/userinfo/
    OVERLEAF_OIDC_LOGOUT_URL=https://authentik.example.com/application/o/overleaf/end-session/
    ```
  </Step>

  <Step title="Comprobar que Overleaf puede acceder al OP">
    Overleaf llama a los endpoints de token y userinfo desde dentro de su contenedor, por lo que el OP debe ser accesible desde ahí, no solo desde tu navegador:

    ```shell theme={null}
    docker exec sharelatex curl -sS -o /dev/null -w "%{http_code}\n" \
      https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration
    ```

    Debería mostrar `200`.
  </Step>
</Steps>

<Warning>
  Copia `issuer` exactamente, incluida la barra final. Overleaf lo compara carácter por carácter con el emisor del token de ID; cualquier diferencia hace que todos los inicios de sesión OIDC fallen con:

  `{"message":{"message":"ID token not issued by expected OpenID provider."}}`

  En Authentik, el emisor pertenece a la aplicación (`.../application/o/<application-slug>/`). No es la dirección del servidor de Authentik, aunque las URL de authorize, token y userinfo son compartidas por todas las aplicaciones.
</Warning>

#### Variables de entorno

Los valores de las siguientes cinco variables obligatorias pueden obtenerse a través del endpoint `.well-known/openid-configuration` de tu proveedor de OpenID (OP); consulta la sección anterior.

* `OVERLEAF_OIDC_ISSUER` <strong>(obligatoria)</strong>
* `OVERLEAF_OIDC_AUTHORIZATION_URL` <strong>(obligatoria)</strong>
* `OVERLEAF_OIDC_TOKEN_URL` <strong>(obligatoria)</strong>
* `OVERLEAF_OIDC_USER_INFO_URL` <strong>(obligatoria)</strong>
* `OVERLEAF_OIDC_LOGOUT_URL` <strong>(obligatoria)</strong>

Los valores de las siguientes dos variables obligatorias te los proporcionará el administrador de tu OP

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(obligatoria)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(obligatoria)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Valor predeterminado: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * ID arbitrario del OP; por defecto, `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * El nombre del OP, que se usa en la sección `Linked Accounts` de la página `/user/settings`; por defecto, `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Nombre visible del servicio de identidad, que se usa en la página de inicio de sesión (por defecto: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Descripción del OP, que se usa en la sección `Linked Accounts` (por defecto: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * URL de `Learn more` en la descripción del OP; por defecto, la descripción no incluye ningún enlace `Learn more`.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * No mostrar el OP en la página `/user/settings` si la cuenta del usuario no está vinculada con el OP; por defecto, `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Overleaf usará el valor de este atributo como ID de usuario externo; por defecto, `id`. Otros valores razonables posibles son `email` y `username` (correspondiente al claim OIDC `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Restringe la creación de cuentas Just-in-Time (JIT) para los usuarios que se autentican mediante OIDC. Si se establece en una lista de nombres de dominio separados por comas, solo se creará una cuenta nueva si el dominio de la dirección de correo electrónico del usuario coincide con uno de los dominios de la lista. Si el dominio no coincide, un administrador debe crear manualmente la cuenta de usuario con la dirección de correo electrónico del usuario OIDC, ya sea con una contraseña aleatoria segura o, preferiblemente, sin el campo `hashedPassword`. Los nombres de dominio pueden incluir un comodín `*.` inicial para coincidir con subdominios.
    * Ejemplo: para permitir la creación de cuentas JIT a usuarios con direcciones de correo como `name@example.com` y `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Ejemplo: para deshabilitar por completo la creación de cuentas JIT:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Si se establece en `true`, actualiza los campos `first_name` y `last_name` del usuario al iniciar sesión y deshabilita el formulario de datos del usuario en la página `/user/settings`.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` y `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Cuando ambas variables de entorno están definidas, el proceso de inicio de sesión establece `user.isAdmin = true` si el perfil devuelto por el OP contiene el atributo especificado en `OVERLEAF_OIDC_IS_ADMIN_FIELD` y su valor coincide con `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` o es un array que contiene `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` (por ejemplo, el claim `groups`); en caso contrario, `user.isAdmin` se establece en `false`. Si `OVERLEAF_OIDC_IS_ADMIN_FIELD` es `email`, se utiliza el valor del atributo `emails[0].value` para la comprobación.

La URL de redirección para tu proveedor de OpenID es `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="Ejemplo de archivo variables.env">
  ```dotenv title="variables.env" wrap theme={null}
  OVERLEAF_APP_NAME="Our Overleaf Instance"

  ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

  # Enables Thumbnail generation using ImageMagick
  ENABLE_CONVERSIONS=true

  # Disables email confirmation requirement
  EMAIL_CONFIRMATION_DISABLED=true

  ## Nginx
  # NGINX_WORKER_PROCESSES=4
  # NGINX_WORKER_CONNECTIONS=768

  ## Set for TLS via nginx-proxy
  # OVERLEAF_BEHIND_PROXY=true
  # OVERLEAF_SECURE_COOKIE=true

  OVERLEAF_SITE_URL=http://my-overleaf-instance.com
  OVERLEAF_NAV_TITLE=Our Overleaf Instance
  # OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
  OVERLEAF_ADMIN_EMAIL=support@example.com

  OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:support@example.com"}]
  OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]

  OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
  OVERLEAF_EMAIL_SMTP_HOST=smtp.example.com
  OVERLEAF_EMAIL_SMTP_PORT=587
  OVERLEAF_EMAIL_SMTP_SECURE=false
  # OVERLEAF_EMAIL_SMTP_USER=
  # OVERLEAF_EMAIL_SMTP_PASS=
  # OVERLEAF_EMAIL_SMTP_NAME=
  OVERLEAF_EMAIL_SMTP_LOGGER=false
  OVERLEAF_EMAIL_SMTP_TLS_REJECT_UNAUTH=true
  OVERLEAF_EMAIL_SMTP_IGNORE_TLS=false
  OVERLEAF_CUSTOM_EMAIL_FOOTER=This system is run by department x

  OVERLEAF_PROXY_LEARN=true
  NAV_HIDE_POWERED_BY=true

  #################
  ## OIDC for CE ##
  #################

  EXTERNAL_AUTH=oidc

  OVERLEAF_OIDC_PROVIDER_ID=oidc
  OVERLEAF_OIDC_ISSUER=https://keycloak.provider.com/realms/example
  OVERLEAF_OIDC_AUTHORIZATION_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/auth
  OVERLEAF_OIDC_TOKEN_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/token
  OVERLEAF_OIDC_USER_INFO_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/userinfo
  OVERLEAF_OIDC_LOGOUT_URL=https://keycloak.provider.com/realms/example/protocol/openid-connect/logout
  OVERLEAF_OIDC_CLIENT_ID=Overleaf-OIDC
  OVERLEAF_OIDC_CLIENT_SECRET=DoNotUseThisATGgaAcTgCcATgGATTACAagGtTCaGcGTAG
  OVERLEAF_OIDC_IDENTITY_SERVICE_NAME='Log in with Keycloak OIDC Provider'
  OVERLEAF_OIDC_PROVIDER_NAME=OIDC Keycloak Provider
  OVERLEAF_OIDC_PROVIDER_INFO_LINK=https://openid.net
  OVERLEAF_OIDC_IS_ADMIN_FIELD=email
  OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=overleaf.admin@example.com
  OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
  ```
</Accordion>

## Paso a paso: goauthentik

Esta guía describe una configuración probada con [goauthentik](https://goauthentik.io/). Sustituye `https://overleaf.example.com` por tu `OVERLEAF_SITE_URL` y `https://authentik.example.com` por la dirección de tu Authentik.

<Steps>
  <Step title="Crear el proveedor">
    En Authentik, abre **Applications > Providers**, haz clic en **New Provider**, elige **OAuth2/OpenID Provider** y haz clic en **Next**.

    * **Client Type**: `Confidential`.
    * **Redirect URIs** (en **Protocol settings**): añade `https://overleaf.example.com/oidc/login/callback` con el modo de coincidencia `Strict`.
    * Copia ahora **Client ID** y **Client Secret** en `OVERLEAF_OIDC_CLIENT_ID` y `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik: Client ID y Client Secret de un nuevo proveedor">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-create.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=f127a92eaf3063714e9af515fe97c263" alt="" width="1120" height="808" data-path="images/on-premises/oidc-authentik-create.png" />
    </Frame>

    <Warning>
      Authentik solo muestra el secreto del cliente mientras creas el proveedor. Más adelante, el formulario de edición solo ofrece **Modify**, que sustituye el secreto por uno nuevo.
    </Warning>
  </Step>

  <Step title="Crear la aplicación">
    Abre **Applications > Applications**, crea una nueva aplicación, asígnale un nombre y un slug, por ejemplo `overleaf`, y selecciona el proveedor. El slug pasa a formar parte del emisor: `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="Copiar las URL">
    Sigue la sección [Encontrar los valores con el documento de descubrimiento](#encontrar-los-valores-con-el-documento-de-descubrimiento) anterior para rellenar las cinco URL.
  </Step>

  <Step title="Asignar los administradores (opcional)">
    Authentik envía los grupos del usuario en el claim `groups`, que es un array. Para que los miembros del grupo `Admins` de Authentik sean administradores de Overleaf:

    ```dotenv theme={null}
    OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
    OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
    ```

    <Warning>
      El indicador de administrador se actualiza en cada inicio de sesión OIDC. Con un campo o un valor incorrecto, todos los administradores que inicien sesión mediante OIDC pierden los derechos de administrador, incluido el administrador creado en el launchpad. Prueba primero la asignación con una segunda cuenta de administrador.
    </Warning>
  </Step>
</Steps>

<Accordion title="Archivo variables.env probado para goauthentik">
  ```dotenv title="variables.env" wrap theme={null}
  EXTERNAL_AUTH=oidc
  OVERLEAF_OIDC_PROVIDER_ID=authentik
  OVERLEAF_OIDC_IDENTITY_SERVICE_NAME=Log in with Authentik
  OVERLEAF_OIDC_ISSUER=https://authentik.example.com/application/o/overleaf/
  OVERLEAF_OIDC_AUTHORIZATION_URL=https://authentik.example.com/application/o/authorize/
  OVERLEAF_OIDC_TOKEN_URL=https://authentik.example.com/application/o/token/
  OVERLEAF_OIDC_USER_INFO_URL=https://authentik.example.com/application/o/userinfo/
  OVERLEAF_OIDC_LOGOUT_URL=https://authentik.example.com/application/o/overleaf/end-session/
  OVERLEAF_OIDC_CLIENT_ID=<Client ID>
  OVERLEAF_OIDC_CLIENT_SECRET=<Client Secret>
  OVERLEAF_OIDC_USER_ID_FIELD=username
  OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
  OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
  OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=true
  ```
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.