Uwierzytelnianie OIDC

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:

thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]

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:

   curl -s https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration \
     | jq '{issuer, authorization_endpoint, token_endpoint, userinfo_endpoint, end_session_endpoint}'
   

   Odpowiedź Authentik wygląda tak:

   {
     "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 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

   Pole w dokumencie discovery	Zmienna środowiskowa
   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

   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/
   
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:

   docker exec sharelatex curl -sS -o /dev/null -w "%{http_code}\n" \
     https://authentik.example.com/application/o/overleaf/.well-known/openid-configuration
   

   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 [e-mail] i [e-mail]:
      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.

Przykładowy plik variables.env

variables.env

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=[e-mail]

OVERLEAF_LEFT_FOOTER=[{"text": "Contact your support team", "url": "mailto:[e-mail]"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Hello, I am on the Right", "url":"https://github.com/yu-i-i/overleaf-cep"}]

OVERLEAF_EMAIL_FROM_ADDRESS=[e-mail]
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=[e-mail]
OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false

​

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:

   OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
   OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
   

   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.

Przetestowany plik variables.env dla goauthentik

variables.env

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