Перейти к содержанию

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")

Много-Деревянные Настройки

На сервере с несколькими деревьями дерево, в которое пользователь входит, должно быть известно до того, как Gramps Web перенаправит на поставщика идентификации, поэтому вход начинается с:

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

tree требуется в много-деревянных настройках; его отсутствие или передача идентификатора дерева, которого не существует, приводит к неудаче входа. На сервере с одним деревом tree является необязательным, но если он указан, он должен соответствовать настроенному TREE.

Идентичность OIDC привязана к точно одной учетной записи Gramps Web, которая, в свою очередь, принадлежит точно одному дереву – вход в другое дерево не удается, вместо этого учетная запись не перемещается. Нет возможности связать одну идентичность у поставщика с учетными записями в нескольких деревьях; пользователи, которым нужен доступ к нескольким деревьям, нуждаются в отдельных идентичностях у поставщика (например, разные имена пользователей или учетные записи).

Warning

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

Обязательные URL-адреса перенаправления

При настройке вашего OIDC-поставщика вы должны зарегистрировать следующий URL-адрес перенаправления:

Для OIDC-поставщиков, которые поддерживают подстановочные знаки: (например, Authentik)

  • https://your-gramps-backend.com/api/oidc/callback/*

Где * является подстановочным знаком регулярного выражения. В зависимости от интерпретатора регулярных выражений вашего поставщика это также может быть .* или подобное. Убедитесь, что регулярные выражения включены, если ваш поставщик этого требует (например, 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 не отправляет атрибут groups

Токены 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) и если адрес уже не используется другой учетной записью; в противном случае вход продолжается без сохранения адреса электронной почты.

Выход из OIDC

Gramps Web поддерживает единую выходную аутентификацию (SSO logout) для 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 или у поставщика идентификации.

Примеры Конфигураций

Пользовательский 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"

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 → ВКЛ.