Перейти до основного вмісту
Цю функцію розроблено в yu-i-i/overleaf-cep. Тут ми наводимо документацію для її налаштування.

Налаштування

Внутрішньо модуль OIDC в Overleaf використовує бібліотеку passport-openidconnect. Якщо у вас виникають проблеми з налаштуванням OpenID Connect, варто прочитати README для passport-openidconnect, щоб зрозуміти, яку конфігурацію вона очікує. Для ввімкнення модуля автентифікації OIDC потрібна змінна середовища EXTERNAL_AUTH. Ця змінна середовища визначає, які методи зовнішньої автентифікації активовано. Значенням цієї змінної є список. Якщо список містить oidc, автентифікацію OIDC буде активовано. Наприклад: EXTERNAL_AUTH=ldap oidc Під час використання методу автентифікації OIDC користувача перенаправляють на сайт автентифікації постачальника ідентичності (IdP). Якщо IdP успішно автентифікує користувача, у базі даних користувачів Overleaf шукається запис, що містить поле thirdPartyIdentifiers такої структури:
externalUserId має збігатися з ID користувача в профілі, який повертає сервер IdP (див. змінну середовища OVERLEAF_OIDC_USER_ID_FIELD), а providerId має збігатися з ID постачальника OIDC (див. OVERLEAF_OIDC_PROVIDER_ID). Якщо відповідного запису не знайдено, у базі даних шукається користувач, чия основна адреса електронної пошти збігається з адресою в профілі користувача IdP:
  • Якщо такого користувача знайдено, поле thirdPartyIdentifiers оновлюється.
  • Якщо відповідного користувача не знайдено, а створення облікових записів JIT не вимкнено, створюється новий користувач з адресою електронної пошти та thirdPartyIdentifiers з профілю IdP.
В обох випадках вважається, що користувача «пов’язано» із зовнішнім користувачем OIDC. Користувач може скасувати зв’язок із постачальником OIDC на сторінці /user/settings.

Пошук значень за допомогою документа виявлення

Кожен постачальник OpenID (OP) публікує документ виявлення (discovery document) за адресою <issuer>/.well-known/openid-configuration. Копіюйте значення з нього, а не вводьте їх вручну: одного неправильного символу достатньо, щоб вхід перестав працювати.
1

Знайдіть URL виявлення

Ваш OP показує його на сторінці клієнта (постачальника), створеного для Overleaf. В Authentik відкрийте Applications > Providers, виберіть постачальника та знайдіть OpenID Configuration URL і OpenID Configuration Issuer:

Authentik: URL виявлення та issuer постачальника (тестовий екземпляр)

Зазвичай URL виглядає так:
  • 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

Прочитайте значення

Відкрийте URL у браузері або виконайте на сервері Overleaf:
Відповідь Authentik виглядає так:
Authentik також наводить ці URL нижче на сторінці постачальника:

Authentik: ендпоінти постачальника (тестовий екземпляр)

3

Скопіюйте їх у variables.env

4

Перевірте, що Overleaf може дістатися до OP

Overleaf звертається до ендпоінтів token і userinfo зсередини свого контейнера, тому OP має бути доступним звідти, а не лише з вашого браузера:
Команда має вивести 200.
Копіюйте issuer точно, включно з кінцевою скісною рискою. Overleaf посимвольно порівнює його з issuer в ID-токені; будь-яка відмінність призводить до того, що кожен вхід через OIDC завершується помилкою:{"message":{"message":"ID token not issued by expected OpenID provider."}}В Authentik issuer належить застосунку (.../application/o/<application-slug>/). Це не адреса сервера Authentik, хоча URL authorize, token і userinfo спільні для всіх застосунків.

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

