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

<Info>
  Diese Funktion wurde von [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep) entwickelt. Hier stellen wir einige Dokumente für Ihre Konfiguration bereit.
</Info>

### Konfiguration

Intern verwendet das Overleaf-OIDC-Modul die Bibliothek [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect). Wenn Sie Probleme bei der Konfiguration von OpenID Connect haben, lohnt es sich, die README von `passport-openidconnect` zu lesen, um ein Gefühl für die erwartete Konfiguration zu bekommen.

Die Umgebungsvariable `EXTERNAL_AUTH` ist erforderlich, um das OIDC-Authentifizierungsmodul zu aktivieren. Diese Umgebungsvariable legt fest, welche externen Authentifizierungsmethoden aktiviert sind. Der Wert dieser Variablen ist eine Liste. Enthält die Liste `oidc`, wird die OIDC-Authentifizierung aktiviert.

Beispiel: `EXTERNAL_AUTH=ldap oidc`

Bei Verwendung der OIDC-Authentifizierungsmethode wird ein Benutzer auf die Authentifizierungsseite des Identity Providers (IdP) weitergeleitet. Wenn der IdP den Benutzer erfolgreich authentifiziert, wird die Overleaf-Benutzerdatenbank nach einem Datensatz durchsucht, der ein Feld `thirdPartyIdentifiers` mit folgender Struktur enthält:

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

Die `externalUserId` muss mit der Benutzer-ID im vom IdP-Server zurückgegebenen Profil übereinstimmen (siehe Umgebungsvariable `OVERLEAF_OIDC_USER_ID_FIELD`), und `providerId` muss mit der ID des OIDC-Providers übereinstimmen (siehe `OVERLEAF_OIDC_PROVIDER_ID`).

Wird kein passender Datensatz gefunden, wird die Datenbank nach einem Benutzer durchsucht, dessen primäre E-Mail-Adresse mit der E-Mail-Adresse im IdP-Benutzerprofil übereinstimmt:

* Wird ein solcher Benutzer gefunden, wird das Feld `thirdPartyIdentifiers` aktualisiert.
* Wird kein passender Benutzer gefunden und ist die JIT-Kontoerstellung nicht deaktiviert, wird ein neuer Benutzer mit der E-Mail-Adresse und den `thirdPartyIdentifiers` aus dem IdP-Profil angelegt.

In beiden Fällen gilt der Benutzer als mit dem externen OIDC-Benutzer „verknüpft“. Der Benutzer kann die Verknüpfung mit dem OIDC-Provider auf der Seite `/user/settings` aufheben.

#### Werte über das Discovery-Dokument ermitteln

Jeder OpenID Provider (OP) veröffentlicht ein Discovery-Dokument unter `<issuer>/.well-known/openid-configuration`. Kopieren Sie die Werte daraus, statt sie von Hand einzutippen; ein einziges falsches Zeichen genügt, damit die Anmeldung fehlschlägt.

