Интеграция с Keycloak (OIDC SSO)

qf-cp поддерживает вход операторов через внешнего OIDC-провайдера. В этом гайде настройка разобрана на примере Keycloak. Для другого OIDC-совместимого провайдера понадобятся те же параметры qf-cp, но другие экраны настройки IdP.

При включённом OIDC оператор входит через провайдера, а qf создаёт для него локальную учётную запись при первом входе. Локальный вход по логину и паролю продолжает работать параллельно.

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

1. Оператор открывает /auth/oidc/login → qf перенаправляет его к провайдеру.
2. После аутентификации провайдер возвращает код на /auth/oidc/callback.
3. qf проверяет ID-токен, находит или создаёт пользователя по email, привязывает учётную запись к sub и выдаёт сессию.
4. Роль qf определяется по группам из токена (см. Маппинг ролей).

Требования к токену:

• Есть claim email, и email_verified = true. Иначе вход отклоняется (403) — непроверенный email мог бы позволить выдать себя за чужую учётку.
• preferred_username необязателен: без него qf использует часть email до @.

Настройка на стороне Keycloak

1. Realm

Подходит существующий realm; при необходимости создаётся новый через Create realm. Пользователи qf должны находиться в этом realm и иметь подтверждённый email.

2. Client

Клиент создаётся через Clients → Create client:

Поле	Значение
Client type	OpenID Connect
Client ID	Например, qf-cp; значение задаётся в QF_OIDC_CLIENT_ID
Client authentication	On (confidential — qf хранит client secret)
Standard flow	On (authorization code)
Valid redirect URIs	https://<адрес-cp>/auth/oidc/callback
Web origins	https://<адрес-cp>

<адрес-cp> — внешний адрес, по которому оператор открывает Web UI (он же QF_CP_HOST). Redirect URI должен точно совпадать с тем, что анонсирует qf (QF_OIDC_REDIRECT_URL, по умолчанию путь /auth/oidc/callback).

После создания значение Credentials → Client secret переносится в QF_OIDC_CLIENT_SECRET.

Scope email и profile включены в клиенте по умолчанию — этого достаточно для claim'ов email / email_verified / preferred_username.

3. Группы и маппер (для ролей)

Для автоматического сопоставления групп с ролями нужны группы и protocol mapper. Без них действует поведение без карты групп.

1. Groups → Create group — группы под роли qf, например qf-admins, qf-editors, qf-auditors.

2. Protocol mapper, который добавляет группы в токен: Clients → qf-cp → Client scopes → qf-cp-dedicated → Add mapper → By configuration → Group Membership.

   Поле маппера	Значение
   Name	напр. groups
   Token Claim Name	groups (должно совпадать с QF_OIDC_ROLE_CLAIM)
   Full group path	Off — claim несёт имя группы (qf-admins); On — полный путь (/qf-admins)
   Add to ID token	On

   Значение «Full group path» определяет, что писать в QF_OIDC_GROUP_ROLE_MAP: имя (qf-admins) при Off, путь (/qf-admins) при On.

3. Пользователи добавляются в группы через Users → … → Groups → Join.

Настройка на стороне qf-cp

qf-cp читает параметры OIDC из переменных окружения. Полный список находится в справочнике конфигурации CP. OIDC включается, только когда заданы три обязательные переменные:

Переменная	Назначение
QF_OIDC_ISSUER	URL issuer realm'а, напр. https://<keycloak>/realms/<realm>
QF_OIDC_CLIENT_ID	Client ID из шага 2
QF_OIDC_CLIENT_SECRET	Client secret из шага 2
QF_OIDC_REDIRECT_URL	Полный callback-URL https://<адрес-cp>/auth/oidc/callback (по умолчанию — путь /auth/oidc/callback)
QF_OIDC_ROLE_CLAIM	Claim с группами; по умолчанию groups
QF_OIDC_GROUP_ROLE_MAP	Маппинг групп в роли (см. ниже)

Issuer должен быть доступен CP по сети, а его OIDC-discovery (<issuer>/.well-known/openid-configuration) — резолвиться. Если CP за reverse-прокси на подпути, issuer в токене и конфигурации qf-cp должны совпадать.

Проверить, что OIDC поднялся: GET /auth/oidc/enabled вернёт {"enabled":true}.

Маппинг групп в роли

Роли qf: admin (полный доступ), editor (создание/правка политик и объектов), auditor (только чтение).

QF_OIDC_GROUP_ROLE_MAP — список пар группа:роль через запятую, роль только из admin/editor/auditor (неверные пары игнорируются):

QF_OIDC_GROUP_ROLE_MAP=qf-admins:admin,qf-editors:editor,qf-auditors:auditor

Поведение:

• Маппинг задан → IdP источник истины. Роль пересчитывается по группам при каждом входе. При нескольких совпавших группах берётся высшая привилегия. Нет совпадений — назначается auditor (наименьшие права).
• Маппинг не задан. Новый OIDC-пользователь получает auditor, существующий сохраняет уже назначенную ему в qf роль (роль правится вручную админом).
• Bootstrap-админ исключён. Учётка с email из QF_ADMIN_EMAIL группами не понижается — mis-scoped IdP не заблокирует встроенного администратора.

Значения ключей в карте должны дословно совпадать с тем, что кладёт маппер (имя или путь, см. «Full group path»).

Проверка входа и роли

1. GET /auth/oidc/enabled → {"enabled":true}.
2. Переход в браузере на /auth/oidc/login открывает страницу входа Keycloak.
3. После входа роль пользователя в разделе Users должна соответствовать его группе.

Диагностика ошибок входа

Симптом	Причина
/auth/oidc/enabled = false	Не заданы все три: issuer/client_id/client_secret
Ошибка на старте CP «oidc provider»	Issuer недоступен или discovery не резолвится
invalid state / 403 email not verified	У пользователя в IdP нет verified email
redirect_uri mismatch на экране Keycloak	Valid redirect URIs ≠ QF_OIDC_REDIRECT_URL
Все пользователи получают auditor	QF_OIDC_GROUP_ROLE_MAP пуст; ключи не совпадают со значением из mapper из-за настройки Full group path; либо mapper не добавлен в ID-токен

См. также

• cp-config.md — полный справочник параметров CP, раздел «OIDC SSO».
• install.md — развёртывание control plane.