> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/uk/konfiguraciya/overleaf-toolkit/authentication/oidc-authentication.md).

# Автентифікація OIDC

Цю функцію розроблено [yu-i-i/overleaf-cep](https://github.com/yu-i-i/overleaf-cep). Тут ми пропонуємо деякі документи для вашої конфігурації.

### Конфігурація

Внутрішньо модуль OIDC Overleaf використовує [passport-openidconnect](https://github.com/jaredhanson/passport-openidconnect) бібліотеку. Якщо у вас виникають проблеми з налаштуванням OpenID Connect, варто прочитати README для `passport-openidconnect` щоб зрозуміти, яку конфігурацію він очікує.

Змінна середовища `EXTERNAL_AUTH` потрібне для ввімкнення модуля автентифікації OIDC. Ця змінна середовища визначає, які зовнішні методи автентифікації активовано. Значення цієї змінної — список. Якщо список містить `oidc` тоді автентифікацію OIDC буде активовано.

Наприклад: `EXTERNAL_AUTH=ldap oidc`

Під час використання методу автентифікації OIDC користувача перенаправляють на сайт автентифікації Identity Provider (IdP). Якщо IdP успішно автентифікує користувача, у базі даних користувачів Overleaf перевіряється запис, що містить `thirdPartyIdentifiers` поле, структуроване так:

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

Поле `externalUserId` має збігатися з ідентифікатором користувача в профілі, поверненому сервером IdP (див. `OVERLEAF_OIDC_USER_ID_FIELD` змінну середовища), а `providerId` має збігатися з ідентифікатором провайдера OIDC (див. `OVERLEAF_OIDC_PROVIDER_ID`).

Якщо відповідного запису не знайдено, у базі даних шукається користувач із основною адресою електронної пошти, що збігається з email у профілі користувача IdP:

* Якщо такого користувача знайдено, `thirdPartyIdentifiers` поле оновлюється.
* Якщо відповідного користувача не знайдено і створення облікового запису JIT не вимкнено, створюється новий користувач з адресою електронної пошти та `thirdPartyIdentifiers` з профілю IdP.

У обох випадках вважається, що користувач «пов’язаний» із зовнішнім користувачем OIDC. Відв’язати користувача від провайдера OIDC можна на `/user/settings` сторінці.

#### Змінні середовища

Значення таких п’яти обов’язкових змінних можна знайти за допомогою `.well-known/openid-configuration` кінцеву точку вашого OpenID Provider (OP).

* `OVERLEAF_OIDC_ISSUER` **(обов’язково)**
* `OVERLEAF_OIDC_AUTHORIZATION_URL` **(обов’язково)**
* `OVERLEAF_OIDC_TOKEN_URL` **(обов’язково)**
* `OVERLEAF_OIDC_USER_INFO_URL` **(обов’язково)**
* `OVERLEAF_OIDC_LOGOUT_URL` **(обов’язково)**

Значення таких двох обов’язкових змінних буде надано адміністратором вашого OP

* `OVERLEAF_OIDC_CLIENT_ID` **(обов’язково)**
* `OVERLEAF_OIDC_CLIENT_SECRET` **(обов’язково)**
* `OVERLEAF_OIDC_SCOPE`
  * За замовчуванням: `openid profile email`
* `OVERLEAF_OIDC_PROVIDER_ID`
  * Будь-який ідентифікатор OP, за замовчуванням `oidc`.
* `OVERLEAF_OIDC_PROVIDER_NAME`
  * Назва OP, що використовується на `Пов’язані облікові записи` розділ у `/user/settings` сторінці, за замовчуванням `Провайдер OIDC`.
* `OVERLEAF_OIDC_IDENTITY_SERVICE_NAME`
  * Відображувана назва служби ідентифікації, використовується на сторінці входу (за замовчуванням: `Увійти за допомогою $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_DESCRIPTION`
  * Опис OP, що використовується в `Пов’язані облікові записи` розділі (за замовчуванням: `Увійти за допомогою $OVERLEAF_OIDC_PROVIDER_NAME`).
* `OVERLEAF_OIDC_PROVIDER_INFO_LINK`
  * `Дізнатися більше` URL в описі OP, за замовчуванням: без посилання `Дізнатися більше` в описі.
* `OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED`
  * Не показувати OP на `/user/settings` сторінці, якщо обліковий запис користувача не пов’язано з OP, за замовчуванням `false`.
* `OVERLEAF_OIDC_USER_ID_FIELD`
  * Значення цього атрибута буде використано Overleaf як зовнішній ідентифікатор користувача, за замовчуванням `id`. Інші можливі розумні значення — `email` та `ім’я користувача` (що відповідає `preferred_username` OIDC-клейму).
* `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS`
  * Обмежує створення облікових записів Just-in-Time (JIT) для користувачів, які автентифікуються через OIDC. Якщо встановити список доменних імен, розділений комами, новий обліковий запис буде створено лише тоді, коли домен адреси електронної пошти користувача збігається з одним із перелічених доменів. Якщо домен не збігається, адміністратор повинен вручну створити обліковий запис користувача, використовуючи адресу електронної пошти користувача OIDC, із надійним випадковим паролем або, бажано, без `hashedPassword` поле взагалі. Доменні імена можуть містити початковий `*.` символ підстановки для збігу з піддоменами.
    * Приклад: щоб дозволити створення облікових записів JIT для користувачів з адресою електронної пошти на кшталт `name@example.com` та `name@math.example.com`:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=example.com, *.example.com`
    * Приклад: щоб повністю вимкнути створення облікових записів JIT:\
      `OVERLEAF_OIDC_ALLOWED_EMAIL_DOMAINS=`
* `OVERLEAF_OIDC_UPDATE_USER_DETAILS_ON_LOGIN`
  * Якщо встановлено у `true`, оновлює поле користувача `first_name` та `last_name` під час входу та вимикає форму даних користувача на `/user/settings` сторінці.
* `OVERLEAF_OIDC_IS_ADMIN_FIELD` та `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`
  * Коли обидві змінні середовища встановлено, процес входу оновлює `user.isAdmin = true` якщо профіль, повернутий OP, містить атрибут, вказаний у `OVERLEAF_OIDC_IS_ADMIN_FIELD` і його значення збігається з `OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE`, інакше `user.isAdmin` встановлюється в `false`. Якщо `OVERLEAF_OIDC_IS_ADMIN_FIELD` є `email` тоді значення атрибута `emails[0].value` використовується для перевірки збігу.

URL перенаправлення для вашого провайдера OpenID — `https://my-overleaf-instance.com/oidc/login/callback`.

<details>

<summary>Приклад файлу variables.env</summary>

{% code title="variables.env" overflow="wrap" %}

```dotenv
OVERLEAF_APP_NAME="Наш екземпляр Overleaf"

ENABLED_LINKED_FILE_TYPES=project_file,project_output_file,url

# Увімкнення генерації мініатюр за допомогою ImageMagick
ENABLE_CONVERSIONS=true

# Вимкнення вимоги підтвердження електронної пошти
EMAIL_CONFIRMATION_DISABLED=true

## Nginx
# NGINX_WORKER_PROCESSES=4
# NGINX_WORKER_CONNECTIONS=768

## Встановити для TLS через nginx-proxy
# OVERLEAF_BEHIND_PROXY=true
# OVERLEAF_SECURE_COOKIE=true

OVERLEAF_SITE_URL=http://my-overleaf-instance.com
OVERLEAF_NAV_TITLE=Наш екземпляр Overleaf
# OVERLEAF_HEADER_IMAGE_URL=http://somewhere.com/mylogo.png
OVERLEAF_ADMIN_EMAIL=support@example.com

OVERLEAF_LEFT_FOOTER=[{"text": "Зверніться до служби підтримки", "url": "mailto:support@example.com"}]
OVERLEAF_RIGHT_FOOTER=[{"text":"Привіт, я праворуч", "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=Цю систему обслуговує відділ x

OVERLEAF_PROXY_LEARN=true
NAV_HIDE_POWERED_BY=true

#################
## OIDC для 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='Увійти за допомогою провайдера Keycloak OIDC'
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
```

{% endcode %}

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayakaleaf-pro.ayaka.space/on-premises/uk/konfiguraciya/overleaf-toolkit/authentication/oidc-authentication.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.