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

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

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

Внутрішньо модуль SAML в Overleaf використовує бібліотеку passport-saml; більшість наведених нижче параметрів конфігурації передаються безпосередньо до passport-saml. Якщо у вас виникають проблеми з налаштуванням SAML, варто прочитати README для passport-saml, щоб зрозуміти, яку конфігурацію вона очікує. Для ввімкнення модуля автентифікації SAML потрібна змінна середовища EXTERNAL_AUTH. Ця змінна середовища визначає, які методи зовнішньої автентифікації активовано. Значенням цієї змінної є список. Якщо список містить saml, автентифікацію SAML буде активовано. Наприклад: EXTERNAL_AUTH=ldap saml Під час використання методу автентифікації SAML користувача перенаправляють на сайт автентифікації постачальника ідентичності (IdP). Якщо IdP успішно автентифікує користувача, у базі даних користувачів Overleaf шукається запис, що містить поле samlIdentifiers такої структури:

samlIdentifiers: [
  {
    externalUserId: "...",
    providerId: "1",
    userIdAttribute: "..."
  }
]

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

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

Примітка: наразі підтримується лише один SAML IdP. Поле providerId у samlIdentifiers має фіксоване значення '1'.

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

OVERLEAF_SAML_IDENTITY_SERVICE_NAME
- Відображувана назва сервісу ідентифікації, що використовується на сторінці входу (за замовчуванням: Log in with SAML IdP).
OVERLEAF_SAML_USER_ID_FIELD
- Значення цього атрибута Overleaf використовуватиме як зовнішній ID користувача; за замовчуванням nameID.
OVERLEAF_SAML_EMAIL_FIELD
- Назва поля Email у профілі користувача; за замовчуванням nameID.
OVERLEAF_SAML_FIRST_NAME_FIELD
- Назва поля firstName у профілі користувача; за замовчуванням givenName.
OVERLEAF_SAML_LAST_NAME_FIELD
- Назва поля lastName у профілі користувача; за замовчуванням lastName
OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN
- Якщо встановлено true, під час входу оновлюються поля користувача first_name і last_name, а форма даних користувача на сторінці /user/settings вимикається.
OVERLEAF_SAML_ENTRYPOINT (обов’язково)
- URL точки входу для сервісу ідентифікації SAML.
  - Приклад: https://idp.example.com/simplesaml/saml2/idp/SSOService.php
  - Приклад для Azure: https://login.microsoftonline.com/8b26b46a-6dd3-45c7-a104-f883f4db1f6b/saml2
OVERLEAF_SAML_ISSUER (обов’язково)
- Назва емітента (Issuer).
OVERLEAF_SAML_AUDIENCE
- Очікуваний Audience у відповіді SAML; за замовчуванням дорівнює значенню OVERLEAF_SAML_ISSUER.
OVERLEAF_SAML_IDP_CERT (обов’язково)
- Шлях до файлу з публічним сертифікатом постачальника ідентичності, що використовується для перевірки підписів вхідних відповідей SAML. Якщо постачальник ідентичності має кілька дійсних сертифікатів підпису, можна вказати JSON-масив шляхів до сертифікатів.
  - Приклад (один сертифікат): /var/lib/overleaf/certs/idp_cert.pem
  - Приклад (кілька сертифікатів): ["var/lib/overleaf/certs/idp_cert.pem", "/var/lib/overleaf/certs/idp_cert_old.pem"]
