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

# Authentification OIDC

<Info>
  Cette fonctionnalité est développée par [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Nous proposons ici quelques documents pour vous aider dans votre configuration.
</Info>

### Configuration

En interne, le module OIDC d'Overleaf utilise la bibliothèque [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect). Si vous rencontrez des difficultés pour configurer OpenID Connect, il est utile de lire le README de `passport-openidconnect` pour vous faire une idée de la configuration attendue.

La variable d'environnement `EXTERNAL_AUTH` est requise pour activer le module d'authentification OIDC. Cette variable d'environnement indique quelles méthodes d'authentification externes sont activées. Sa valeur est une liste. Si la liste contient `oidc`, l'authentification OIDC sera activée.

Par exemple : `EXTERNAL_AUTH=ldap oidc`

Avec la méthode d'authentification OIDC, l'utilisateur est redirigé vers le site d'authentification du fournisseur d'identité (IdP). Si l'IdP authentifie l'utilisateur avec succès, la base de données des utilisateurs Overleaf est consultée à la recherche d'un enregistrement contenant un champ `thirdPartyIdentifiers` structuré comme suit :

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

`externalUserId` doit correspondre à l'identifiant utilisateur présent dans le profil renvoyé par le serveur IdP (voir la variable d'environnement `OVERLEAF_OIDC_USER_ID_FIELD`), et `providerId` doit correspondre à l'identifiant du fournisseur OIDC (voir `OVERLEAF_OIDC_PROVIDER_ID`).

Si aucun enregistrement correspondant n'est trouvé, la base de données est parcourue à la recherche d'un utilisateur dont l'adresse e-mail principale correspond à l'e-mail du profil utilisateur de l'IdP :

* Si un tel utilisateur est trouvé, le champ `thirdPartyIdentifiers` est mis à jour.
* Si aucun utilisateur correspondant n'est trouvé et que la création de compte JIT n'est pas désactivée, un nouvel utilisateur est créé avec l'adresse e-mail et les `thirdPartyIdentifiers` issus du profil de l'IdP.

Dans les deux cas, on dit que l'utilisateur est « lié » à l'utilisateur OIDC externe. L'utilisateur peut être dissocié du fournisseur OIDC sur la page `/user/settings`.

#### Trouver les valeurs à l'aide du document de découverte

Chaque fournisseur OpenID (OP) publie un document de découverte à l'adresse `<issuer>/.well-known/openid-configuration`. Copiez-en les valeurs au lieu de les saisir à la main ; un seul caractère erroné suffit à empêcher la connexion.

<Steps>
  <Step title="Trouver l'URL de découverte">
    Votre OP l'affiche sur la page du client (fournisseur) que vous avez créé pour Overleaf. Dans Authentik, ouvrez **Applications > Providers**, sélectionnez le fournisseur et repérez **OpenID Configuration URL** et **OpenID Configuration Issuer** :

    <Frame caption="Authentik : l'URL de découverte et l'émetteur d'un fournisseur (instance de test)">
      <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>

    L'URL ressemble généralement à ceci :

    * 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="Lire les valeurs">
    Ouvrez l'URL dans un navigateur, ou exécutez sur le serveur 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 réponse d'Authentik ressemble à ceci :

    ```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 liste également ces URL plus bas sur la page du fournisseur :

    <Frame caption="Authentik : les points de terminaison d'un fournisseur (instance de test)">
      <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="Les copier dans `variables.env`">
    | Champ du document de découverte | Variable d'environnement |
    | - | - |
    | `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="Vérifier qu'Overleaf peut joindre l'OP">
    Overleaf appelle les points de terminaison token et userinfo depuis son conteneur ; l'OP doit donc être joignable depuis celui-ci, et pas seulement depuis votre navigateur :

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

    La commande doit afficher `200`.
  </Step>
</Steps>

<Warning>
  Copiez `issuer` exactement, y compris la barre oblique finale. Overleaf le compare caractère par caractère avec l'émetteur du jeton d'identité ; toute différence fait échouer chaque connexion OIDC avec :

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

  Dans Authentik, l'émetteur appartient à l'application (`.../application/o/<application-slug>/`). Ce n'est pas l'adresse du serveur Authentik, bien que les URL authorize, token et userinfo soient partagées par toutes les applications.
</Warning>

#### Variables d'environnement

Les valeurs des cinq variables obligatoires suivantes se trouvent via le point de terminaison `.well-known/openid-configuration` de votre fournisseur OpenID (OP), voir ci-dessus.

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

