> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Ověřování OIDC

<Info>
  Tuto funkci vyvíjí [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Zde nabízíme dokumentaci pro vaši konfiguraci.
</Info>

### Konfigurace

Modul OIDC v Overleaf interně používá knihovnu [passport-openidconnect](https://github.com/jaredhanson/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:

```text theme={null}
thirdPartyIdentifiers: [
  {
    externalUserId: "...",
    externalData: null,
    providerId: "..."
  }
]
```

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

<Steps>
  <Step title="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**:

    <Frame caption="Authentik: discovery URL a issuer poskytovatele (testovací instance)">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-provider.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=e3cb5603d959665472b53e39b58b2775" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-provider.png" />
    </Frame>

    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`
  </Step>

  <Step title="Přečtěte hodnoty">
    Otevřete URL v prohlížeči, nebo na serveru Overleaf spusťte:

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

    Odpověď Authentiku vypadá takto:

    ```json theme={null}
    {
      "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 tyto URL uvádí také níže na stránce poskytovatele:

    <Frame caption="Authentik: endpointy poskytovatele (testovací instance)">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-endpoints.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=55d130cbbbf27fd11aebafa1ab3f090c" alt="" width="1280" height="633" data-path="images/on-premises/oidc-authentik-endpoints.png" />
    </Frame>
  </Step>

  <Step title="Zkopírujte je do `variables.env`">
    | Pole v discovery dokumentu | Proměnná prostředí |
    | - | - |
    | `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` |

    ```dotenv theme={null}
    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/
    ```
  </Step>

  <Step title="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:

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

    Mělo by se vypsat `200`.
  </Step>
</Steps>

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

#### 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` <strong>(povinné)</strong>
* `OVERLEAF_OIDC_AUTHORIZATION_URL` <strong>(povinné)</strong>
* `OVERLEAF_OIDC_TOKEN_URL` <strong>(povinné)</strong>
* `OVERLEAF_OIDC_USER_INFO_URL` <strong>(povinné)</strong>
* `OVERLEAF_OIDC_LOGOUT_URL` <strong>(povinné)</strong>

Hodnoty následujících dvou povinných proměnných vám poskytne administrátor vašeho OP

* `OVERLEAF_OIDC_CLIENT_ID` <strong>(povinné)</strong>
* `OVERLEAF_OIDC_CLIENT_SECRET` <strong>(povinné)</strong>
* `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`.

<Accordion title="Ukázkový soubor variables.env">
  ```dotenv title="variables.env" wrap theme={null}
  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=support@example.com

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

  OVERLEAF_EMAIL_FROM_ADDRESS=team@example.com
  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=overleaf.admin@example.com
  OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN=false
  ```
</Accordion>

## Postup krok za krokem: goauthentik

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

<Steps>
  <Step title="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`.

    <Frame caption="Authentik: Client ID a Client Secret nového poskytovatele">
      <img src="https://mintcdn.com/ayakaleaf-pro/TjqwH4XzxYAkHStq/images/on-premises/oidc-authentik-create.png?fit=max&auto=format&n=TjqwH4XzxYAkHStq&q=85&s=f127a92eaf3063714e9af515fe97c263" alt="" width="1120" height="808" data-path="images/on-premises/oidc-authentik-create.png" />
    </Frame>

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

  <Step title="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/`.
  </Step>

  <Step title="Zkopírujte URL">
    Pět URL vyplňte podle části [Zjištění hodnot pomocí discovery dokumentu](#zjištění-hodnot-pomocí-discovery-dokumentu) výše.
  </Step>

  <Step title="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:

    ```dotenv theme={null}
    OVERLEAF_OIDC_IS_ADMIN_FIELD=groups
    OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE=Admins
    ```

    <Warning>
      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.
    </Warning>
  </Step>
</Steps>

<Accordion title="Otestovaný soubor variables.env pro goauthentik">
  ```dotenv title="variables.env" wrap theme={null}
  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
  ```
</Accordion>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.