OVERLEAF_SAML_PUBLIC_CERT
- Шлях до файлу з публічним сертифікатом підпису, який вбудовується в запити автентифікації, щоб IdP міг перевірити підписи вхідного запиту SAML. Він потрібен під час налаштування ендпоінта метаданих, коли стратегію налаштовано з OVERLEAF_SAML_PRIVATE_KEY. Для підтримки ротації сертифікатів можна вказати JSON-масив шляхів до сертифікатів. У разі передавання масиву сертифікатів перший елемент масиву має відповідати поточному OVERLEAF_SAML_PRIVATE_KEY. Додаткові елементи масиву можна використовувати для публікації майбутніх сертифікатів для IdP до зміни OVERLEAF_SAML_PRIVATE_KEY.
OVERLEAF_SAML_PRIVATE_KEY
- Шлях до файлу з приватним ключем у форматі PEM, що відповідає OVERLEAF_SAML_PUBLIC_CERT і використовується для підпису запитів автентифікації, які надсилає passport-saml.
OVERLEAF_SAML_DECRYPTION_CERT
- Шлях до файлу з публічним сертифікатом, що використовується для ендпоінта метаданих.
OVERLEAF_SAML_DECRYPTION_PVK
- Шлях до файлу з приватним ключем, що відповідає OVERLEAF_SAML_DECRYPTION_CERT, який використовуватиметься для спроби розшифрування будь-яких отриманих зашифрованих тверджень (assertions).
OVERLEAF_SAML_SIGNATURE_ALGORITHM
- Необов’язково задає алгоритм підпису запитів; допустимі значення: ‘sha1’ (за замовчуванням), ‘sha256’ (рекомендовано), ‘sha512’ (найбезпечніший, перевірте, чи підтримує його ваш IdP).
OVERLEAF_SAML_ADDITIONAL_PARAMS
- JSON-словник додаткових параметрів запиту, які додаються до всіх запитів.
OVERLEAF_SAML_ADDITIONAL_AUTHORIZE_PARAMS
- JSON-словник додаткових параметрів запиту, які додаються до запитів ‘authorize’.
  - Приклад: {"some_key": "some_value"}
OVERLEAF_SAML_IDENTIFIER_FORMAT
- Формат ідентифікатора імені, який запитується в постачальника ідентичності (за замовчуванням: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress). Якщо використовується urn:oasis:names:tc:SAML:2.0:nameid-format:persistent, переконайтеся, що визначено змінну середовища OVERLEAF_SAML_EMAIL_FIELD. Якщо потрібен urn:oasis:names:tc:SAML:2.0:nameid-format:transient, необхідно також визначити змінну середовища OVERLEAF_SAML_USER_ID_FIELD, якій можна, наприклад, присвоїти адресу електронної пошти користувача.
OVERLEAF_SAML_ACCEPTED_CLOCK_SKEW_MS
- Допустиме розходження годинників клієнта та сервера в мілісекундах під час перевірки часових міток дійсності умов тверджень OnBefore і NotOnOrAfter. Значення -1 повністю вимикає перевірку цих умов. За замовчуванням 0.
OVERLEAF_SAML_ATTRIBUTE_CONSUMING_SERVICE_INDEX
- Атрибут AttributeConsumingServiceIndex, який додається до AuthnRequest, щоб вказати IdP, який набір атрибутів додати до відповіді (посилання).
OVERLEAF_SAML_AUTHN_CONTEXT
- JSON-масив значень формату ідентифікатора імені для запиту контексту автентифікації. За замовчуванням: ["urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport"].
OVERLEAF_SAML_FORCE_AUTHN
- Якщо true, початковий запит SAML від постачальника послуг вказує, що IdP має примусово повторно автентифікувати користувача, навіть якщо в нього є дійсний сеанс.
OVERLEAF_SAML_DISABLE_REQUESTED_AUTHN_CONTEXT
- Якщо true, конкретний контекст автентифікації не запитується. Наприклад, можна встановити true, щоб дозволити додаткові контексти, як-от вхід без пароля (urn:oasis:names:tc:SAML:2.0:ac:classes:X509). Підтримка додаткових контекстів залежить від вашого IdP.
OVERLEAF_SAML_AUTHN_REQUEST_BINDING
- Якщо встановлено HTTP-POST, автентифікація в IdP запитуватиметься через прив’язку HTTP POST, інакше за замовчуванням використовується HTTP-Redirect.
OVERLEAF_SAML_VALIDATE_IN_RESPONSE_TO
- Якщо always, InResponseTo перевірятиметься у вхідних відповідях SAML.
- Якщо never, InResponseTo не перевірятиметься (за замовчуванням).
- Якщо ifPresent, InResponseTo перевірятиметься лише тоді, коли воно присутнє у вхідній відповіді SAML.
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED і OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED
- Якщо встановлено true (за замовчуванням), Overleaf очікує, що твердження SAML та, відповідно, уся відповідь автентифікації SAML будуть підписані IdP. Коли обидва параметри мають значення false, підписаними мають бути принаймні твердження або відповідь.
OVERLEAF_SAML_REQUEST_ID_EXPIRATION_PERIOD_MS
- Визначає час, після якого ID запиту, згенерований для запиту SAML, вважатиметься недійсним, якщо його виявлено в полі InResponseTo відповіді SAML. За замовчуванням: 28800000 (8 годин).
OVERLEAF_SAML_LOGOUT_URL
- базова адреса для запитів на вихід (за замовчуванням: entryPoint).
  - Приклад: https://idp.example.com/simplesaml/saml2/idp/SingleLogoutService.php
