Přejít na hlavní obsah
Tuto funkci vyvíjí yu-i-i/overleaf-cep. Zde nabízíme dokumentaci pro vaši konfiguraci.

Konfigurace

Modul OIDC v Overleaf interně používá knihovnu passport-openidconnect. Pokud máte potíže s konfigurací OpenID Connect, vyplatí se přečíst si README knihovny passport-openidconnect, abyste získali představu o konfiguraci, kterou očekává. K zapnutí ověřovacího modulu OIDC je vyžadována proměnná prostředí EXTERNAL_AUTH. Tato proměnná prostředí určuje, které externí metody ověřování jsou aktivovány. Hodnotou této proměnné je seznam. Pokud seznam obsahuje oidc, bude aktivováno ověřování OIDC. Například: EXTERNAL_AUTH=ldap oidc Při použití metody ověřování OIDC je uživatel přesměrován na ověřovací stránku poskytovatele identity (IdP). Pokud IdP uživatele úspěšně ověří, v databázi uživatelů Overleaf se vyhledá záznam obsahující pole thirdPartyIdentifiers s následující strukturou:
externalUserId se musí shodovat s ID uživatele v profilu vráceném serverem IdP (viz proměnná prostředí OVERLEAF_OIDC_USER_ID_FIELD) a providerId se musí shodovat s ID poskytovatele OIDC (viz OVERLEAF_OIDC_PROVIDER_ID). Pokud není nalezen žádný odpovídající záznam, v databázi se vyhledá uživatel, jehož primární e-mailová adresa odpovídá e-mailu v uživatelském profilu IdP:
  • Pokud je takový uživatel nalezen, pole thirdPartyIdentifiers se aktualizuje.
  • Pokud není nalezen žádný odpovídající uživatel a vytváření účtů JIT není vypnuto, vytvoří se nový uživatel s e-mailovou adresou a thirdPartyIdentifiers z profilu IdP.
V obou případech se říká, že uživatel je „propojen“ s externím uživatelem OIDC. Propojení uživatele s poskytovatelem OIDC lze zrušit na stránce /user/settings.

Zjištění hodnot pomocí discovery dokumentu

Každý poskytovatel OpenID (OP) zveřejňuje discovery dokument na adrese <issuer>/.well-known/openid-configuration. Hodnoty z něj zkopírujte, místo abyste je psali ručně; k selhání přihlášení stačí jediný chybný znak.
1

Najděte discovery URL

Váš OP ji zobrazuje na stránce klienta (poskytovatele), kterého jste pro Overleaf vytvořili. V Authentiku otevřete Applications > Providers, vyberte poskytovatele a vyhledejte OpenID Configuration URL a OpenID Configuration Issuer:

Authentik: discovery URL a issuer poskytovatele (testovací instance)

URL obvykle vypadá takto:
  • 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

Přečtěte hodnoty

Otevřete URL v prohlížeči, nebo na serveru Overleaf spusťte:
Odpověď Authentiku vypadá takto:
Authentik tyto URL uvádí také níže na stránce poskytovatele:

Authentik: endpointy poskytovatele (testovací instance)

3

Zkopírujte je do variables.env

4

Ověřte, že Overleaf dosáhne na OP

Overleaf volá endpointy token a userinfo zevnitř svého kontejneru, takže OP musí být dostupný odtud, nejen z vašeho prohlížeče:
Mělo by se vypsat 200.
Zkopírujte issuer přesně, včetně koncového lomítka. Overleaf jej porovnává znak po znaku s issuerem v ID tokenu; jakýkoli rozdíl způsobí, že každé přihlášení přes OIDC selže s chybou:{"message":{"message":"ID token not issued by expected OpenID provider."}}V Authentiku issuer patří k aplikaci (.../application/o/<application-slug>/). Nejde o adresu serveru Authentik, přestože URL authorize, token a userinfo jsou sdílené všemi aplikacemi.

Proměnné prostředí

Hodnoty následujících pěti povinných proměnných zjistíte pomocí endpointu .well-known/openid-configuration vašeho poskytovatele OpenID (OP), viz výše.
  • OVERLEAF_OIDC_ISSUER (povinné)
  • OVERLEAF_OIDC_AUTHORIZATION_URL (povinné)
  • OVERLEAF_OIDC_TOKEN_URL (povinné)
  • OVERLEAF_OIDC_USER_INFO_URL (povinné)
  • OVERLEAF_OIDC_LOGOUT_URL (povinné)
