Перейти до змісту

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

Gramps Web підтримує аутентифікацію OpenID Connect (OIDC), що дозволяє користувачам входити в систему, використовуючи зовнішні постачальники ідентичності. Це включає вбудовані постачальники Google та Microsoft, а також кастомні OIDC постачальники, такі як Keycloak, Authentik та Authelia.

GitHub як OIDC постачальник більше не підтримується

Якщо у вас встановлено OIDC_GITHUB_CLIENT_ID / OIDC_GITHUB_CLIENT_SECRET з попередньої версії, видаліть їх – вони тепер ігноруються, і користувачі, які раніше входили через GitHub, більше не можуть увійти таким чином. GitHub є постачальником OAuth 2.0, а не постачальником OpenID Connect, і ніколи не повертав заяву, на яку Gramps Web покладається для ідентифікації, тому він ніколи не був повністю надійним.

Огляд

Аутентифікація OIDC дозволяє вам:

  • Використовувати зовнішні постачальники ідентичності для аутентифікації користувачів
  • Підтримувати кілька постачальників аутентифікації одночасно
  • Відображати OIDC групи/ролі на ролі користувачів Gramps Web
  • Реалізувати Єдину Аутентифікацію (SSO) та Єдине Виходу
  • За бажанням вимкнути локальну аутентифікацію за допомогою імені користувача/пароля

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

Щоб увімкнути аутентифікацію OIDC, вам потрібно налаштувати відповідні параметри у вашому файлі конфігурації Gramps Web або змінних середовища. Дивіться сторінку Конфігурація сервера для отримання повного списку доступних налаштувань OIDC.

Info

При використанні змінних середовища пам'ятайте, що потрібно додавати префікс до кожної назви налаштування GRAMPSWEB_ (наприклад, GRAMPSWEB_OIDC_ENABLED). Дивіться Файл конфігурації проти змінних середовища для деталей.

Вбудовані постачальники

Gramps Web має вбудовану підтримку популярних постачальників ідентичності. Щоб їх використовувати, вам потрібно лише надати ідентифікатор клієнта та секрет клієнта:

  • Google: OIDC_GOOGLE_CLIENT_ID та OIDC_GOOGLE_CLIENT_SECRET
  • Microsoft: OIDC_MICROSOFT_CLIENT_ID та OIDC_MICROSOFT_CLIENT_SECRET

Ви можете налаштувати кілька постачальників одночасно. Система автоматично виявить, які постачальники доступні на основі значень конфігурації.

Microsoft: однотенантні розгортання

Вбудований постачальник Microsoft використовує багатотенантну точку доступу /common і за замовчуванням приймає входи з будь-якого облікового запису Microsoft. Якщо ви хочете дозволити користувачам входити лише з вашого власного тенанту, використовуйте кастомний OIDC постачальник з вашим специфічним для тенанту URL-адресою видавця, що дозволяє зберегти валідацію видавця активною і обмежити входи до цього тенанту.

Кастомні OIDC постачальники

Для кастомних OIDC постачальників (таких як Keycloak, Authentik, Authelia або однотенантний Microsoft Entra тенант) використовуйте ці налаштування:

