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

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

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

Огляд

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

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

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

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

Info

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

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

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

  • Google: OIDC_GOOGLE_CLIENT_ID та OIDC_GOOGLE_CLIENT_SECRET
  • Microsoft: OIDC_MICROSOFT_CLIENT_ID та OIDC_MICROSOFT_CLIENT_SECRET
  • GitHub: OIDC_GITHUB_CLIENT_ID та OIDC_GITHUB_CLIENT_SECRET

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

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

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

Ключ Опис
OIDC_ENABLED Логічне значення, чи слід увімкнути аутентифікацію OIDC. Встановіть в True.
OIDC_ISSUER URL-адреса постачальника
OIDC_CLIENT_ID Ідентифікатор клієнта для вашого OIDC постачальника
OIDC_CLIENT_SECRET Секрет клієнта для вашого OIDC постачальника
OIDC_NAME Кастомна назва (необов'язково, за замовчуванням "OIDC")
OIDC_SCOPES OAuth області (необов'язково, за замовчуванням "openid email profile")

Обов'язкові 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/?provider=custom

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

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

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

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

Ключ Опис
OIDC_ROLE_CLAIM Ім'я заяви в OIDC токені, що містить групи/ролі користувача. За замовчуванням "groups"
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_*), існуючі ролі користувачів зберігаються
  • Користувачам призначається найвища роль, на яку вони мають право, на основі їх членства в групах
  • Відображення ролей чутливе до регістру за замовчуванням (залежить від вашого OIDC постачальника)

Вихід з OIDC

Gramps Web підтримує єдиний вихід (SSO logout) для OIDC постачальників. Коли користувач виходить з Gramps Web після аутентифікації через OIDC, він буде автоматично перенаправлений на сторінку виходу постачальника ідентичності, якщо постачальник підтримує end_session_endpoint.

Вихід через бекканал

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

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

Щоб налаштувати вихід через бекканал з вашим постачальником ідентичності:

  1. Зареєструйте кінцеву точку виходу через бекканал у конфігурації клієнта вашого постачальника: 

    https://your-gramps-backend.com/api/oidc/backchannel-logout/

  2. Налаштуйте ваш постачальник для надсилання повідомлень про вихід. Точні кроки залежать від вашого постачальника:

Keycloak:

  • У конфігурації клієнта перейдіть до "Налаштування"
  • Встановіть "URL виходу через бекканал" на https://your-gramps-backend.com/api/oidc/backchannel-logout/
  • Увімкніть "Вихід через бекканал, що вимагає сесію", якщо ви хочете вихід на основі сесії

Authentik:

  • У конфігурації постачальника додайте URL виходу через бекканал
  • Переконайтеся, що постачальник налаштований на надсилання токенів виходу

Термін дії токена

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

Для підвищення безпеки розгляньте:

  • Зменшення часу дії JWT токена (JWT_ACCESS_TOKEN_EXPIRES)
  • Навчання користувачів вручну виходити з Gramps Web при виході з вашого постачальника ідентичності

Як це працює

Коли користувач виходить з вашого постачальника ідентичності або іншого додатку:

  1. Постачальник надсилає logout_token JWT до кінцевої точки виходу через бекканал Gramps Web
  2. Gramps Web перевіряє токен і реєструє подію виходу
  3. JTI токена виходу додається до чорного списку, щоб запобігти атакам повторного використання
  4. Будь-які нові API запити з JWT користувача будуть відхилені, як тільки токени закінчаться

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

Кастомний 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_TLS=True
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-ідентифікатор-клієнта"
OIDC_GOOGLE_CLIENT_SECRET="ваш-google-секрет-клієнта"

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

Ви можете одночасно увімкнути кілька 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-ідентифікатор-клієнта"
OIDC_GOOGLE_CLIENT_SECRET="ваш-google-секрет-клієнта"

# GitHub OAuth
OIDC_GITHUB_CLIENT_ID="ваш-github-ідентифікатор-клієнта"
OIDC_GITHUB_CLIENT_SECRET="ваш-github-секрет-клієнта"

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 → УВІМКНУТО.