Hodnoty následujících dvou povinných proměnných vám poskytne administrátor vašeho OP
  • OVERLEAF_OIDC_CLIENT_ID (povinné)
  • OVERLEAF_OIDC_CLIENT_SECRET (povinné)
  • OVERLEAF_OIDC_SCOPE
    • Výchozí: openid profile email
  • OVERLEAF_OIDC_PROVIDER_ID
    • Libovolné ID poskytovatele OP, výchozí hodnota je oidc.
  • OVERLEAF_OIDC_PROVIDER_NAME
    • Název OP, používaný v části Linked Accounts na stránce /user/settings, výchozí hodnota je OIDC Provider.
  • OVERLEAF_OIDC_IDENTITY_SERVICE_NAME
    • Zobrazovaný název služby identity, používaný na přihlašovací stránce (výchozí: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_DESCRIPTION
    • Popis OP, používaný v části Linked Accounts (výchozí: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_INFO_LINK
    • URL odkazu Learn more v popisu OP; ve výchozím nastavení popis neobsahuje odkaz Learn more.
  • OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
    • Nezobrazovat OP na stránce /user/settings, pokud účet uživatele není s OP propojen; výchozí hodnota false.
  • OVERLEAF_OIDC_USER_ID_FIELD
    • Hodnotu tohoto atributu použije Overleaf jako externí ID uživatele; výchozí hodnota je id. Další možné rozumné hodnoty jsou email a username (odpovídá OIDC claimu preferred_username).
  • OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS
    • Omezuje vytváření účtů Just-in-Time (JIT) pro uživatele ověřované přes OIDC. Pokud je nastavena na seznam doménových jmen oddělených čárkami, nový účet se vytvoří pouze tehdy, když doména e-mailové adresy uživatele odpovídá některé z uvedených domén. Pokud doména neodpovídá, musí administrátor vytvořit uživatelský účet ručně s použitím e-mailové adresy uživatele OIDC, buď se silným náhodným heslem, nebo nejlépe zcela bez pole hashedPassword. Doménová jména mohou obsahovat úvodní zástupný znak *., který odpovídá subdoménám.
      • Příklad: Povolení vytváření účtů JIT pro uživatele s e-mailovými adresami jako name@example.com a name@math.example.com:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com
      • Příklad: Úplné vypnutí vytváření účtů JIT:
        OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=
  • OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN
    • Pokud je nastaveno na true, při přihlášení se aktualizují pole uživatele first_name a last_name a formulář s údaji o uživateli na stránce /user/settings se vypne.
  • OVERLEAF_OIDC_IS_ADMIN_FIELD a OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE
    • Pokud jsou nastaveny obě proměnné prostředí, proces přihlášení nastaví user.isAdmin = true, pokud profil vrácený OP obsahuje atribut určený proměnnou OVERLEAF_OIDC_IS_ADMIN_FIELD a jeho hodnota buď odpovídá OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE, nebo je polem obsahujícím OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE (například claim groups); v opačném případě se user.isAdmin nastaví na false. Pokud je OVERLEAF_OIDC_IS_ADMIN_FIELD rovno email, pro kontrolu shody se použije hodnota atributu emails[0].value.
URL pro přesměrování pro vašeho poskytovatele OpenID je https://my-overleaf-instance.com/oidc/login/callback.
variables.env

Postup krok za krokem: goauthentik

Tento návod popisuje nastavení otestované s goauthentik. Nahraďte https://overleaf.example.com svou hodnotou OVERLEAF_SITE_URL a https://authentik.example.com adresou svého Authentiku.
1

Vytvořte poskytovatele

V Authentiku otevřete Applications > Providers, klikněte na New Provider, zvolte OAuth2/OpenID Provider a klikněte na Next.
  • Client Type: Confidential.
  • Redirect URIs (v části Protocol settings): přidejte https://overleaf.example.com/oidc/login/callback s režimem shody Strict.
  • Hned teď zkopírujte Client ID a Client Secret do OVERLEAF_OIDC_CLIENT_ID a OVERLEAF_OIDC_CLIENT_SECRET.

Authentik: Client ID a Client Secret nového poskytovatele

Authentik zobrazuje client secret pouze při vytváření poskytovatele. Formulář pro úpravy později nabízí jen Modify, které secret nahradí novým.
2

Vytvořte aplikaci

Otevřete Applications > Applications, vytvořte novou aplikaci, zadejte její název a slug, například overleaf, a vyberte poskytovatele. Slug se stane součástí issueru: https://authentik.example.com/application/o/overleaf/.
3

Zkopírujte URL

Pět URL vyplňte podle části Zjištění hodnot pomocí discovery dokumentu výše.
4

Namapujte administrátory (volitelné)

Authentik posílá skupiny uživatele v claimu groups jako pole. Chcete-li, aby se členové skupiny Authentiku Admins stali administrátory Overleafu:
Příznak administrátora se aktualizuje při každém přihlášení přes OIDC. Při chybném poli nebo hodnotě přijde každý administrátor, který se přihlásí přes OIDC, o administrátorská práva, včetně administrátora vytvořeného v launchpadu. Mapování nejprve otestujte s druhým administrátorským účtem.
variables.env

Otázky a odpovědi

Odpověď: Zkontrolujte následující:
  • Verze. Před verzí v6.3.0 Overleaf nečetl vlastní nároky (claims), jako je groups, takže fungovalo pouze OVERLEAF_OIDC_IS_ADMIN_FIELD=email. Aktualizujte na verzi v6.3.0 nebo novější.
  • Nárok musí být v odpovědi UserInfo. Overleaf čte nárok z OVERLEAF_OIDC_USER_INFO_URL, nikoli z ID tokenu. Pokud váš OP přidává nárok pouze do ID tokenu, přidejte jej také do UserInfo, například volbou Add to userinfo u mapperu v Keycloaku.
  • Hodnota se musí přesně shodovat, včetně velikosti písmen, například Admins.
Stav administrátora se kontroluje znovu při každém přihlášení: uživatel, který byl administrátorem jmenován v administraci, o tento stav při dalším přihlášení přijde, pokud nárok neodpovídá.
Odpověď: Ne. GitHub podporuje OAuth 2.0, ale nikoli OpenID Connect pro přihlašování uživatelů: nevrací ID token, který Overleaf vyžaduje, takže přihlášení selže s chybou ID token not present in token response.Chcete-li uživatelům umožnit přihlášení účtem GitHub, použijte poskytovatele identity, jako je goauthentik nebo Keycloak, s GitHubem jako zdrojem přihlášení, a Overleaf k tomuto poskytovateli připojte přes OIDC.
Odpověď: Ano. GitLab, včetně self-managed GitLabu, je poskytovatelem OpenID Connect. V GitLabu vytvořte aplikaci v části Applications (v nastavení svého uživatele, skupiny nebo oblasti Admin) s těmito údaji:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile a email
Poté načtěte endpointy z https://gitlab.com/.well-known/openid-configuration nebo ze stejné cesty na vašem GitLabu, jak je popsáno v části Zjištění hodnot pomocí discovery dokumentu. Pro gitlab.com je issuer https://gitlab.com, bez koncového lomítka.
Odpověď: Před přesměrováním na OP uloží Overleaf do relace uživatele náhodnou hodnotu state a zkontroluje ji, když OP přesměruje zpět. Tyto chyby znamenají, že relace při callbacku není ta, která přihlášení zahájila.Unable to verify authorization request state znamená, že prohlížeč při callbacku neposlal zpět cookie relace. Zkontrolujte, že:
  • Uživatelé otevírají Overleaf na adrese z OVERLEAF_SITE_URL. Callback vždy směřuje na OVERLEAF_SITE_URL, takže přihlášení zahájené z jiné adresy, například http://192.168.1.20, zatímco OVERLEAF_SITE_URL je https://overleaf.example.com, svou relaci ztratí.
  • OVERLEAF_SECURE_COOKIE není nastaveno, když je Overleaf poskytován přes čisté HTTP. Prohlížeče zabezpečené cookies na HTTP zahazují. Zapne ji jakákoli hodnota, včetně false, proto řádek raději odstraňte.
Invalid authorization request state znamená, že uloženou hodnotu nahradilo novější přihlášení, například po přihlášení ze dvou záložek současně nebo po návratu zpět v prohlížeči během přihlašování. Zavřete ostatní záložky a zahajte přihlášení znovu z přihlašovací stránky Overleafu.
Naposledy změněno 2. listopadu 2026