Przejdź do głównej treści
Ta funkcja została opracowana przez yu-i-i/overleaf-cep. Poniżej udostępniamy dokumentację, która pomoże Ci ją skonfigurować.

Konfiguracja

Wewnętrznie moduł OIDC Overleaf korzysta z biblioteki passport-openidconnect. Jeśli masz problemy z konfiguracją OpenID Connect, warto przeczytać README biblioteki passport-openidconnect, aby zorientować się, jakiej konfiguracji oczekuje. Do włączenia modułu uwierzytelniania OIDC wymagana jest zmienna środowiskowa EXTERNAL_AUTH. Określa ona, które zewnętrzne metody uwierzytelniania są aktywne. Wartością tej zmiennej jest lista. Jeśli lista zawiera oidc, uwierzytelnianie OIDC zostanie włączone. Na przykład: EXTERNAL_AUTH=ldap oidc Przy metodzie uwierzytelniania OIDC użytkownik jest przekierowywany na stronę uwierzytelniania dostawcy tożsamości (IdP). Jeśli IdP pomyślnie uwierzytelni użytkownika, w bazie użytkowników Overleaf wyszukiwany jest rekord zawierający pole thirdPartyIdentifiers o następującej strukturze:
Wartość externalUserId musi odpowiadać identyfikatorowi użytkownika w profilu zwróconym przez serwer IdP (patrz zmienna środowiskowa OVERLEAF_OIDC_USER_ID_FIELD), a providerId musi odpowiadać identyfikatorowi dostawcy OIDC (patrz OVERLEAF_OIDC_PROVIDER_ID). Jeśli nie zostanie znaleziony pasujący rekord, w bazie danych wyszukiwany jest użytkownik, którego główny adres e-mail odpowiada adresowi e-mail w profilu użytkownika IdP:
  • Jeśli taki użytkownik zostanie znaleziony, pole thirdPartyIdentifiers zostanie zaktualizowane.
  • Jeśli nie zostanie znaleziony pasujący użytkownik, a tworzenie kont JIT nie jest wyłączone, tworzony jest nowy użytkownik z adresem e-mail i thirdPartyIdentifiers z profilu IdP.
W obu przypadkach mówi się, że użytkownik jest „powiązany” z zewnętrznym użytkownikiem OIDC. Powiązanie z dostawcą OIDC można usunąć na stronie /user/settings.

Znajdowanie wartości za pomocą dokumentu discovery

Każdy dostawca OpenID (OP) publikuje dokument discovery pod adresem <issuer>/.well-known/openid-configuration. Skopiuj wartości z niego, zamiast wpisywać je ręcznie; wystarczy jeden błędny znak, aby logowanie przestało działać.
1

Znajdź adres URL discovery

Twój OP wyświetla go na stronie klienta (dostawcy) utworzonego dla Overleaf. W Authentik otwórz Applications > Providers, wybierz dostawcę i znajdź OpenID Configuration URL oraz OpenID Configuration Issuer:

Authentik: adres URL discovery i wystawca dostawcy (instancja testowa)

Adres URL zwykle wygląda tak:
  • 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

Odczytaj wartości

Otwórz adres URL w przeglądarce lub uruchom na serwerze Overleaf:
Odpowiedź Authentik wygląda tak:
Authentik wyświetla te adresy URL również niżej na stronie dostawcy:

Authentik: punkty końcowe dostawcy (instancja testowa)

3

Skopiuj je do variables.env

4

Sprawdź, czy Overleaf może połączyć się z OP

Overleaf wywołuje punkty końcowe token i userinfo z wnętrza swojego kontenera, więc OP musi być osiągalny stamtąd, a nie tylko z Twojej przeglądarki:
Polecenie powinno wypisać 200.
Skopiuj issuer dokładnie, łącznie z końcowym ukośnikiem. Overleaf porównuje go znak po znaku z wystawcą w tokenie ID; każda różnica sprawia, że każde logowanie OIDC kończy się błędem:{"message":{"message":"ID token not issued by expected OpenID provider."}}W Authentik wystawca należy do aplikacji (.../application/o/<application-slug>/). Nie jest to adres serwera Authentik, mimo że adresy URL authorize, token i userinfo są wspólne dla wszystkich aplikacji.

Zmienne środowiskowe

Wartości poniższych pięciu wymaganych zmiennych można znaleźć za pomocą punktu końcowego .well-known/openid-configuration Twojego dostawcy OpenID (OP), patrz wyżej.
  • OVERLEAF_OIDC_ISSUER (wymagana)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (wymagana)
  • OVERLEAF_OIDC_TOKEN_URL (wymagana)
  • OVERLEAF_OIDC_USER_INFO_URL (wymagana)
  • OVERLEAF_OIDC_LOGOUT_URL (wymagana)
