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). См. Файл конфигурации против переменных окружения для получения подробной информации.

Встроенные Поставщики¶

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.

Выход через Backchannel¶

Gramps Web реализует спецификацию OpenID Connect Back-Channel Logout. Это позволяет поставщикам идентификации уведомлять Gramps Web, когда пользователь выходит из другой программы или самого поставщика идентификации.

Конфигурация¶

Чтобы настроить выход через backchannel с вашим поставщиком идентификации:

Зарегистрируйте конечную точку выхода через backchannel в конфигурации клиента вашего поставщика идентификации:
```
https://your-gramps-backend.com/api/oidc/backchannel-logout/
```
Настройте вашего поставщика на отправку уведомлений о выходе. Точные шаги зависят от вашего поставщика:

Keycloak:

В конфигурации вашего клиента перейдите в "Настройки"
Установите "Backchannel Logout URL" на https://your-gramps-backend.com/api/oidc/backchannel-logout/
Включите "Backchannel Logout Session Required", если вы хотите выход на основе сессии

Authentik:

В конфигурации вашего поставщика добавьте URL-адрес выхода через backchannel
Убедитесь, что поставщик настроен на отправку токенов выхода

Истечение Токена

Из-за безгосударственной природы JWT токенов, выход через backchannel в настоящее время фиксирует событие выхода, но не может немедленно отозвать уже выданные JWT токены. Токены останутся действительными до их истечения (по умолчанию: 15 минут для токенов доступа).

Для повышения безопасности рассмотрите возможность:

Уменьшения времени истечения токена JWT (JWT_ACCESS_TOKEN_EXPIRES)
Обучения пользователей вручную выходить из Gramps Web при выходе из вашего поставщика идентификации

Как Это Работает

Когда пользователь выходит из вашего поставщика идентификации или другого приложения:

Поставщик отправляет logout_token JWT на конечную точку выхода через backchannel Gramps Web
Gramps Web проверяет токен и фиксирует событие выхода
JTI токена выхода добавляется в черный список, чтобы предотвратить атаки повторного воспроизведения
Любые новые 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-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"

# GitHub OAuth
OIDC_GITHUB_CLIENT_ID="ваш-github-client-id"
OIDC_GITHUB_CLIENT_SECRET="ваш-github-client-secret"

Authelia¶

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

Keycloak¶

Большинство конфигураций для Keycloak можно оставить по умолчанию (Клиент → Создать клиента → Аутентификация клиента ВКЛ). Есть несколько исключений:

Область OpenID – Область openid не включена по умолчанию во всех версиях Keycloak. Чтобы избежать проблем, добавьте ее вручную: Клиент → [Клиент Gramps] → Области клиента → Добавить область → Имя: openid → Установить по умолчанию.
Роли – Роли могут быть назначены либо на уровне клиента, либо глобально для каждого реалма.
- Если вы используете клиентские роли, установите параметр конфигурации OIDC_ROLE_CLAIM на: resource_access.[gramps-client-name].roles
- Чтобы сделать роли видимыми для Gramps, перейдите в Области клиентов (верхний уровень, а не под конкретным клиентом), затем: Роли → Мапперы → клиентские роли → Добавить в userinfo → ВКЛ.