Перейти к основному содержимому
Версия: 2.0 (WIP)

OIDC

OpenID Connect (OIDC) — это стандарт аутентификации поверх OAuth 2.0.
Он позволяет пользователю входить в одно приложение с учётной записью, которая хранится у внешнего провайдера (Google, GitLab, Keycloak, корпоративный SSO и т.п.).

В типичном сценарии участвуют три стороны:

  1. Пользователь — тот, кто хочет войти в систему.
  2. OIDC‑провайдер (IdP) — сервис, который знает, кто такой пользователь
    (хранит логин/пароль, выполняет 2FA и т.п.).
  3. Наша система — «клиент» (relying party), которая доверяет результатам аутентификации провайдера.

Процесс входа выглядит так:

  1. Пользователь на странице входа выбирает внешнего провайдера (например, «Войти через GitLab»).
  2. Система перенаправляет пользователя на страницу логина провайдера.
  3. Пользователь вводит логин/пароль (и, при необходимости, 2FA) уже у провайдера.
  4. После успешной аутентификации провайдер возвращает пользователя назад в систему с одноразовым кодом.
  5. Система по этому коду запрашивает у провайдера:
  • ID‑токен (подписанный JWT с информацией о пользователе);
  • при необходимости — access token и user info.
  1. На основании этих данных система:
  • определяет, какого локального пользователя они соответствуют;
  • создаёт нового пользователя (если это разрешено и он ещё не существует);
  • заполняет / обновляет его атрибуты.

Настройка подключения OIDC на этой странице как раз определяет:

  • с каким провайдером и по каким URL работать;
  • какие клиенские учётные данные (Client ID / Secret) использовать;
  • какие данные пользователя запрашивать у провайдера;
  • как эти данные преобразовывать в локальный логин и атрибуты пользователя.

Что нужно подготовить на стороне провайдера​

Перед настройкой подключения убедитесь, что у вас есть:

  1. Созданный OIDC‑клиент в панели управления провайдера.
  2. Client ID и (при необходимости) Client Secret этого клиента.
  3. Discovery URL провайдера (обычно заканчивается на
    /.well-known/openid-configuration), либо URL его отдельных endpoint’ов.
  4. Разрешённый redirect URI (callback‑адрес нашей системы) —
    точное значение берётся из документации или подсказки в интерфейсе и должно быть скопировано в настройки клиента на стороне провайдера.
  5. Понимание, какие scopes (openid, email, profile и т.п.) нужно запрашивать.

Поля настройки подключения​

Ниже перечислены основные поля и их смысл. Названия соответствуют подписям в форме.

Основная информация​

Отображаемое имя
Имя подключения, которое будут видеть пользователи на странице входа
(например: Google, gitlab.com, Корпоративный SSO).

  • Можно менять в любое время — это чисто «человеческое» название.

Название
Уникальный идентификатор подключения внутри системы.
Часто совпадает с техническим именем клиента на стороне провайдера
(например: gitlab_com или corp_oidc).

  • Используется в системе и API.
  • Обычно после создания менять нельзя (или нежелательно).

Учётные данные​

Client ID
Идентификатор клиента, выданный провайдером при регистрации приложения.

  • Копируется из настроек клиента на стороне IdP.
  • Обязателен.

Client Secret
Секрет клиента (пароль приложения), выданный провайдером.

  • Обязателен для конфиденциальных клиентов.
  • При редактировании подключения:
    • если поле оставить пустым, уже сохранённый секрет не изменится;
    • чтобы сменить секрет, введите новое значение и сохраните.

Метод аутентификации
Определяет, как client_id и client_secret передаются провайдеру
при запросе токена (token endpoint).

Типичные сценарии:

  • Public client — без client_secret (например, при использовании PKCE).
  • Другие варианты — разные способы передачи секрета (client_secret_basic, client_secret_post и т.п., зависят от реализации).

Выберите вариант, который указан в документации к вашему провайдеру.

Конфигурация подключения​

Discovery URL (.well-known)
Адрес точки авто‑конфигурации провайдера.

Примеры:

  • https://accounts.google.com/.well-known/openid-configuration
  • https://idp.example.com/realms/main/.well-known/openid-configuration

По этому URL система автоматически получает:

  • issuer;
  • URL авторизации (authorization endpoint);
  • URL выдачи токенов (token endpoint);
  • URL UserInfo;
  • URL JWK‑ключей и т.п.

Если ваш провайдер не поддерживает Discovery или нужно переопределить настройки, используйте расширенные настройки и задайте endpoint’ы вручную (адреса берутся из документации провайдера).

Дополнительные параметры​

