Skip to main content
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ł SAML Overleaf korzysta z biblioteki passport-saml; większość poniższych opcji konfiguracyjnych jest przekazywana do passport-saml. Jeśli masz problemy z konfiguracją SAML, warto przeczytać README biblioteki passport-saml, aby zorientować się, jakiej konfiguracji oczekuje. Do włączenia modułu uwierzytelniania SAML 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 saml, uwierzytelnianie SAML zostanie włączone. Na przykład: EXTERNAL_AUTH=ldap saml Przy metodzie uwierzytelniania SAML 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 samlIdentifiers o następującej strukturze:
Wartość externalUserId musi odpowiadać wartości właściwości określonej przez userIdAttribute w profilu użytkownika zwróconym przez serwer IdP. 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 hashedPassword jest usuwane, aby wyłączyć uwierzytelnianie lokalne, i dodawane jest pole samlIdentifiers.
  • Jeśli nie zostanie znaleziony pasujący użytkownik, tworzony jest nowy użytkownik z adresem e-mail i samlIdentifiers z profilu IdP.
Uwaga: obecnie obsługiwany jest tylko jeden IdP SAML. Pole providerId w samlIdentifiers ma stałą wartość '1'.

​
Zmienne środowiskowe

  • OVERLEAF_SAML_IDENTITY_SERVICE_NAME
    • Wyświetlana nazwa usługi tożsamości, używana na stronie logowania (domyślnie: Log in with SAML IdP).
  • OVERLEAF_SAML_USER_ID_FIELD
    • Wartość tego atrybutu będzie używana przez Overleaf jako zewnętrzny identyfikator użytkownika; domyślnie nameID.
  • OVERLEAF_SAML_EMAIL_FIELD
    • Nazwa pola adresu e-mail w profilu użytkownika; domyślnie nameID.
  • OVERLEAF_SAML_FIRST_NAME_FIELD
    • Nazwa pola firstName w profilu użytkownika; domyślnie givenName.
  • OVERLEAF_SAML_LAST_NAME_FIELD
    • Nazwa pola lastName w profilu użytkownika; domyślnie lastName
  • OVERLEAF_SAML_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_SAML_ENTRYPOINT (wymagana)
    • Adres URL punktu wejścia usługi tożsamości SAML.
      • Przykład: https://idp.example.com/simplesaml/saml2/idp/SSOService.php
      • Przykład dla Azure: https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2
  • OVERLEAF_SAML_ISSUER (wymagana)
    • Nazwa wystawcy (Issuer).
  • OVERLEAF_SAML_AUDIENCE
    • Oczekiwana wartość Audience w odpowiedzi SAML; domyślnie wartość OVERLEAF_SAML_ISSUER.
  • OVERLEAF_SAML_IDP_CERT (wymagana)
    • Ścieżka do pliku zawierającego publiczny certyfikat dostawcy tożsamości, używany do weryfikacji podpisów przychodzących odpowiedzi SAML. Jeśli dostawca tożsamości ma kilka ważnych certyfikatów podpisujących, może to być tablica JSON ze ścieżkami do certyfikatów.
      • Przykład (jeden certyfikat): /var/lib/overleaf/certs/idp_cert.pem
      • Przykład (wiele certyfikatów): ["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]
  • OVERLEAF_SAML_PUBLIC_CERT
    • Ścieżka do pliku zawierającego publiczny certyfikat podpisujący, osadzany w żądaniach uwierzytelniania, aby IdP mógł weryfikować podpisy przychodzących żądań SAML. Jest wymagany przy konfigurowaniu punktu końcowego metadanych, gdy strategia jest skonfigurowana z OVERLEAF_SAML_PRIVATE_KEY. Aby obsłużyć rotację certyfikatów, można podać tablicę JSON ze ścieżkami do certyfikatów. W takim przypadku pierwszy element tablicy powinien odpowiadać bieżącemu OVERLEAF_SAML_PRIVATE_KEY. Dodatkowe elementy tablicy mogą służyć do publikowania przyszłych certyfikatów dla IdP przed zmianą OVERLEAF_SAML_PRIVATE_KEY.
  • OVERLEAF_SAML_PRIVATE_KEY
    • Ścieżka do pliku zawierającego klucz prywatny w formacie PEM, odpowiadający OVERLEAF_SAML_PUBLIC_CERT, używany do podpisywania żądań uwierzytelniania wysyłanych przez passport-saml.
  • OVERLEAF_SAML_DECRYPTION_CERT
  • OVERLEAF_SAML_DECRYPTION_PVK
    • Ścieżka do pliku zawierającego klucz prywatny odpowiadający OVERLEAF_SAML_DECRYPTION_CERT, który będzie używany do próby odszyfrowania wszystkich otrzymanych zaszyfrowanych asercji.
  • OVERLEAF_SAML_SIGNATURE_ALGORITHM
    • Opcjonalnie ustawia algorytm podpisu dla podpisywania żądań; prawidłowe wartości to ‘sha1’ (domyślna), ‘sha256’ (zalecana), ‘sha512’ (najbezpieczniejsza, sprawdź, czy Twój IdP ją obsługuje).
  • OVERLEAF_SAML_ADDITIONAL_PARAMS
    • Słownik JSON z dodatkowymi parametrami zapytania dodawanymi do wszystkich żądań.
  • OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS
    • Słownik JSON z dodatkowymi parametrami zapytania dodawanymi do żądań ‘authorize’.
      • Przykład: {"some_key": "some_value"}
  • OVERLEAF_SAML_IDENTIFIER_FORMAT
    • Format identyfikatora nazwy, o który należy poprosić dostawcę tożsamości (domyślnie: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress). W przypadku użycia urn:oasis:names:tc:SAML:2.0:nameid-format:persistent upewnij się, że zdefiniowano zmienną środowiskową OVERLEAF_SAML_EMAIL_FIELD. Jeśli wymagany jest urn:oasis:names:tc:SAML:2.0:nameid-format:transient, musisz także zdefiniować zmienną środowiskową OVERLEAF_SAML_USER_ID_FIELD, którą można na przykład ustawić na adres e-mail użytkownika.
  • OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
    • Akceptowalna różnica czasu (w milisekundach) między klientem a serwerem podczas sprawdzania znaczników czasu warunków ważności asercji OnBefore i NotOnOrAfter. Ustawienie -1 całkowicie wyłącza sprawdzanie tych warunków. Domyślnie 0.
  • OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
    • Atrybut AttributeConsumingServiceIndex dodawany do AuthnRequest, aby wskazać IdP, który zestaw atrybutów dołączyć do odpowiedzi (link).
  • OVERLEAF_SAML_AUTHN_CONTEXT
    • Tablica JSON wartości formatu identyfikatora nazwy dla żądanego kontekstu uwierzytelniania. Domyślnie: ["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"].
  • OVERLEAF_SAML_FORCE_AUTHN
    • Jeśli true, początkowe żądanie SAML od dostawcy usług określa, że IdP powinien wymusić ponowne uwierzytelnienie użytkownika, nawet jeśli ma on ważną sesję.
  • OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT
    • Jeśli true, nie jest żądany określony kontekst uwierzytelniania. Możesz na przykład ustawić tę wartość na true, aby zezwolić na dodatkowe konteksty, takie jak logowanie bez hasła (urn:oasis:names:tc:SAML:2.0:ac:classes:X509). Obsługa dodatkowych kontekstów zależy od Twojego IdP.
  • OVERLEAF_SAML_AUTHN_REQUEST_BINDING
    • Jeśli ustawiono na HTTP-POST, uwierzytelnianie jest żądane od IdP za pomocą powiązania HTTP POST; w przeciwnym razie domyślnie używane jest HTTP-Redirect.
  • OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO
    • Jeśli always, InResponseTo będzie weryfikowane w przychodzących odpowiedziach SAML.
    • Jeśli never, InResponseTo nie będzie weryfikowane (domyślnie).
    • Jeśli ifPresent, InResponseTo będzie weryfikowane tylko wtedy, gdy występuje w przychodzącej odpowiedzi SAML.
  • OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED i OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED
    • Gdy ustawiono na true (domyślnie), Overleaf oczekuje, że odpowiednio asercje SAML lub cała odpowiedź uwierzytelniania SAML będą podpisane przez IdP. Gdy obie opcje mają wartość false, podpisana musi być co najmniej jedna z asercji lub odpowiedź.
  • OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS
    • Określa czas wygaśnięcia, po którym identyfikator żądania wygenerowany dla żądania SAML nie będzie ważny, jeśli pojawi się w polu InResponseTo odpowiedzi SAML. Domyślnie: 28800000 (8 godzin).
  • OVERLEAF_SAML_LOGOUT_URL
    • Adres bazowy, pod który wysyłane są żądania wylogowania (domyślnie: entryPoint).
      • Przykład: https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php
  • OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS
    • Słownik JSON z dodatkowymi parametrami zapytania dodawanymi do żądań ‘logout’.
  • OVERLEAF_SAML_IS_ADMIN_FIELD i OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE
    • Gdy obie zmienne środowiskowe są ustawione, proces logowania ustawia user.isAdmin = true, jeśli profil zwrócony przez IdP SAML zawiera atrybut określony przez OVERLEAF_SAML_IS_ADMIN_FIELD, a jego wartość odpowiada OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE lub jest tablicą zawierającą OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE; w przeciwnym razie user.isAdmin jest ustawiane na false. Jeśli którakolwiek z tych zmiennych nie jest ustawiona, status administratora jest ustawiany na true tylko podczas tworzenia użytkownika-administratora w Launchpad.
Metadane dla dostawcy tożsamości Bieżąca wersja Overleaf CE zawiera punkt końcowy do pobierania metadanych dostawcy usług (Service Provider): http://my-overleaf-instance.com/saml/meta Dostawcę tożsamości należy skonfigurować tak, aby rozpoznawał serwer Overleaf jako „dostawcę usług” (Service Provider). Instrukcje, jak to zrobić, znajdziesz w dokumentacji swojego serwera SAML. Poniżej znajduje się przykład odpowiednich metadanych dostawcy usług:
Zwróć uwagę na certyfikaty, AssertionConsumerService.Location, SingleLogoutService.Location oraz EntityDescriptor.entityID i ustaw je odpowiednio w konfiguracji IdP albo wyślij plik metadanych administratorowi IdP.

​
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ę i aplikację

W Authentik otwórz Applications > Applications i kliknij New Application. Kreator tworzy aplikację wraz z jej dostawcą.1. Nadaj aplikacji nazwę i slug, na przykład overleaf, i kliknij Next:

Authentik: nazwa i slug aplikacji

2. Wybierz SAML Provider i kliknij Next:

Authentik: wybór dostawcy SAML

3. Wypełnij dane dostawcy:
  • Authorization Flow: default-provider-authorization-implicit-consent
  • ACS URL: https://overleaf.example.com/saml/login/callback
  • Audience: nazwa dla Overleaf, na przykład overleaf. Overleaf wysyła ją jako OVERLEAF_SAML_ISSUER.

Authentik: dostawca SAML aplikacji

4. Otwórz Advanced protocol settings i ustaw:
  • Signing Certificate: certyfikat, na przykład authentik Self-signed Certificate
  • Sign assertions i Sign responses: oba włączone
  • Service Provider Binding: Post

Authentik: podpisywanie i powiązanie przetestowanego dostawcy (instancja testowa)

5. Klikaj Next aż do ostatniej strony i zatwierdź aplikację.
2

Skopiuj wartości ze strony dostawcy

Ponownie otwórz dostawcę. Wszystko, czego potrzebuje Overleaf, znajduje się w jego przeglądzie:

Authentik: przegląd dostawcy SAML (instancja testowa)

EntityID/Issuer w sekcji SAML Configuration to nazwa samego Authentik. Nie wpisuj jej do OVERLEAF_SAML_ISSUER; użyj wartości Audience.
3

Zainstaluj certyfikat podpisujący

Kliknij Download pod Download signing certificate i zapisz plik jako data/overleaf/certs/idp_cert.pem w katalogu Toolkit. Kontener widzi go jako /var/lib/overleaf/certs/idp_cert.pem:
4

Zmapuj atrybuty

Authentik wysyła swoje atrybuty pod następującymi nazwami:
Grupy są przesyłane jako http://schemas.xmlsoap.org/claims/Group, czyli lista. Aby członkowie grupy Authentik Admins stali się administratorami Overleaf:
Flaga administratora jest aktualizowana przy każdym logowaniu SAML. Przy błędnym polu lub wartości każdy administrator logujący się przez SAML traci uprawnienia administratora. Najpierw przetestuj mapowanie na drugim koncie administratora.
variables.env
Ostatnia modyfikacja 6 października 2026