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

# OIDC-authenticatie

<Info>
  Deze functie is ontwikkeld door [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Hier bieden we wat documentatie voor je configuratie.
</Info>

### Configuratie

Intern gebruikt de OIDC-module van Overleaf de bibliotheek [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect). Als je problemen hebt met het configureren van OpenID Connect, is het de moeite waard om de README van `passport-openidconnect` te lezen om een idee te krijgen van de configuratie die deze verwacht.

De omgevingsvariabele `EXTERNAL_AUTH` is vereist om de OIDC-authenticatiemodule in te schakelen. Deze omgevingsvariabele geeft aan welke externe authenticatiemethoden worden geactiveerd. De waarde van deze variabele is een lijst. Als de lijst `oidc` bevat, wordt OIDC-authenticatie geactiveerd.

Bijvoorbeeld: `EXTERNAL_AUTH=ldap oidc`

Bij gebruik van de OIDC-authenticatiemethode wordt een gebruiker doorgestuurd naar de authenticatiesite van de Identity Provider (IdP). Als de IdP de gebruiker succesvol authenticeert, wordt in de gebruikersdatabase van Overleaf gezocht naar een record met een veld `thirdPartyIdentifiers` met de volgende structuur:

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

De `externalUserId` moet overeenkomen met het gebruikers-ID in het profiel dat door de IdP-server wordt geretourneerd (zie de omgevingsvariabele `OVERLEAF_OIDC_USER_ID_FIELD`), en `providerId` moet overeenkomen met het ID van de OIDC-provider (zie `OVERLEAF_OIDC_PROVIDER_ID`).

Als er geen overeenkomend record wordt gevonden, wordt in de database gezocht naar een gebruiker van wie het primaire e-mailadres overeenkomt met het e-mailadres in het gebruikersprofiel van de IdP:

* Als zo'n gebruiker wordt gevonden, wordt het veld `thirdPartyIdentifiers` bijgewerkt.
* Als er geen overeenkomende gebruiker wordt gevonden en het JIT-aanmaken van accounts niet is uitgeschakeld, wordt een nieuwe gebruiker aangemaakt met het e-mailadres en de `thirdPartyIdentifiers` uit het IdP-profiel.

In beide gevallen wordt gezegd dat de gebruiker 'gekoppeld' is aan de externe OIDC-gebruiker. De gebruiker kan op de pagina `/user/settings` worden ontkoppeld van de OIDC-provider.

#### De waarden vinden met het discovery-document

Elke OpenID Provider (OP) publiceert een discovery-document op `<issuer>/.well-known/openid-configuration`. Kopieer de waarden daaruit in plaats van ze met de hand over te typen; één verkeerd teken is genoeg om het inloggen te laten mislukken.

<Steps>
  <Step title="Zoek de discovery-URL">
    Je OP toont deze op de pagina van de client (provider) die je voor Overleaf hebt aangemaakt. Open in Authentik **Applications > Providers**, selecteer de provider en zoek naar **OpenID Configuration URL** en **OpenID Configuration Issuer**:

    <Frame caption="Authentik: de discovery-URL en de issuer van een provider (testinstantie)">
      <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>

    De URL ziet er meestal zo uit:

    * 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="Lees de waarden uit">
    Open de URL in een browser, of voer op de Overleaf-server uit:

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

    Het antwoord van Authentik ziet er zo uit:

    ```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 vermeldt deze URL's ook verderop op de providerpagina:

    <Frame caption="Authentik: de endpoints van een provider (testinstantie)">
      <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="Kopieer ze naar `variables.env`">
    | Veld in het discovery-document | Omgevingsvariabele |
    | - | - |
    | `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="Controleer of Overleaf de OP kan bereiken">
    Overleaf roept de token- en userinfo-endpoints aan vanuit zijn container, dus de OP moet vanaf daar bereikbaar zijn, niet alleen vanuit je browser:

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

    Dit zou `200` moeten tonen.
  </Step>
</Steps>

<Warning>
  Kopieer `issuer` exact, inclusief de afsluitende slash. Overleaf vergelijkt deze teken voor teken met de issuer in het ID-token; elk verschil laat elke OIDC-aanmelding mislukken met:

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

  In Authentik hoort de issuer bij de applicatie (`.../application/o/<application-slug>/`). Het is niet het adres van de Authentik-server, hoewel de authorize-, token- en userinfo-URL's door alle applicaties worden gedeeld.
</Warning>

#### Omgevingsvariabelen

De waarden van de volgende vijf verplichte variabelen kun je vinden via het endpoint `.well-known/openid-configuration` van je OpenID Provider (OP), zie hierboven.

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

De waarden van de volgende twee verplichte variabelen worden verstrekt door de beheerder van je OP

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(verplicht)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(verplicht)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Standaard: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * Willekeurig ID van de OP, standaard `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * De naam van de OP, gebruikt in de sectie `Linked Accounts` van de pagina `/user/settings`, standaard `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Weergavenaam voor de identiteitsdienst, gebruikt op de inlogpagina (standaard: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Beschrijving van de OP, gebruikt in de sectie `Linked Accounts` (standaard: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * URL voor `Learn more` in de beschrijving van de OP; standaard: geen `Learn more`-link in de beschrijving.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Toon de OP niet op de pagina `/user/settings` als het account van de gebruiker niet aan de OP is gekoppeld; standaard `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * De waarde van dit attribuut wordt door Overleaf gebruikt als het externe gebruikers-ID, standaard `id`. Andere mogelijke redelijke waarden zijn `email` en `username` (overeenkomend met de OIDC-claim `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Beperkt het Just-in-Time (JIT) aanmaken van accounts voor gebruikers die zich via OIDC authenticeren. Als deze is ingesteld op een door komma's gescheiden lijst met domeinnamen, wordt alleen een nieuw account aangemaakt als het domein van het e-mailadres van de gebruiker overeenkomt met een van de vermelde domeinen. Als het domein niet overeenkomt, moet een beheerder het gebruikersaccount handmatig aanmaken met het e-mailadres van de OIDC-gebruiker, met een sterk willekeurig wachtwoord of bij voorkeur helemaal zonder het veld `hashedPassword`. Domeinnamen mogen beginnen met een `*.`-jokerteken om subdomeinen te matchen.
    * Voorbeeld: om JIT-accountaanmaak toe te staan voor gebruikers met e-mailadressen zoals `name@example.com` en `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Voorbeeld: om JIT-accountaanmaak volledig uit te schakelen:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Als deze is ingesteld op `true`, worden de velden `first_name` en `last_name` van de gebruiker bij het inloggen bijgewerkt en wordt het formulier met gebruikersgegevens op de pagina `/user/settings` uitgeschakeld.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` en `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Wanneer beide omgevingsvariabelen zijn ingesteld, stelt het inlogproces `user.isAdmin = true` in als het door de OP geretourneerde profiel het attribuut bevat dat is opgegeven door `OVERLEAF_OIDC_IS_ADMIN_FIELD` en de waarde ervan overeenkomt met `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` of een array is die `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` bevat (bijvoorbeeld de claim `groups`); anders wordt `user.isAdmin` ingesteld op `false`. Als `OVERLEAF_OIDC_IS_ADMIN_FIELD` gelijk is aan `email`, wordt de waarde van het attribuut `emails[0].value` gebruikt voor de controle.

De redirect-URL voor je OpenID Provider is `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="Voorbeeld van een variables.env-bestand">
  ```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>

## Stap voor stap: goauthentik

Hieronder doorlopen we een setup die is getest met [goauthentik](https://goauthentik.io/). Vervang `https://overleaf.example.com` door je `OVERLEAF_SITE_URL` en `https://authentik.example.com` door het adres van je Authentik.

<Steps>
  <Step title="Maak de provider aan">
    Open in Authentik **Applications > Providers**, klik op **New Provider**, kies **OAuth2/OpenID Provider** en klik op **Next**.

    * **Client Type**: `Confidential`.
    * **Redirect URIs** (onder **Protocol settings**): voeg `https://overleaf.example.com/oidc/login/callback` toe met de matching-modus `Strict`.
    * Kopieer nu **Client ID** en **Client Secret** naar `OVERLEAF_OIDC_CLIENT_ID` en `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik: Client ID en Client Secret van een nieuwe provider">
      <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 toont het client secret alleen tijdens het aanmaken van de provider. Later biedt het bewerkingsformulier alleen **Modify**, waarmee het secret wordt vervangen door een nieuw secret.
    </Warning>
  </Step>

  <Step title="Maak de applicatie aan">
    Open **Applications > Applications**, maak een nieuwe applicatie aan, geef deze een naam en een slug, bijvoorbeeld `overleaf`, en selecteer de provider. De slug wordt onderdeel van de issuer: `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="Kopieer de URL's">
    Volg [De waarden vinden met het discovery-document](#de-waarden-vinden-met-het-discovery-document) hierboven om de vijf URL's in te vullen.
  </Step>

  <Step title="Koppel de beheerders (optioneel)">
    Authentik stuurt de groepen van de gebruiker als de claim `groups`, een array. Om de leden van de Authentik-groep `Admins` beheerder van Overleaf te maken:

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

    <Warning>
      De beheerdersvlag wordt bij elke OIDC-aanmelding bijgewerkt. Met een verkeerd veld of een verkeerde waarde verliest elke beheerder die via OIDC inlogt de beheerdersrechten, inclusief de beheerder die in de launchpad is aangemaakt. Test de koppeling eerst met een tweede beheerdersaccount.
    </Warning>
  </Step>
</Steps>

<Accordion title="Geteste variables.env voor 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.