OVERLEAF_SAML_ADDITIONAL_LOGOUT_PARAMS
- JSON-словник додаткових параметрів запиту, які додаються до запитів ‘logout’.
OVERLEAF_SAML_IS_ADMIN_FIELD і OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE
- Коли задано обидві змінні середовища, процес входу встановлює user.isAdmin = true, якщо профіль, повернутий SAML IdP, містить атрибут, вказаний у OVERLEAF_SAML_IS_ADMIN_FIELD, і його значення або збігається з OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE, або є масивом, що містить OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE; інакше user.isAdmin встановлюється в false. Якщо хоча б одну з цих змінних не задано, статус адміністратора встановлюється в true лише під час створення користувача-адміністратора в Launchpad.

Метадані для постачальника ідентичності Поточна версія Overleaf CE містить ендпоінт для отримання метаданих постачальника послуг: http://my-overleaf-instance.com/saml/meta Постачальника ідентичності потрібно налаштувати так, щоб він розпізнавав сервер Overleaf як «постачальника послуг» (Service Provider). Інструкції щодо цього див. у документації вашого сервера SAML. Нижче наведено приклад відповідних метаданих постачальника послуг:

ol-meta.xml

<?xml version="1.0"?>
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
                  xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
                  entityID="MyOverleaf"
                  ID="_b508c83b7dda452f5b269383fb391107116f8f57">
  <SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol" AuthnRequestsSigned="true" WantAssertionsSigned="true">
    <KeyDescriptor use="signing">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
    </KeyDescriptor>
    <KeyDescriptor use="encryption">
      <ds:KeyInfo>
        <ds:X509Data>
          <ds:X509Certificate>MII...
[skipped]
</ds:X509Certificate>
        </ds:X509Data>
      </ds:KeyInfo>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes256-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2009/xmlenc11#aes128-gcm"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes256-cbc"/>
      <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#aes128-cbc"/>
    </KeyDescriptor>
    <SingleLogoutService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                         Location="https://my-overleaf-instance.com/saml/logout/callback"/>
    <NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
    <AssertionConsumerService index="1"
                              isDefault="true"
                              Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
                              Location="https://my-overleaf-instance.com/saml/login/callback"/>
  </SPSSODescriptor>
</EntityDescriptor>

Зверніть увагу на сертифікати, AssertionConsumerService.Location, SingleLogoutService.Location і EntityDescriptor.entityID та задайте відповідні значення в конфігурації вашого IdP або надішліть файл метаданих адміністраторові IdP.

Приклад файлу variables.env (мінімальний)

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

#################
##     SAML    ##
#################

EXTERNAL_AUTH=saml
OVERLEAF_SAML_ISSUER=MyOverleaf
OVERLEAF_SAML_IDENTITY_SERVICE_NAME='Log in with SAML Provider'
OVERLEAF_SAML_EMAIL_FIELD=Email
OVERLEAF_SAML_FIRST_NAME_FIELD=DisplayName
OVERLEAF_SAML_LAST_NAME_FIELD=DisplayName
OVERLEAF_SAML_ENTRYPOINT=http://localhost:18000/login/saml/authorize/admin/SAML_Overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_SIGNATURE_ALGORITHM=

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

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

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