Les valeurs des deux variables obligatoires suivantes vous seront fournies par l'administrateur de votre OP

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(obligatoire)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(obligatoire)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Par défaut : `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * Identifiant arbitraire de l'OP, par défaut `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * Nom de l'OP, utilisé dans la section `Linked Accounts` de la page `/user/settings`, par défaut `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Nom d'affichage du service d'identité, utilisé sur la page de connexion (par défaut : `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Description de l'OP, utilisée dans la section `Linked Accounts` (par défaut : `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * URL `Learn more` dans la description de l'OP ; par défaut, aucun lien `Learn more` dans la description.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Ne pas afficher l'OP sur la page `/user/settings` si le compte de l'utilisateur n'est pas lié à l'OP, par défaut `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * La valeur de cet attribut sera utilisée par Overleaf comme identifiant utilisateur externe, par défaut `id`. D'autres valeurs raisonnables possibles sont `email` et `username` (correspondant à la claim OIDC `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Restreint la création de compte Just-in-Time (JIT) pour les utilisateurs s'authentifiant via OIDC. Si elle est définie comme une liste de noms de domaine séparés par des virgules, un nouveau compte ne sera créé que si le domaine de l'adresse e-mail de l'utilisateur correspond à l'un des domaines listés. Si le domaine ne correspond pas, un administrateur doit créer manuellement le compte utilisateur avec l'adresse e-mail de l'utilisateur OIDC, soit avec un mot de passe aléatoire robuste, soit, de préférence, sans aucun champ `hashedPassword`. Les noms de domaine peuvent commencer par le joker `*.` pour inclure les sous-domaines.
    * Exemple : pour autoriser la création de compte JIT pour les utilisateurs ayant une adresse e-mail comme `name@example.com` et `name@math.example.com` :\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Exemple : pour désactiver complètement la création de compte JIT :\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Si elle vaut `true`, met à jour les champs `first_name` et `last_name` de l'utilisateur à la connexion, et désactive le formulaire des informations utilisateur sur la page `/user/settings`.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` et `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Lorsque ces deux variables d'environnement sont définies, le processus de connexion met à jour `user.isAdmin = true` si le profil renvoyé par l'OP contient l'attribut indiqué par `OVERLEAF_OIDC_IS_ADMIN_FIELD` et que sa valeur correspond à `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` ou est un tableau contenant `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` (par exemple le claim `groups`) ; sinon, `user.isAdmin` est défini à `false`. Si `OVERLEAF_OIDC_IS_ADMIN_FIELD` vaut `email`, la valeur de l'attribut `emails[0].value` est utilisée pour la vérification.

L'URL de redirection pour votre fournisseur OpenID est `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="Exemple de fichier 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>

## Guide pas à pas avec goauthentik

Ce guide décrit une configuration testée avec [goauthentik](https://goauthentik.io/). Remplacez `https://overleaf.example.com` par votre `OVERLEAF_SITE_URL` et `https://authentik.example.com` par l'adresse de votre Authentik.

<Steps>
  <Step title="Créer le fournisseur">
    Dans Authentik, ouvrez **Applications > Providers**, cliquez sur **New Provider**, choisissez **OAuth2/OpenID Provider** puis cliquez sur **Next**.

    * **Client Type** : `Confidential`.
    * **Redirect URIs** (sous **Protocol settings**) : ajoutez `https://overleaf.example.com/oidc/login/callback` avec le mode de correspondance `Strict`.
    * Copiez dès maintenant **Client ID** et **Client Secret** dans `OVERLEAF_OIDC_CLIENT_ID` et `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik : Client ID et Client Secret d'un nouveau fournisseur">
      <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 n'affiche le secret client que pendant la création du fournisseur. Par la suite, le formulaire de modification ne propose que **Modify**, qui remplace le secret par un nouveau.
    </Warning>
  </Step>

  <Step title="Créer l'application">
    Ouvrez **Applications > Applications**, créez une nouvelle application, donnez-lui un nom et un slug, par exemple `overleaf`, puis sélectionnez le fournisseur. Le slug fait partie de l'émetteur : `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="Copier les URL">
    Suivez la section [Trouver les valeurs à l'aide du document de découverte](#trouver-les-valeurs-à-laide-du-document-de-découverte) ci-dessus pour renseigner les cinq URL.
  </Step>

  <Step title="Associer les administrateurs (facultatif)">
    Authentik envoie les groupes de l'utilisateur dans le claim `groups`, sous forme de tableau. Pour que les membres du groupe Authentik `Admins` deviennent administrateurs d'Overleaf :

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

    <Warning>
      L'indicateur d'administrateur est mis à jour à chaque connexion OIDC. Avec un champ ou une valeur incorrects, tout administrateur qui se connecte via OIDC perd ses droits d'administrateur, y compris l'administrateur créé dans le launchpad. Testez d'abord l'association avec un second compte administrateur.
    </Warning>
  </Step>
</Steps>

<Accordion title="Fichier variables.env testé pour 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.