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

# Uwierzytelnianie OIDC

<Info>
  Ta funkcja została opracowana przez [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Poniżej udostępniamy dokumentację, która pomoże Ci ją skonfigurować.
</Info>

### Konfiguracja

Wewnętrznie moduł OIDC Overleaf korzysta z biblioteki [passport-openidconnect](https://github.com/jaredhanson/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:

```text theme={null}
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ć.

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

    <Frame caption="Authentik: adres URL discovery i wystawca dostawcy (instancja testowa)">
      <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>

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

  <Step title="Odczytaj wartości">
    Otwórz adres URL w przeglądarce lub uruchom na serwerze Overleaf:

    ```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}'
    ```

    Odpowiedź Authentik wygląda tak:

    ```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 wyświetla te adresy URL również niżej na stronie dostawcy:

    <Frame caption="Authentik: punkty końcowe dostawcy (instancja testowa)">
      <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="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` |

    ```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="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:

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

    Polecenie powinno wypisać `200`.
  </Step>
</Steps>

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

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

Wartości poniższych dwóch wymaganych zmiennych przekaże Ci administrator Twojego OP

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

<Accordion title="Przykładowy plik 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>

## Krok po kroku: goauthentik

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

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

    <Frame caption="Authentik: Client ID i Client Secret nowego dostawcy">
      <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 wyświetla sekret klienta tylko podczas tworzenia dostawcy. Później formularz edycji oferuje jedynie opcję **Modify**, która zastępuje sekret nowym.
    </Warning>
  </Step>

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

  <Step title="Skopiuj adresy URL">
    Postępuj zgodnie z sekcją [Znajdowanie wartości za pomocą dokumentu discovery](#znajdowanie-wartości-za-pomocą-dokumentu-discovery) powyżej, aby uzupełnić pięć adresów URL.
  </Step>

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

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

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

<Accordion title="Przetestowany plik variables.env dla 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.