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")
`OIDC_PKCE`	Чи використовувати PKCE, дивіться PKCE (необов'язково, автоматично увімкнено, якщо постачальник це підтримує)

PKCE¶

З версії Gramps Web API 3.23, Gramps Web підтримує PKCE (Proof Key for Code Exchange, метод S256) для потоку авторизаційного коду. Деякі постачальники ідентичності, такі як Pocket ID, можуть бути налаштовані на вимогу PKCE для клієнта і відмовляти у вході, якщо він не використовується. Старі версії Gramps Web API ніколи не використовують PKCE, тому входи з таким клієнтом зазнають невдачі.

Чи використовується PKCE, вирішується під час входу наступним чином:

Якщо OIDC_PKCE встановлено на True, PKCE використовується.
Якщо OIDC_PKCE встановлено на False, PKCE не використовується, навіть якщо постачальник це підтримує.
Якщо OIDC_PKCE не встановлено, або встановлено, але пусте, PKCE використовується, якщо документ виявлення постачальника (/.well-known/openid-configuration) містить S256 у code_challenge_methods_supported, і не використовується в іншому випадку.

Для більшості налаштувань вам не потрібно нічого налаштовувати. Встановіть OIDC_PKCE на True, якщо ваш постачальник вимагає PKCE, але не рекламує S256 у своєму документі виявлення, і на False, якщо ваш постачальник рекламує S256, але неправильно його обробляє. Як змінні середовища, логічні значення повинні бути написані малими літерами (GRAMPSWEB_OIDC_PKCE=true), дивіться Конфігурацію.

Для вбудованих постачальників відповідні параметри – це OIDC_GOOGLE_PKCE та OIDC_MICROSOFT_PKCE.

Код перевірки PKCE зберігається у сесії користувача між перенаправленням до постачальника та зворотним викликом, тому це не вимагає змін у URL-адресах перенаправлення.

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

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

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

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

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

Warning

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

Обов'язкові URL-адреси перенаправлення¶

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

Для 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

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

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

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); в іншому випадку вхід відбувається без зберігання адреси електронної пошти. Оскільки адреси електронної пошти не повинні бути унікальними (з версії Gramps Web API 3.22), адреса зберігається, навіть якщо інший обліковий запис вже її використовує.

OIDC Вихід¶

Gramps Web підтримує єдиний вихід (SSO вихід) для 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 або з постачальника ідентичності.

Виправлення помилок¶

Почніть з точки, де зупиняється вхід, і дотримуйтесь гілки. Gramps Web записує причину невдалого зворотного виклику (шукайте OIDC callback error for provider у журналі сервера), що зазвичай є більш специфічним, ніж повідомлення, показане у браузері.

1. Відсутня кнопка входу?

Перевірте <BASE_URL>/api/oidc/config/. Якщо enabled дорівнює false або providers порожній, OIDC не налаштовано: OIDC_ENABLED має бути True, а кастомний постачальник потребує і OIDC_ISSUER, і OIDC_CLIENT_ID.
Вбудований постачальник (Google, Microsoft) реєструється лише тоді, коли ідентифікатор клієнта та секрет клієнта обидва налаштовані.
Перегляньте журнал сервера під час запуску на наявність Could not load discovery document. Це означає, що сервер не зміг досягти <issuer>/.well-known/openid-configuration (або OIDC_OPENID_CONFIG_URL). Він повторює спробу при першому використанні, але контейнер Gramps Web повинен мати можливість розпізнавати та досягати URL-адресу видавця самостійно, а не лише ваш браузер.

2. Чи отримує браузер помилку відразу після перенаправлення до постачальника?

Помилка показується постачальником ідентичності, до входу.

"невідповідність URL-адреси перенаправлення" (або подібне): URL-адреса перенаправлення, зареєстрована у постачальника, має точно відповідати, включаючи схему, хост, порт і ID постачальника. Дивіться Обов'язкові URL-адреси перенаправлення. Зверніть увагу, що вона формується з BASE_URL, тому неправильний BASE_URL призводить до неправильної URL-адреси перенаправлення.
Помилка PKCE (наприклад, invalid_request, "вимога коду челенджу", або відсутній параметр code_challenge): постачальник вимагає PKCE, але Gramps Web не надіслав його. Перейдіть до гілки PKCE нижче.

3. Чи приймає постачальник вхід, але Gramps Web потім показує помилку?