В Authentik відкрийте Applications > Applications і натисніть New Application. Майстер створює застосунок і його постачальника разом.1. Задайте застосунку назву та slug, наприклад overleaf, і натисніть Next:

2. Виберіть SAML Provider і натисніть Next:

3. Заповніть дані постачальника:

Authorization Flow: default-provider-authorization-implicit-consent
ACS URL: https://overleaf.example.com/saml/login/callback
Audience: назва для Overleaf, наприклад overleaf. Overleaf надсилає її як OVERLEAF_SAML_ISSUER.

4. Відкрийте Advanced protocol settings і встановіть:

Signing Certificate: сертифікат, наприклад authentik Self-signed Certificate
Sign assertions і Sign responses: обидва ввімкнено
Service Provider Binding: Post

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

5. Натискайте Next до останньої сторінки та надішліть застосунок.

Скопіюйте значення зі сторінки постачальника

Знову відкрийте постачальника. Усе, що потрібно Overleaf, є на сторінці його огляду:

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

На сторінці постачальника	Змінна середовища
SAML Endpoint	`OVERLEAF_SAML_ENTRYPOINT` і `OVERLEAF_SAML_LOGOUT_URL`
Audience	`OVERLEAF_SAML_ISSUER`
Download signing certificate (файл)	`OVERLEAF_SAML_IDP_CERT`, див. наступний крок

EntityID/Issuer у розділі SAML Configuration — це назва самого Authentik. Не вказуйте її в OVERLEAF_SAML_ISSUER, використовуйте Audience.

Встановіть сертифікат підпису

Натисніть Download у розділі Download signing certificate і збережіть файл як data/overleaf/certs/idp_cert.pem у каталозі Toolkit. Контейнер бачить його як /var/lib/overleaf/certs/idp_cert.pem:

OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem

Зіставте атрибути

Authentik надсилає свої атрибути під такими назвами:

OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username

Групи надходять як http://schemas.xmlsoap.org/claims/Group — список. Щоб члени групи Authentik Admins стали адміністраторами Overleaf:

OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins

Прапорець адміністратора оновлюється під час кожного входу через SAML. Якщо поле або значення неправильні, кожен адміністратор, який входить через SAML, втрачає права адміністратора. Спершу протестуйте зіставлення з другим обліковим записом адміністратора.

Протестований variables.env для goauthentik

variables.env

EXTERNAL_AUTH=saml
OVERLEAF_SAML_IDENTITY_SERVICE_NAME=Log in with Authentik
OVERLEAF_SAML_ENTRYPOINT=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_LOGOUT_URL=https://authentik.example.com/application/saml/overleaf/
OVERLEAF_SAML_ISSUER=overleaf
OVERLEAF_SAML_IDP_CERT=/var/lib/overleaf/certs/idp_cert.pem
OVERLEAF_SAML_WANT_ASSERTIONS_SIGNED=true
OVERLEAF_SAML_WANT_AUTHN_RESPONSE_SIGNED=true
OVERLEAF_SAML_USER_ID_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_EMAIL_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
OVERLEAF_SAML_FIRST_NAME_FIELD=http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
OVERLEAF_SAML_LAST_NAME_FIELD=http://schemas.goauthentik.io/2021/02/saml/username
OVERLEAF_SAML_IS_ADMIN_FIELD=http://schemas.xmlsoap.org/claims/Group
OVERLEAF_SAML_IS_ADMIN_FIELD_VALUE=Admins
OVERLEAF_SAML_UPDATE_USER_DETAILS_ON_LOGIN=true

Огляд

Встановлення

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

Обслуговування

Керування користувачами та проєктами

Підтримка

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

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

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

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

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

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

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

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

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

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