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

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

Обзор¶

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

Использовать внешние поставщики идентификации для аутентификации пользователей
Поддерживать несколько поставщиков аутентификации одновременно
Сопоставлять группы/роли OIDC с ролями пользователей Gramps Web
Реализовать единую регистрацию (SSO) и единую выход (Single Sign-Out)
При необходимости отключить локальную аутентификацию по имени пользователя/паролю

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

Чтобы включить аутентификацию 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/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, когда пользователь выходит из другой программы или самого поставщика идентификации.

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

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

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

Keycloak:

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

Authentik:

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

Истечение срока действия токена

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

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

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

Как это работает

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

Поставщик отправляет JWT logout_token на конечную точку выхода через обратный канал 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 → ВКЛ.