mismatching_state, або помилка згадує сесію або стан: браузер не надіслав назад кукі сесії, які Gramps Web встановив, коли почався вхід. Цей кукі також несе код перевірки PKCE. Переконайтеся, що адреса в браузері відповідає BASE_URL (така ж схема та хост), що зворотний проксі передає кукі та оригінальний хост, і що вхід починається та завершується в одній і тій же вкладці або вікні браузера.
OIDC authentication failed for <provider> (HTTP 401): перевірте журнал сервера на наявність основної причини. Загальні причини – це неправильний секрет клієнта, URL-адреса видавця, яка не відповідає вимозі iss токенів, та постачальник, який повертає помилку на зворотний виклик (наприклад, PKCE, дивіться нижче).
Занадто багато спроб: кінцеві точки входу та зворотних викликів обмежені за частотою (5 запитів на хвилину). Почекайте хвилину та спробуйте ще раз.

4. Чи входить успішно, але ви бачите "Обліковий запис на розгляді", або не можете нічого зробити?

Нові облікові записи створюються з вимкненим статусом, якщо відображення ролей не надає роль. Дивіться Перший вхід та початкове налаштування та Поведінка відображення ролей. Адміністратор також може активувати обліковий запис у Налаштуваннях > Адміністрування > Керування користувачами.

Гілка PKCE¶

Gramps Web вирішує, чи використовувати PKCE, коли починається вхід (дивіться PKCE). Щоб дізнатися, що сталося у вашій налаштуванні, пройдіть через ці питання в порядку:

Чи встановлено OIDC_PKCE? (Для вбудованих постачальників, OIDC_GOOGLE_PKCE або OIDC_MICROSOFT_PKCE.)
- True: PKCE використовується. Перейдіть до питання 3.
- False: PKCE навмисно вимкнено, і документ виявлення постачальника ігнорується. Якщо ваш постачальник вимагає PKCE, видаліть налаштування або встановіть його на True.
- Не встановлено, або пусте: продовжуйте з питання 2.
Чи містить документ виявлення S256? Відкрийте <issuer>/.well-known/openid-configuration і шукайте S256 у code_challenge_methods_supported.
- Так: PKCE використовується автоматично. Продовжте з питання 3.
- Ні, або поле відсутнє: PKCE не використовується. Встановіть OIDC_PKCE на True, якщо ваш постачальник цього вимагає. Також перевірте журнал сервера на наявність Could not check the provider for PKCE support, що означає, що документ виявлення не вдалося отримати, і PKCE тому залишився вимкненим.
Чи дійсно PKCE було надіслано? Розпочніть вхід і подивіться на адресу сторінки входу постачальника (або перше перенаправлення у вкладці мережі вашого браузера). Вона повинна містити code_challenge= та code_challenge_method=S256.
- Присутнє, але вхід все ще зазнає невдачі на зворотному виклику: постачальник відхилив код перевірки. Кукі сесії могли бути втрачені між перенаправленням та зворотним викликом (дивіться гілку 3 вище), або постачальник не підтримує S256, у такому випадку встановіть OIDC_PKCE на False, якщо постачальник не вимагає PKCE.
- Відсутнє: вище наведені налаштування не були застосовані. Перевірте, що змінна середовища має правильний префікс і мале значення (наприклад, GRAMPSWEB_OIDC_PKCE=true у Docker; True не читається як логічне значення), перезапустіть сервер і знову перегляньте конфігурацію.

Note

З увімкненим PKCE у постачальника як необов'язковим, або взагалі не увімкненим, входи працюють незалежно від того, чи надсилає Gramps Web челендж. Лише постачальники (або клієнти), налаштовані на вимогу PKCE, роблять це налаштування важливим.

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

Кастомний 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-client-id"
OIDC_GOOGLE_CLIENT_SECRET="ваш-google-client-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-client-id"
OIDC_GOOGLE_CLIENT_SECRET="ваш-google-client-secret"

# Microsoft OAuth
OIDC_MICROSOFT_CLIENT_ID="ваш-microsoft-client-id"
OIDC_MICROSOFT_CLIENT_SECRET="ваш-microsoft-client-secret"

Pocket ID¶

Створіть OIDC клієнта в Pocket ID з URL-адресою перенаправлення <BASE_URL>/api/oidc/callback/custom (дивіться Обов'язкові URL-адреси перенаправлення). Якщо ви увімкнете "Вимагати PKCE" для клієнта, додаткова конфігурація Gramps Web не потрібна, оскільки Pocket ID рекламує підтримку PKCE у своєму документі виявлення. Потім налаштуйте:

GRAMPSWEB_OIDC_ENABLED=True
GRAMPSWEB_OIDC_ISSUER=https://id.example.com
GRAMPSWEB_OIDC_CLIENT_ID=<ідентифікатор клієнта>
GRAMPSWEB_OIDC_CLIENT_SECRET=<секрет клієнта>
GRAMPSWEB_OIDC_NAME=Pocket ID

Authelia¶

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

Keycloak¶

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

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