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

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/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="your-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="your-google-client-id"
OIDC_GOOGLE_CLIENT_SECRET="your-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="your-client-secret"
OIDC_NAME="Компанійний SSO"

# Google OAuth
OIDC_GOOGLE_CLIENT_ID="your-google-client-id"
OIDC_GOOGLE_CLIENT_SECRET="your-google-client-secret"

# GitHub OAuth
OIDC_GITHUB_CLIENT_ID="your-github-client-id"
OIDC_GITHUB_CLIENT_SECRET="your-github-client-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 → УВІМКНУТО.