Ключ Опис
OIDC_ENABLED Булеве значення, чи потрібно увімкнути аутентифікацію OIDC. Встановіть на True.
OIDC_ISSUER URL-адреса видавця вашого постачальника. Відкриття отримується з <issuer>/.well-known/openid-configuration.
OIDC_CLIENT_ID Ідентифікатор клієнта для вашого OIDC постачальника
OIDC_CLIENT_SECRET Секрет клієнта для вашого OIDC постачальника
OIDC_NAME Кастомна назва для відображення (необов'язково, за замовчуванням "OIDC")
OIDC_SCOPES OAuth області (необов'язково, за замовчуванням "openid email profile")
OIDC_USERNAME_CLAIM Заява, що використовується для генерації імені користувача (необов'язково, за замовчуванням "preferred_username")

Налаштування з кількома деревами

На сервері з кількома деревами дерево, в яке користувач входить, має бути відомим до того, як Gramps Web перенаправить до постачальника ідентичності, тому вхід починається з:

GET /api/oidc/login/?provider=<id>&tree=<tree_id>

tree є обов'язковим у налаштуваннях з кількома деревами; пропуск його або передача ID дерева, яке не існує, призводить до невдачі входу. На сервері з одним деревом tree є необов'язковим, але якщо воно вказане, воно повинно відповідати налаштованому TREE.

OIDC ідентичність прив'язується до точно одного облікового запису Gramps Web, який, в свою чергу, належить точно одному дереву – вхід до іншого дерева призводить до невдачі, а не до переміщення облікового запису. Немає способу зв'язати одну ідентичність у постачальника з обліковими записами в кількох деревах; користувачі, які потребують доступу до кількох дерев, потребують окремих ідентичностей у постачальника (наприклад, різні імена користувачів або облікові записи).

Warning

Обліковий запис адміністратора сайту без асоційованого дерева (див. створення адміністративного облікового запису) не може увійти через OIDC, оскільки вхід OIDC завжди вимагає дерева. Такі облікові записи повинні бути створені та аутентифіковані за допомогою локального імені користувача/пароля.

Обов'язкові URI для перенаправлення

При налаштуванні вашого OIDC постачальника ви повинні зареєструвати наступний URI для перенаправлення:

Для OIDC постачальників, які підтримують символи підстановки: (наприклад, Authentik)

  • https://your-gramps-backend.com/api/oidc/callback/*

Де * є символом підстановки regex. В залежності від інтерпретатора regex вашого постачальника це також може бути .* або подібне. Переконайтеся, що regex увімкнено, якщо ваш постачальник цього вимагає (наприклад, Authentik).

Для OIDC постачальників, які не підтримують символи підстановки: (наприклад, Authelia)

  • https://your-gramps-backend.com/api/oidc/callback/custom

Дерево ніколи не є частиною URI для перенаправлення, навіть на серверах з кількома деревами – воно передається окремо в сесії, оскільки постачальники вимагають, щоб URI для перенаправлення точно відповідав зареєстрованому.

Відображення ролей

Gramps Web може автоматично відображати OIDC групи або ролі з вашого постачальника ідентичності на ролі користувачів Gramps Web. Це дозволяє вам централізовано керувати дозволами користувачів у вашому постачальнику ідентичності. Відображення ролей працює однаково для всіх постачальників, вбудованих або кастомних.

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

Використовуйте ці налаштування для конфігурації відображення ролей:

Ключ Опис
OIDC_ROLE_CLAIM Назва заяви в OIDC токені, що містить групи/ролі користувача. За замовчуванням "groups". Підтримуються крапкові шляхи, наприклад, realm_access.roles.
OIDC_GROUP_ADMIN Назва групи/ролі з вашого OIDC постачальника, що відображається на роль "Admin" Gramps
OIDC_GROUP_OWNER Назва групи/ролі з вашого OIDC постачальника, що відображається на роль "Owner" Gramps
OIDC_GROUP_EDITOR Назва групи/ролі з вашого OIDC постачальника, що відображається на роль "Editor" Gramps
OIDC_GROUP_CONTRIBUTOR Назва групи/ролі з вашого OIDC постачальника, що відображається на роль "Contributor" Gramps
OIDC_GROUP_MEMBER Назва групи/ролі з вашого OIDC постачальника, що відображається на роль "Member" Gramps
OIDC_GROUP_GUEST Назва групи/ролі з вашого OIDC постачальника, що відображається на роль "Guest" Gramps

Поведінка відображення ролей

Якщо жодне налаштування OIDC_GROUP_* не налаштоване, відображення ролей вимкнене, і ролі керуються вручну в Gramps Web; нові OIDC облікові записи тоді створюються з вимкненим статусом і потребують схвалення існуючого власника або адміністратора (див. Перший вхід та початкове налаштування нижче).

Після налаштування відображення ролей, при кожному вході:

  • Якщо заява про роль присутня і користувач належить до відображеної групи, йому надається відповідна роль.
  • Якщо заява про роль присутня, але користувач не належить до жодної відображеної групи, його роль встановлюється на вимкнену. Це є стандартним поведінковим режимом, а не помилкою – Gramps Web не може вивести роль для групи, яку не розпізнає.
  • Якщо заява про роль зовсім відсутня в токені, існуюча роль залишається незмінною; новий обліковий запис все ще за замовчуванням вимкнений.

Google не надсилає заяву про групи

Токени Google ніколи не включають заяву groups, тому з увімкненим відображенням ролей входи Google потрапляють під "заява відсутня" вище: існуючі користувачі зберігають свою роль, але нові користувачі Google створюються з вимкненим статусом і потребують ручного схвалення. Пам'ятайте про це перед увімкненням відображення ролей лише для іншого постачальника – це не вимикає існуючих користувачів Google.

Microsoft Entra повертає ролі додатків та членства в групах лише в ID токені, а не з кінцевої точки userinfo. Gramps Web об'єднує заяви ID токена в відповідь userinfo, щоб OIDC_ROLE_CLAIM працював так само, як для інших постачальників; де обидва містять заяву, значення userinfo має перевагу.

Перший вхід та початкове налаштування

Нові облікові записи, створені через OIDC, починають з вимкненим статусом, якщо відображення ролей не надає їм роль (див. вище). На абсолютно новій інстанції ніхто не може схвалити вимкнений обліковий запис, і якщо OIDC_DISABLE_LOCAL_AUTH також увімкнено, немає можливості входу з паролем.

Налаштуйте групу власників/адміністраторів перед першим входом

Перед тим, як хтось увійде через OIDC вперше, налаштуйте OIDC_GROUP_OWNER (або OIDC_GROUP_ADMIN) і переконайтеся, що перший користувач належить до цієї групи у постачальника. Інакше інстанцію не можна буде початково налаштувати через OIDC.

Облікові записи та імена користувачів

Облікові записи, створені через OIDC, отримують згенероване ім'я користувача, яке призначається один раз під час створення облікового запису і ніколи не змінюється при наступних входах:

  • Вбудовані постачальники: <provider>_<claim value>, наприклад, microsoft_alice@contoso.com
  • Кастомний постачальник: просте значення заяви, наприклад, alice

Числовий суфікс додається при конфлікті. Немає способу перейменувати ім'я користувача облікового запису, створеного через OIDC; на відміну від цього, повне ім'я та адреса електронної пошти оновлюються при кожному вході.

Вхід через OIDC ніколи не прив'язується до існуючого локального облікового запису, який випадково ділить свою адресу електронної пошти – це навмисно, оскільки зв'язування облікових записів за адресою електронної пошти є вектором захоплення облікового запису. Користувач, який вже має локальний обліковий запис, отримує другий, окремий обліковий запис перший раз, коли він входить через OIDC.

Адреси електронної пошти від постачальника зберігаються лише в тому випадку, якщо постачальник позначає їх як перевірені (або зовсім не включає заяву email_verified) і якщо адреса ще не використовується іншим обліковим записом; в іншому випадку вхід проходить без зберігання адреси електронної пошти.

Вихід OIDC

Gramps Web підтримує Єдиний Вихід (SSO logout) для OIDC постачальників. GET /api/oidc/logout/ шукає end_session_endpoint постачальника і повертає його як logout_url у відповіді; саме фронтенд Gramps Web навігає браузер туди, щоб фактично завершити сесію у постачальника ідентичності. logout_url є null, коли у постачальника немає end_session_endpoint.

Токени не відкликаються при виході

Вихід лише завершує сесію браузера; наразі немає способу відкликати токен Gramps Web, який вже був виданий. Токени залишаються дійсними до їх закінчення (JWT_ACCESS_TOKEN_EXPIRES, за замовчуванням 15 хвилин для токенів доступу), незалежно від того, чи вийшов користувач з Gramps Web або у постачальника ідентичності.

Приклад конфігурацій

Кастомний OIDC постачальник (Keycloak)

TREE="Моє Сімейне Дерево"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..."  # ваш секретний ключ
USER_DB_URI="sqlite:////path/to/users.sqlite"

# Кастомна конфігурація OIDC
OIDC_ENABLED=True
OIDC_ISSUER="https://auth.example.com/realms/myrealm"
OIDC_CLIENT_ID="gramps-web"
OIDC_CLIENT_SECRET="ваш-секрет-клієнта"
OIDC_NAME="Сімейний SSO"
OIDC_SCOPES="openid email profile"
OIDC_AUTO_REDIRECT=True  # Необов'язково: автоматично перенаправити на SSO вхід
OIDC_DISABLE_LOCAL_AUTH=True  # Необов'язково: вимкнути вхід за допомогою імені користувача/пароля

# Необов'язково: Відображення ролей з OIDC груп на ролі Gramps
OIDC_ROLE_CLAIM="groups"  # або "roles" залежно від вашого постачальника
OIDC_GROUP_ADMIN="gramps-admins"
OIDC_GROUP_EDITOR="gramps-editors"
OIDC_GROUP_MEMBER="gramps-members"

EMAIL_HOST="mail.example.com"
EMAIL_PORT=465
EMAIL_USE_SSL=True  # Використовувати імпліцитний SSL для порту 465
EMAIL_HOST_USER="gramps@example.com"
EMAIL_HOST_PASSWORD="..." # ваш SMTP пароль
DEFAULT_FROM_EMAIL="gramps@example.com"

Вбудований постачальник (Google)

TREE="Моє Сімейне Дерево"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..."  # ваш секретний ключ
USER_DB_URI="sqlite:////path/to/users.sqlite"

# Google OAuth
OIDC_GOOGLE_CLIENT_ID="ваш-google-клієнт-id"
OIDC_GOOGLE_CLIENT_SECRET="ваш-google-клієнт-secret"

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

Ви можете одночасно увімкнути кілька OIDC постачальників:

TREE="Моє Сімейне Дерево"
BASE_URL="https://mytree.example.com"
SECRET_KEY="..."  # ваш секретний ключ
USER_DB_URI="sqlite:////path/to/users.sqlite"

# Кастомний постачальник
OIDC_ENABLED=True
OIDC_ISSUER="https://auth.example.com/realms/myrealm"
OIDC_CLIENT_ID="gramps-web"
OIDC_CLIENT_SECRET="ваш-секрет-клієнта"
OIDC_NAME="Компанійний SSO"

# Google OAuth
OIDC_GOOGLE_CLIENT_ID="ваш-google-клієнт-id"
OIDC_GOOGLE_CLIENT_SECRET="ваш-google-клієнт-secret"

# Microsoft OAuth
OIDC_MICROSOFT_CLIENT_ID="ваш-microsoft-клієнт-id"
OIDC_MICROSOFT_CLIENT_SECRET="ваш-microsoft-клієнт-secret"

Authelia

Доступний посібник зі створення OIDC для Gramps Web, створений спільнотою, на офіційному веб-сайті документації Authelia.

Keycloak

Більшість конфігурації для Keycloak можна залишити за замовчуванням (Клієнт → Створити клієнта → Аутентифікація клієнта УВІМКНЕНА). Є кілька винятків:

  1. OpenID область – Область openid не включена за замовчуванням у всіх версіях Keycloak. Щоб уникнути проблем, додайте її вручну: Клієнт → [Клієнт Gramps] → Області клієнтів → Додати область → Ім'я: openid → Встановити за замовчуванням.

  2. Ролі – Ролі можуть бути призначені або на рівні клієнта, або глобально для кожного царства.

    • Якщо ви використовуєте ролі клієнта, встановіть параметр конфігурації OIDC_ROLE_CLAIM на: resource_access.[gramps-client-name].roles
    • Щоб зробити ролі видимими для Gramps, перейдіть до Області клієнтів (верхній рівень, не під конкретним клієнтом), потім: Ролі → Мапери → ролі клієнта → Додати до userinfo → УВІМКНУТО.