Значення наведених нижче п’яти обов’язкових змінних можна знайти за допомогою ендпоінта .well-known/openid-configuration вашого постачальника OpenID (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
    • Довільний ID OP, за замовчуванням oidc.
  • OVERLEAF_OIDC_PROVIDER_NAME
    • Назва OP, що використовується в розділі Linked Accounts на сторінці /user/settings, за замовчуванням OIDC Provider.
  • OVERLEAF_OIDC_IDENTITY_SERVICE_NAME
    • Відображувана назва сервісу ідентифікації, що використовується на сторінці входу (за замовчуванням: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_DESCRIPTION
    • Опис OP, що використовується в розділі Linked Accounts (за замовчуванням: Log in with $OVERLEAF_OIDC_PROVIDER_NAME).
  • OVERLEAF_OIDC_PROVIDER_INFO_LINK
    • URL Learn more в описі OP; за замовчуванням посилання Learn more в описі немає.
  • OVERLEAF_OIDC_PROVIDER_HIDE_NOT_LINKED
    • Не показувати OP на сторінці /user/settings, якщо обліковий запис користувача не пов’язано з OP; за замовчуванням false.
  • OVERLEAF_OIDC_USER_ID_FIELD
    • Значення цього атрибута Overleaf використовуватиме як зовнішній ID користувача; за замовчуванням id. Інші можливі доречні значення — email і username (відповідає claim OIDC preferred_username).
  • 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, або є масивом, що містить OVERLEAF_OIDC_IS_ADMIN_FIELD_VALUE (наприклад, claim groups); інакше user.isAdmin встановлюється в false. Якщо OVERLEAF_OIDC_IS_ADMIN_FIELD має значення email, для перевірки збігу використовується значення атрибута emails[0].value.
URL перенаправлення для вашого постачальника OpenID: https://my-overleaf-instance.com/oidc/login/callback.
variables.env

Покрокова інструкція: goauthentik

Тут описано налаштування, протестоване з goauthentik. Замініть https://overleaf.example.com на ваш OVERLEAF_SITE_URL, а https://authentik.example.com — на адресу вашого Authentik.
1

Створіть постачальника

В Authentik відкрийте Applications > Providers, натисніть New Provider, виберіть OAuth2/OpenID Provider і натисніть Next.
  • Client Type: Confidential.
  • Redirect URIs (у розділі Protocol settings): додайте https://overleaf.example.com/oidc/login/callback з режимом зіставлення Strict.
  • Одразу скопіюйте Client ID і Client Secret у OVERLEAF_OIDC_CLIENT_ID і OVERLEAF_OIDC_CLIENT_SECRET.

Authentik: Client ID і Client Secret нового постачальника

Authentik показує client secret лише під час створення постачальника. Пізніше форма редагування пропонує тільки Modify, що замінює секрет новим.
2

Створіть застосунок

Відкрийте Applications > Applications, створіть новий застосунок, задайте йому назву та slug, наприклад overleaf, і виберіть постачальника. Slug стає частиною issuer: https://authentik.example.com/application/o/overleaf/.
3

Скопіюйте URL

Дотримуйтеся розділу Пошук значень за допомогою документа виявлення вище, щоб заповнити п’ять URL.
4

Зіставте адміністраторів (необов'язково)

Authentik надсилає групи користувача як claim groups — масив. Щоб члени групи Authentik Admins стали адміністраторами Overleaf:
Прапорець адміністратора оновлюється під час кожного входу через OIDC. Якщо поле або значення неправильні, кожен адміністратор, який входить через OIDC, втрачає права адміністратора, зокрема й адміністратор, створений у launchpad. Спершу протестуйте зіставлення з другим обліковим записом адміністратора.
variables.env

Питання та відповіді

Відповідь: Перевірте таке:
  • Версія. До v6.3.0 Overleaf не зчитував власні claims, як-от groups, тож працювало лише OVERLEAF_OIDC_IS_ADMIN_FIELD=email. Оновіться до v6.3.0 або новішої версії.
  • Claim має бути у відповіді UserInfo. Overleaf зчитує claim з OVERLEAF_OIDC_USER_INFO_URL, а не з ID-токена. Якщо ваш OP додає claim лише до ID-токена, додайте його також до UserInfo, наприклад за допомогою Add to userinfo у mapper Keycloak.
  • Значення має збігатися точно, включно з регістром, наприклад Admins.
Статус адміністратора перевіряється заново під час кожного входу: користувач, якого зробили адміністратором в адмін-панелі, втрачає цей статус під час наступного входу, якщо claim не збігається.
Відповідь: Ні. GitHub підтримує OAuth 2.0, але не OpenID Connect для входу користувачів: він не повертає ID-токен, якого вимагає Overleaf, тож вхід завершується помилкою ID token not present in token response.Щоб користувачі могли входити через свій обліковий запис GitHub, використовуйте постачальника ідентичності, як-от goauthentik або Keycloak, з GitHub як джерелом входу, і підключіть Overleaf до цього постачальника через OIDC.
Відповідь: Так. GitLab, зокрема самостійно розміщений GitLab, є постачальником OpenID Connect. У GitLab створіть застосунок у розділі Applications (у налаштуваннях користувача, групи або Admin area) з такими параметрами:
  • Redirect URI: https://my-overleaf-instance.com/oidc/login/callback
  • Scopes: openid, profile і email
Потім візьміть кінцеві точки з https://gitlab.com/.well-known/openid-configuration або з того самого шляху на вашому GitLab, як описано в розділі Пошук значень за допомогою документа виявлення. Для gitlab.com issuer — це https://gitlab.com, без кінцевої скісної риски.
Відповідь: Перед перенаправленням до OP Overleaf зберігає випадкове значення state у сеансі користувача й перевіряє його, коли OP перенаправляє назад. Ці помилки означають, що сеанс під час callback — не той, що розпочав вхід.Unable to verify authorization request state означає, що браузер не надіслав cookie сеансу назад під час callback. Перевірте, що:
  • Користувачі відкривають Overleaf за адресою з OVERLEAF_SITE_URL. Callback завжди надходить на OVERLEAF_SITE_URL, тож вхід, розпочатий з іншої адреси, наприклад http://192.168.1.20, коли OVERLEAF_SITE_URL дорівнює https://overleaf.example.com, втрачає свій сеанс.
  • OVERLEAF_SECURE_COOKIE не задано, коли Overleaf обслуговується через звичайний HTTP. Браузери відкидають захищені cookie через HTTP. Будь-яке значення вмикає цей параметр, зокрема false, тож натомість видаліть цей рядок.
Invalid authorization request state означає, що новіший вхід замінив збережене значення, наприклад після входу одночасно з двох вкладок або повернення назад у браузері під час входу. Закрийте інші вкладки й розпочніть вхід знову зі сторінки входу Overleaf.
Останнє оновлення 2 листопада 2026 р.