Scopes
Список областей доступа (scopes), которые запрашивает наша система у провайдера.
Указываются через пробел.

  • Обязательно должен присутствовать openid.
  • Часто используются:
    • email — доступ к адресу электронной почты;
    • profile — базовая информация профиля (имя, фамилия, аватар и т.п.).

Примеры значений:

  • openid
  • openid email
  • openid profile email

Проверять SSL‑сертификат
Переключатель, определяющий, нужно ли проверять TLS‑сертификат провайдера.

  • Включено — сертификат проверяется, соединение только к «доверенным» серверам.
    Рекомендуется для любых боевых систем.
  • Выключено — проверки отключены (допускаются самоподписанные сертификаты и т.п.).
    Допустимо только для тестовых стендов.

Активировать подключение
Определяет, будет ли подключение доступно пользователям.

  • Включено — пользователи могут выбирать это подключение на странице входа.
  • Выключено — настройки сохранены, но подключение не используется.

JQ‑выражение для логина​

Поле отвечает за то, как из данных провайдера получить логин пользователя в системе.

Смысл параметра

  • В поле задаётся jq‑выражение.
  • Оно применяется к объекту user info (или к claims ID‑токена).
  • Результат выражения записывается в поле login локального пользователя.
  • По этому login пользователь сопоставляется с уже существующими записями в системе.

Рекомендуемый плейсхолдер: .email.

Типичные примеры:

  • .email
    Использовать email пользователя как логин.

  • .preferred_username // .email
    Использовать preferred_username, а если его нет — email.

  • (.email | ascii_downcase)
    Логин = email в нижнем регистре (удобно, если локальные логины хранятся без учёта регистра).

Если выражение настроено некорректно (например, не возвращает строку),
пользователь может не найтись в системе или не создаться.

Сопоставление атрибутов пользователя​

Этот блок управляет тем, какие поля профиля провайдера будут записаны в атрибуты пользователя в системе и когда они будут обновляться.

Поля строки атрибута​

Название*
Имя атрибута в нашей системе.
Примеры: email, full_name, department, phone.

Выражение*
Выражение (как правило, в синтаксисе jq), применяемое к JSON‑объекту user info.
Результат станет значением атрибута.

Примеры:

  • .email
  • .name
  • .given_name + " " + .family_name
  • .groups[] | select(startswith("team-"))

Тип синхронизации (sync_type)*
Определяет, когда и как обновлять атрибут из данных провайдера:

  • DISABLE — Синхронизация выключена
    Значение атрибута не меняется автоматически.
    Можно использовать, если атрибут должен управляться только внутри системы.

  • PERIODIC — Обновлять периодически
    Атрибут пересчитывается и перезаписывается при каждом обновлении информации от провайдера
    (например, при продлении токена / обновлении user info).
    Удобно для полей, которые должны всегда отражать текущее состояние в IdP (департамент, должность и т.д.).

  • ON_CREATE — Только при создании пользователя
    Атрибут заполняется один раз при первом входе пользователя через OIDC,
    затем автоматически не обновляется.
    Полезно для полей, которые не должны «переезжать» при изменении профиля в IdP.

  • IF_EXIST — Обновлять только если значение пришло от провайдера
    Атрибут перезаписывается только если выражение дало непустой результат
    (IdP прислал реальное значение, а не null).

    Особенность:

    • В обычных режимах, если провайдер возвращает null / отсутствующий атрибут, это может трактоваться как удаление значения и оно стирается в системе.
    • В режиме IF_EXIST, если значение не пришло, текущее значение в системе сохраняется.

Типичный порядок настройки подключения OIDC​

  1. На стороне OIDC‑провайдера:
  • создать клиента;
  • взять Client ID и Client Secret;
  • указать корректный redirect URI системы;
  • при необходимости настроить набор scopes.
  1. В настройках системы:
  • заполнить Отображаемое имя и Название подключения;
  • ввести Client ID и, при необходимости, Client Secret;
  • указать Discovery URL (или настроить endpoint’ы вручную);
  • выбрать Метод аутентификации в соответствии с документацией провайдера;
  • задать нужные Scopes (обязательно openid);
  • настроить JQ‑выражение для логина (обычно .email);
  • задать необходимые атрибуты в блоке Сопоставление атрибутов и выбрать для них подходящий sync_type;
  • при необходимости отключить проверку SSL‑сертификата (для тестовых стендов);
  • включить флаг Активировать подключение.

  1. Нажать «Протестировать соединение» и убедиться, что конфигурация корректна.

  2. Сохранить изменения и при необходимости проверить вход с тестовой учётной записью провайдера.