Wartości poniższych dwóch wymaganych zmiennych przekaże Ci administrator Twojego OP
  • OVERLEAF_OIDC_CLIENT_ID (wymagana)
  • OVERLEAF_OIDC_CLIENT_SECRET (wymagana)
  • OVERLEAF_OIDC_SCOPE
    • Domyślnie: openid profile email
  • OVERLEAF_OIDC_PROVIDER_ID
    • Dowolny identyfikator OP, domyślnie oidc.
  • OVERLEAF_OIDC_PROVIDER_NAME
    • Nazwa OP używana w sekcji Linked Accounts na stronie /user/settings, domyślnie OIDC Provider.
  • OVERLEAF_OIDC_IDENTITY_SERVICE_NAME
    • Wyświetlana nazwa usługi tożsamości, używana na stronie logowania (domyślnie: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_DESCRIPTION
    • Opis OP używany w sekcji Linked Accounts (domyślnie: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_INFO_LINK
    • Adres URL Learn more w opisie OP; domyślnie opis nie zawiera linku Learn more.
  • OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
    • Nie pokazuje OP na stronie /user/settings, jeśli konto użytkownika nie jest z nim powiązane; domyślnie false.
  • OVERLEAF_OIDC_USER_ID_FIELD
    • Wartość tego atrybutu będzie używana przez Overleaf jako zewnętrzny identyfikator użytkownika; domyślnie id. Inne sensowne wartości to email i username (odpowiadająca oświadczeniu OIDC preferred_username).
  • OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS
    • Ogranicza tworzenie kont Just-in-Time (JIT) dla użytkowników uwierzytelniających się przez OIDC. Jeśli ustawiono ją na listę nazw domen rozdzielonych przecinkami, nowe konto zostanie utworzone tylko wtedy, gdy domena adresu e-mail użytkownika pasuje do jednej z wymienionych domen. Jeśli domena nie pasuje, administrator musi ręcznie utworzyć konto użytkownika z adresem e-mail użytkownika OIDC, z silnym losowym hasłem lub, najlepiej, całkowicie bez pola hashedPassword. Nazwy domen mogą zawierać na początku symbol wieloznaczny *., aby obejmować subdomeny.
      • Przykład: aby zezwolić na tworzenie kont JIT dla użytkowników z adresami e-mail takimi jak name@example.com i name@math.example.com:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com
      • Przykład: aby całkowicie wyłączyć tworzenie kont JIT:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
  • OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN
    • Jeśli ustawiono na true, przy logowaniu aktualizowane są pola first_name i last_name użytkownika, a formularz danych użytkownika na stronie /user/settings zostaje wyłączony.
  • OVERLEAF_OIDC_IS_ADMIN_FIELD i OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE
    • Gdy obie zmienne środowiskowe są ustawione, proces logowania ustawia user.isAdmin = true, jeśli profil zwrócony przez OP zawiera atrybut określony przez OVERLEAF_OIDC_IS_ADMIN_FIELD, a jego wartość odpowiada OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE lub jest tablicą zawierającą OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE (na przykład oświadczenie groups); w przeciwnym razie user.isAdmin jest ustawiane na false. Jeśli OVERLEAF_OIDC_IS_ADMIN_FIELD ma wartość email, do sprawdzenia dopasowania używana jest wartość atrybutu emails[0].value.
Adres URL przekierowania dla Twojego dostawcy OpenID to https://my-overleaf-instance.com/oidc/login/callback.
variables.env

Krok po kroku: goauthentik

Poniżej opisano konfigurację przetestowaną z goauthentik. Zastąp https://overleaf.example.com swoim OVERLEAF_SITE_URL, a https://authentik.example.com adresem swojej instancji Authentik.
1

Utwórz dostawcę

W Authentik otwórz Applications > Providers, kliknij New Provider, wybierz OAuth2/OpenID Provider i kliknij Next.
  • Client Type: Confidential.
  • Redirect URIs (w sekcji Protocol settings): dodaj https://overleaf.example.com/oidc/login/callback z trybem dopasowania Strict.
  • Od razu skopiuj Client ID i Client Secret do OVERLEAF_OIDC_CLIENT_ID i OVERLEAF_OIDC_CLIENT_SECRET.

Authentik: Client ID i Client Secret nowego dostawcy

Authentik wyświetla sekret klienta tylko podczas tworzenia dostawcy. Później formularz edycji oferuje jedynie opcję Modify, która zastępuje sekret nowym.
2

Utwórz aplikację

Otwórz Applications > Applications, utwórz nową aplikację, nadaj jej nazwę i slug, na przykład overleaf, i wybierz dostawcę. Slug staje się częścią wystawcy: https://authentik.example.com/application/o/overleaf/.
3

Skopiuj adresy URL

Postępuj zgodnie z sekcją Znajdowanie wartości za pomocą dokumentu discovery powyżej, aby uzupełnić pięć adresów URL.
4

Zmapuj administratorów (opcjonalnie)

Authentik wysyła grupy użytkownika jako oświadczenie groups, które jest tablicą. Aby członkowie grupy Authentik Admins stali się administratorami Overleaf:
Flaga administratora jest aktualizowana przy każdym logowaniu OIDC. Przy błędnym polu lub wartości każdy administrator logujący się przez OIDC traci uprawnienia administratora, łącznie z administratorem utworzonym w launchpadzie. Najpierw przetestuj mapowanie na drugim koncie administratora.
variables.env

Pytania i odpowiedzi

Odpowiedź: Sprawdź następujące kwestie:
  • Wersja. Przed wersją v6.3.0 Overleaf nie odczytywał niestandardowych claimów, takich jak groups, więc działało tylko OVERLEAF_OIDC_IS_ADMIN_FIELD=email. Zaktualizuj do wersji v6.3.0 lub nowszej.
  • Claim musi znajdować się w odpowiedzi UserInfo. Overleaf odczytuje claim z OVERLEAF_OIDC_USER_INFO_URL, a nie z tokena ID. Jeśli Twój OP dodaje claim tylko do tokena ID, dodaj go również do UserInfo, na przykład za pomocą opcji Add to userinfo w mapperze Keycloak.
  • Wartość musi być dokładnie zgodna, łącznie z wielkością liter, na przykład Admins.
Status administratora jest sprawdzany ponownie przy każdym logowaniu: użytkownik, który został administratorem w panelu administratora, traci ten status przy następnym logowaniu, jeśli claim nie jest zgodny.
Odpowiedź: Nie. GitHub obsługuje OAuth 2.0, ale nie OpenID Connect do logowania użytkowników: nie zwraca tokena ID, którego wymaga Overleaf, więc logowanie kończy się błędem ID token not present in token response.Aby umożliwić użytkownikom logowanie kontem GitHub, użyj dostawcy tożsamości, takiego jak goauthentik lub Keycloak, z GitHub jako źródłem logowania, i połącz Overleaf z tym dostawcą przez OIDC.
Odpowiedź: Tak. GitLab, w tym samodzielnie zarządzany GitLab, jest dostawcą OpenID Connect. W GitLab utwórz aplikację w sekcji Applications (w ustawieniach użytkownika, grupy lub w obszarze Admin) z następującymi ustawieniami:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile i email
Następnie odczytaj endpointy z https://gitlab.com/.well-known/openid-configuration lub z tej samej ścieżki w Twoim GitLab, zgodnie z opisem w sekcji Znajdowanie wartości za pomocą dokumentu discovery. Dla gitlab.com wystawcą (issuer) jest https://gitlab.com, bez końcowego ukośnika.
Odpowiedź: Przed przekierowaniem do OP Overleaf zapisuje losową wartość state w sesji użytkownika i sprawdza ją, gdy OP przekierowuje z powrotem. Te błędy oznaczają, że sesja w momencie wywołania zwrotnego (callback) nie jest tą, która rozpoczęła logowanie.Unable to verify authorization request state oznacza, że przeglądarka nie odesłała pliku cookie sesji podczas wywołania zwrotnego. Sprawdź, czy:
  • Użytkownicy otwierają Overleaf pod adresem z OVERLEAF_SITE_URL. Wywołanie zwrotne zawsze trafia na OVERLEAF_SITE_URL, więc logowanie rozpoczęte z innego adresu, np. http://192.168.1.20, gdy OVERLEAF_SITE_URL to https://overleaf.example.com, traci swoją sesję.
  • OVERLEAF_SECURE_COOKIE nie jest ustawione, gdy Overleaf jest udostępniany przez zwykłe HTTP. Przeglądarki odrzucają bezpieczne pliki cookie przy HTTP. Każda wartość włącza tę opcję, w tym false, więc zamiast tego usuń całą linię.
Invalid authorization request state oznacza, że nowsze logowanie zastąpiło zapisaną wartość, na przykład po zalogowaniu z dwóch kart jednocześnie lub cofnięciu się w przeglądarce podczas logowania. Zamknij pozostałe karty i rozpocznij logowanie ponownie ze strony logowania Overleaf.
Ostatnia modyfikacja 2 listopada 2026