Zum Hauptinhalt springen
Diese Funktion wurde von yu-i-i/overleaf-cep entwickelt. Hier stellen wir einige Dokumente für Ihre Konfiguration bereit.

Konfiguration

Intern verwendet das Overleaf-OIDC-Modul die Bibliothek 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:
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.
1

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:

Authentik: Discovery-URL und Issuer eines Providers (Testinstanz)

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
2

Werte auslesen

Öffnen Sie die URL in einem Browser oder führen Sie auf dem Overleaf-Server Folgendes aus:
Die Antwort von Authentik sieht so aus:
Authentik listet diese URLs auch weiter unten auf der Provider-Seite auf:

Authentik: die Endpunkte eines Providers (Testinstanz)

3

In variables.env übernehmen

4

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:
Die Ausgabe sollte 200 lauten.
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.

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 (erforderlich)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (erforderlich)
  • OVERLEAF_OIDC_TOKEN_URL (erforderlich)
  • OVERLEAF_OIDC_USER_INFO_URL (erforderlich)
  • OVERLEAF_OIDC_LOGOUT_URL (erforderlich)
Die Werte der folgenden zwei erforderlichen Variablen werden Ihnen vom Administrator Ihres OP bereitgestellt
  • OVERLEAF_OIDC_CLIENT_ID (erforderlich)
  • OVERLEAF_OIDC_CLIENT_SECRET (erforderlich)
  • 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.
variables.env

Schritt für Schritt: goauthentik

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

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.

Authentik: Client ID und Client Secret eines neuen Providers

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

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/.
3

URLs kopieren

Folgen Sie dem Abschnitt Werte über das Discovery-Dokument ermitteln oben, um die fünf URLs einzutragen.
4

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:
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.
variables.env

Fragen & Antworten

Antwort: Prüfen Sie Folgendes:
  • Version. Vor v6.3.0 hat Overleaf benutzerdefinierte Claims wie groups nicht ausgelesen, sodass nur OVERLEAF_OIDC_IS_ADMIN_FIELD=email funktionierte. Aktualisieren Sie auf v6.3.0 oder neuer.
  • Der Claim muss in der UserInfo-Antwort enthalten sein. Overleaf liest den Claim aus OVERLEAF_OIDC_USER_INFO_URL, nicht aus dem ID-Token. Wenn Ihr OP den Claim nur zum ID-Token hinzufügt, fügen Sie ihn auch zu UserInfo hinzu, zum Beispiel mit Add to userinfo bei einem Keycloak-Mapper.
  • Der Wert muss exakt übereinstimmen, einschließlich Groß-/Kleinschreibung, zum Beispiel Admins.
Der Admin-Status wird bei jeder Anmeldung erneut geprüft: Ein Benutzer, der im Admin-Bereich zum Administrator gemacht wurde, verliert diesen Status bei der nächsten Anmeldung, wenn der Claim nicht übereinstimmt.
Antwort: Nein. GitHub unterstützt für die Benutzeranmeldung OAuth 2.0, aber nicht OpenID Connect: Es gibt kein ID-Token zurück, das Overleaf jedoch benötigt, sodass die Anmeldung mit ID token not present in token response fehlschlägt.Damit sich Benutzer mit ihrem GitHub-Konto anmelden können, verwenden Sie einen Identity Provider wie goauthentik oder Keycloak mit GitHub als Anmeldequelle und verbinden Sie Overleaf per OIDC mit diesem Provider.
Antwort: Ja. GitLab, einschließlich selbst verwaltetem GitLab, ist ein OpenID-Connect-Provider. Erstellen Sie in GitLab unter Applications (in den Einstellungen Ihres Benutzers, Ihrer Gruppe oder des Admin-Bereichs) eine Anwendung mit:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile und email
Lesen Sie die Endpunkte dann aus https://gitlab.com/.well-known/openid-configuration oder aus demselben Pfad auf Ihrem GitLab aus, wie unter Werte über das Discovery-Dokument ermitteln beschrieben. Für gitlab.com lautet der Issuer https://gitlab.com, ohne abschließenden Schrägstrich.
Antwort: Vor der Weiterleitung zum OP speichert Overleaf einen zufälligen state-Wert in der Sitzung des Benutzers und prüft ihn, wenn der OP zurückleitet. Diese Fehler bedeuten, dass die Sitzung beim Callback nicht diejenige ist, mit der die Anmeldung begonnen wurde.Unable to verify authorization request state bedeutet, dass der Browser das Sitzungscookie beim Callback nicht zurückgesendet hat. Prüfen Sie Folgendes:
  • Benutzer öffnen Overleaf unter der Adresse aus OVERLEAF_SITE_URL. Der Callback geht immer an OVERLEAF_SITE_URL, daher verliert eine Anmeldung, die von einer anderen Adresse aus gestartet wurde, etwa http://192.168.1.20, während OVERLEAF_SITE_URL https://overleaf.example.com ist, ihre Sitzung.
  • OVERLEAF_SECURE_COOKIE ist nicht gesetzt, wenn Overleaf über reines HTTP bereitgestellt wird. Browser verwerfen sichere Cookies bei HTTP. Jeder Wert aktiviert die Option, auch false, entfernen Sie die Zeile daher stattdessen.
Invalid authorization request state bedeutet, dass eine neuere Anmeldung den gespeicherten Wert ersetzt hat, zum Beispiel nach einer gleichzeitigen Anmeldung aus zwei Tabs oder wenn während der Anmeldung im Browser zurückgegangen wurde. Schließen Sie die anderen Tabs und starten Sie die Anmeldung erneut über die Overleaf-Anmeldeseite.
Zuletzt geändert am 2. November 2026