Единый вход (OIDC)

Единый вход — модуль sso: тариф Enterprise или ключ Pro с отдельно купленным sso. Поддерживается любой провайдер OpenID Connect: Keycloak, Microsoft Entra ID, ADFS, Okta и другие.

Настройка

1. Зарегистрируйте в провайдере конфиденциального клиента с redirect URI:

   https://<адрес kvalli>/api/auth/oidc/callback

2. Задайте переменные окружения:

   KVALLI_PUBLIC_URL=https://kvalli.company.internal
   KVALLI_OIDC_ISSUER=https://keycloak.company.internal/realms/main   # или https://login.microsoftonline.com/<tenant>/v2.0
   KVALLI_OIDC_CLIENT_ID=kvalli
   KVALLI_OIDC_CLIENT_SECRET=...
   KVALLI_OIDC_ROLE_MAPPING=kvalli-admins=admin;qa-leads=lead;engineers=editor
   KVALLI_OIDC_REQUIRE_GROUP=true     # не пускать тех, кто не в одной из групп

3. Перезапустите приложение. На странице входа появится кнопка единого входа.

Переменные

Переменная	Что задаёт	По умолчанию
KVALLI_OIDC_ISSUER	Адрес провайдера	—
KVALLI_OIDC_CLIENT_ID, KVALLI_OIDC_CLIENT_SECRET	Клиент в провайдере	—
KVALLI_OIDC_ROLE_MAPPING	Пары группа=роль через ;. Роли: admin, lead, editor, viewer	—
KVALLI_OIDC_GROUPS_CLAIM	Claim с группами; можно путь через точку, например realm_access.roles для ролей Keycloak	groups
KVALLI_OIDC_DEFAULT_ROLE	Роль для тех, чьи группы ни с чем не совпали (игнорируется при KVALLI_OIDC_REQUIRE_GROUP=true)	viewer
KVALLI_OIDC_REQUIRE_GROUP	Не пускать пользователей вне сопоставленных групп	false
KVALLI_OIDC_AUTO_PROVISION	Создавать аккаунт при первом входе; иначе администратор создаёт его заранее	true
KVALLI_OIDC_SYNC_ROLES	Обновлять роль по группам при каждом входе	true, если задан ROLE_MAPPING
KVALLI_OIDC_LABEL	Текст кнопки	«Single sign-on»
KVALLI_OIDC_SCOPES	Запрашиваемые scope через пробел	openid email profile
KVALLI_OIDC_REDIRECT_URI	Callback, если он отличается от стандартного	<KVALLI_PUBLIC_URL>/api/auth/oidc/callback
KVALLI_OIDC_ALLOW_HTTP	Разрешить провайдера по http — только для тестового провайдера в доверенной сети	false
KVALLI_OIDC_TRUST_EMAIL	Принимать email, который провайдер не отметил подтверждённым, при создании нового аккаунта. Для привязки существующего не используется никогда	false
KVALLI_PASSWORD_LOGIN	false — только единый вход	true

Включённые значения — true или 1. Для KVALLI_PASSWORD_LOGIN выключает только точное значение false.

Неизвестная роль выключает единый вход

Если в KVALLI_OIDC_ROLE_MAPPING указана роль, которой нет, единый вход выключается целиком, а не понижает кого-то молча: страница входа скажет, что он настроен неверно, а лог сервера назовёт роль.

Как сопоставляются аккаунты

Пользователи сопоставляются по subject провайдера.

При первом входе через SSO существующий аккаунт с тем же email, подтверждённым провайдером, привязывается автоматически, только если администратор создал его заранее без пароля и это не администратор. Аккаунт с паролем — включая первого администратора — привязывается так: войдите паролем, затем в том же браузере нажмите кнопку единого входа.

С KVALLI_OIDC_ROLE_MAPPING роли определяет провайдер при каждом входе. Последнего активного администратора автоматически не понижают никогда. KVALLI_OIDC_SYNC_ROLES=false оставляет роли такими, какими их задал администратор в Kvalli после первого входа.

Только единый вход

KVALLI_PASSWORD_LOGIN=false отключает вход по паролю. Это работает только там, где единый вход лицензирован, — установка без SSO не может закрыть себе вход.