<Steps>
  <Step title="Discovery-URL finden">
    Ihr OP zeigt sie auf der Seite des Clients (Providers) an, den Sie für Overleaf angelegt haben. Öffnen Sie in Authentik **Applications > Providers**, wählen Sie den Provider aus und suchen Sie nach **OpenID Configuration URL** und **OpenID Configuration Issuer**:

    <Frame caption="Authentik: Discovery-URL und Issuer eines Providers (Testinstanz)">
      <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>

    Die URL sieht in der Regel so aus:

    * 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="Werte auslesen">
    Öffnen Sie die URL in einem Browser oder führen Sie auf dem Overleaf-Server Folgendes aus:

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

    Die Antwort von Authentik sieht so aus:

    ```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 listet diese URLs auch weiter unten auf der Provider-Seite auf:

    <Frame caption="Authentik: die Endpunkte eines Providers (Testinstanz)">
      <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="In `variables.env` übernehmen">
    | Feld im Discovery-Dokument | Umgebungsvariable |
    | - | - |
    | `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="Prüfen, ob Overleaf den OP erreicht">
    Overleaf ruft die Token- und Userinfo-Endpunkte aus seinem Container heraus auf. Der OP muss daher von dort aus erreichbar sein, nicht nur von Ihrem 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
    ```

    Die Ausgabe sollte `200` lauten.
  </Step>
</Steps>

<Warning>
  Kopieren Sie `issuer` exakt, einschließlich des abschließenden Schrägstrichs. Overleaf vergleicht ihn Zeichen für Zeichen mit dem Issuer im ID-Token; jede Abweichung lässt jede OIDC-Anmeldung mit folgender Meldung fehlschlagen:

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

  In Authentik gehört der Issuer zur Anwendung (`.../application/o/<application-slug>/`). Er ist nicht die Adresse des Authentik-Servers, obwohl die Authorize-, Token- und Userinfo-URLs von allen Anwendungen gemeinsam genutzt werden.
</Warning>

#### Umgebungsvariablen

Die Werte der folgenden fünf erforderlichen Variablen finden Sie über den Endpunkt `.well-known/openid-configuration` Ihres OpenID Providers (OP), siehe oben.

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

Die Werte der folgenden zwei erforderlichen Variablen werden Ihnen vom Administrator Ihres OP bereitgestellt

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(erforderlich)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(erforderlich)</strong>
* `OVERLEAF_OIDC_SCOPE`
  * Standard: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * Beliebige ID des OP, Standard ist `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * Der Name des OP, der im Abschnitt `Linked Accounts` der Seite `/user/settings` verwendet wird, Standard ist `OIDC Provider`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Anzeigename des Identitätsdienstes, der auf der Anmeldeseite verwendet wird (Standard: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Beschreibung des OP, die im Abschnitt `Linked Accounts` verwendet wird (Standard: `Log in with $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `Learn more`-URL in der OP-Beschreibung, Standard: kein `Learn more`-Link in der Beschreibung.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Den OP auf der Seite `/user/settings` nicht anzeigen, wenn das Benutzerkonto nicht mit dem OP verknüpft ist, Standard `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Der Wert dieses Attributs wird von Overleaf als externe Benutzer-ID verwendet, Standard ist `id`. Weitere sinnvolle Werte sind `email` und `username` (entspricht dem OIDC-Claim `preferred_username`).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Schränkt die Just-in-Time-(JIT-)Kontoerstellung für Benutzer ein, die sich über OIDC authentifizieren. Ist hier eine kommagetrennte Liste von Domainnamen gesetzt, wird ein neues Konto nur erstellt, wenn die Domain der E-Mail-Adresse des Benutzers mit einer der aufgeführten Domains übereinstimmt. Stimmt die Domain nicht überein, muss ein Administrator das Benutzerkonto manuell mit der E-Mail-Adresse des OIDC-Benutzers anlegen – entweder mit einem starken zufälligen Passwort oder vorzugsweise ganz ohne das Feld `hashedPassword`. Domainnamen können ein vorangestelltes `*.` als Platzhalter enthalten, um Subdomains abzudecken.
    * Beispiel: Um die JIT-Kontoerstellung für Benutzer mit E-Mail-Adressen wie `name@example.com` und `name@math.example.com` zu erlauben:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Beispiel: Um die JIT-Kontoerstellung vollständig zu deaktivieren:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Wenn auf `true` gesetzt, werden die Felder `first_name` und `last_name` des Benutzers bei der Anmeldung aktualisiert, und das Formular für Benutzerdetails auf der Seite `/user/settings` wird deaktiviert.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` und `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Wenn beide Umgebungsvariablen gesetzt sind, setzt der Anmeldevorgang `user.isAdmin = true`, sofern das vom OP zurückgegebene Profil das durch `OVERLEAF_OIDC_IS_ADMIN_FIELD` angegebene Attribut enthält und dessen Wert entweder mit `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` übereinstimmt oder ein Array ist, das `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE` enthält (zum Beispiel der `groups`-Claim); andernfalls wird `user.isAdmin` auf `false` gesetzt. Ist `OVERLEAF_OIDC_IS_ADMIN_FIELD` gleich `email`, wird der Wert des Attributs `emails[0].value` für die Prüfung verwendet.

Die Redirect-URL für Ihren OpenID Provider lautet `https://my-overleaf-instance.com/oidc/login/callback`.

<Accordion title="Beispieldatei 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>

## Schritt für Schritt: goauthentik

Diese Anleitung beschreibt eine Einrichtung, die mit [goauthentik](https://goauthentik.io/) getestet wurde. Ersetzen Sie `https://overleaf.example.com` durch Ihre `OVERLEAF_SITE_URL` und `https://authentik.example.com` durch die Adresse Ihrer Authentik-Instanz.

<Steps>
  <Step title="Provider anlegen">
    Öffnen Sie in Authentik **Applications > Providers**, klicken Sie auf **New Provider**, wählen Sie **OAuth2/OpenID Provider** und klicken Sie auf **Next**.

    * **Client Type**: `Confidential`.
    * **Redirect URIs** (unter **Protocol settings**): Fügen Sie `https://overleaf.example.com/oidc/login/callback` mit dem Abgleichmodus `Strict` hinzu.
    * Kopieren Sie **Client ID** und **Client Secret** jetzt in `OVERLEAF_OIDC_CLIENT_ID` und `OVERLEAF_OIDC_CLIENT_SECRET`.

    <Frame caption="Authentik: Client ID und Client Secret eines neuen Providers">
      <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 zeigt das Client Secret nur beim Anlegen des Providers an. Später bietet das Bearbeitungsformular nur noch **Modify** an, wodurch das Secret durch ein neues ersetzt wird.
    </Warning>
  </Step>

  <Step title="Anwendung anlegen">
    Öffnen Sie **Applications > Applications**, legen Sie eine neue Anwendung an, geben Sie ihr einen Namen und einen Slug, zum Beispiel `overleaf`, und wählen Sie den Provider aus. Der Slug wird Teil des Issuers: `https://authentik.example.com/application/o/overleaf/`.
  </Step>

  <Step title="URLs kopieren">
    Folgen Sie dem Abschnitt [Werte über das Discovery-Dokument ermitteln](#werte-über-das-discovery-dokument-ermitteln) oben, um die fünf URLs einzutragen.
  </Step>

  <Step title="Administratoren zuordnen (optional)">
    Authentik sendet die Gruppen des Benutzers als `groups`-Claim, ein Array. Um die Mitglieder der Authentik-Gruppe `Admins` zu Administratoren von Overleaf zu machen:

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

    <Warning>
      Das Admin-Flag wird bei jeder OIDC-Anmeldung aktualisiert. Bei einem falschen Feld oder Wert verliert jeder Administrator, der sich über OIDC anmeldet, seine Administratorrechte, einschließlich des im Launchpad angelegten Administrators. Testen Sie die Zuordnung zuerst mit einem zweiten Administratorkonto.
    </Warning>
  </Step>
</Steps>

<Accordion title="Getestete variables.env für 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.