Корпоративный вход за вечер (SSO)

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

🎯 Задача

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

💡 Решение

Настроить единственный OIDC-коннектор в .env, включить JIT-провижининг по списку доменов, а затем SSO_ENFORCE с заранее заполненным break-glass. Справочник по каждому параметру — Корпоративный вход (SSO); здесь мы проходим его по порядку.

📝 Что понадобится

  • Доступ к серверу box: правка .env и перезапуск через ./doqa.
  • Клиент (application), заведённый в вашем IdP — Keycloak, AD FS или Entra (Azure AD): client_id, client_secret и разрешённый redirect URI.
  • Список email для break-glass — учётные записи с локальным паролем, которым вход остаётся при недоступном провайдере.

⏱ Время: ≈40 мин

Шаг 1. Прописать OIDC в .env

Параметры SSO_* в поставляемый шаблон не входят — добавьте строки в .env вручную (см. раздел Аутентификация). Возьмите значения из карточки клиента в вашем IdP:

SSO_ENABLED=true
SSO_ISSUER=https://idp.company.ru/realms/company
SSO_CLIENT_ID=doqa
SSO_CLIENT_SECRET=<секрет клиента из IdP>
SSO_REDIRECT=https://doqa.company.ru/api/auth/sso/callback
SSO_SCOPES="openid email profile"
SSO_LABEL="Corporate SSO"

SSO_ISSUER — это базовый адрес провайдера. Остальные endpoint'ы (authorize, token, jwks) DoQA читает сама по {issuer}/.well-known/openid-configuration, отдельно их указывать не нужно. SSO_REDIRECT должен совпадать с адресом https://<APP_URL>/api/auth/sso/callback и быть в списке разрешённых redirect URI на стороне IdP.

Перезапустите приложение, чтобы .env применился:

./doqa stop && ./doqa start

✅ Результат: на странице входа появилась кнопка «Корпоративный вход (SSO)». Форма логина и пароля пока остаётся рядом — оба способа работают одновременно. Детали и тонкая настройка кэшей/таймаутов — раздел Включение.

Шаг 2. Включить автоматическое создание учётных записей (JIT)

Без JIT войти смогут только те, кого вы завели заранее. Чтобы сотрудник появлялся при первом входе, добавьте:

SSO_JIT_ENABLED=true
SSO_JIT_MODE=domain_allowlist
SSO_JIT_ALLOWED_DOMAINS=company.ru

domain_allowlist создаёт учётную запись только для email из SSO_JIT_ALLOWED_DOMAINS; значение open пропустит любого, кого вернул провайдер. Отдельного значения «выключено» у SSO_JIT_MODE нет — за это отвечает SSO_JIT_ENABLED. Домены перечисляются через запятую или пробел.

Роль нового пользователя — «просмотр», всегда. Роли из провайдера не читаются и не синхронизируются: права в DoQA древовидные, по проектам и пространствам, их выдаёт администратор внутри продукта (это Шаг 5).

Перезапустите приложение после правки.

✅ Результат: сотрудник с доменом из списка, войдя через провайдера впервые, заводится сам с ролью «просмотр» и без локального пароля. Порядок сопоставления и создания — Автоматическое создание пользователей (JIT).

Шаг 3. Собрать break-glass и включить enforce

SSO_ENFORCE=true запрещает вход по локальному паролю тем, кто считается управляемым через SSO (домен из SSO_JIT_ALLOWED_DOMAINS или есть привязанная внешняя учётная запись), и скрывает форму логина. Автоматических исключений нет — владелец инстанса и суперадмин попадают под enforce на общих основаниях.

Поэтому сначала заполните аварийный список, и только потом включайте enforce:

SSO_ENFORCE=true
SSO_BREAKGLASS_EMAILS=admin@company.ru

Убедитесь, что у перечисленных учётных записей задан пароль. Задать его можно из консоли сервера (ввод скрытый):

docker compose exec api php artisan users:set-password admin@company.ru

Форма пароля под enforce скрыта, но не удалена: чтобы открыть её для break-glass, добавьте к адресу входа ?password — https://<APP_URL>/auth/login?password. Вход по этой форме пройдёт только для email из SSO_BREAKGLASS_EMAILS.

Перезапустите приложение.

✅ Результат: SSO-управляемые пользователи заходят только через провайдера, форма пароля на обычной странице входа скрыта, а у break-glass остаётся аварийный вход. Подробно — Обязательный вход через SSO (enforce).

Шаг 4. Проверить вход

  1. Откройте страницу входа. Нет кнопки «Корпоративный вход (SSO)» — значит SSO_ENABLED не применился: проверьте, что приложение перезапущено после правки .env.
  2. Нажмите кнопку — браузер должен уйти на страницу аутентификации провайдера.
  3. Войдите рабочей учётной записью. Провайдер вернёт вас в DoQA.

Если вместо возврата страница показывает «Не удалось войти через внешнего провайдера», причина — в адресной строке параметром error=sso_* и в логах (docker compose logs -f api). Расшифровка кодов и порядок диагностики — Проверка настройки.

✅ Результат: сотрудник вошёл через корпоративный провайдер и оказался в DoQA. Если он завёлся впервые — он в списке пользователей с ролью «просмотр».

Шаг 5. Выдать роли и лицензии

Пользователь, созданный через JIT, места в лицензии не занимает и прав на редактирование не имеет. Дальше всё делается внутри продукта, во вкладке «Пользователи» панели администратора:

✅ Результат: сотрудник входит по корпоративной кнопке, назначен на слот и имеет нужные права. Инсталляция переведена на корпоративный вход.

⚠️ Возможные трудности

Включили SSO_ENFORCE=true с пустым SSO_BREAKGLASS_EMAILS. При недоступном провайдере в DoQA не сможет войти никто: паролем вход запрещён, а через провайдера он не проходит. Восстановить доступ можно будет только правкой .env на сервере и перезапуском. Заполняйте break-glass до включения enforce и проверяйте, что у этих учётных записей задан пароль.

Опечатка в SSO_JIT_MODE. Любое значение, кроме domain_allowlist и open, молча ломает вход новым сотрудникам: пользователи не создаются вообще, а во входе отказывается без внятной причины (в логах — error=sso_not_allowed). Проверьте написание значения по буквам.

SSO_JIT_MODE=open шире, чем кажется. Учётную запись в DoQA получит каждый, кто может войти в ваш провайдер. Убедитесь, что круг пользователей IdP совпадает с кругом сотрудников, которым нужен DoQA, иначе оставайтесь на domain_allowlist.

Кнопки SSO нет после правки .env. Приложение не перезапущено либо SSO_ENABLED не true. Параметры SSO_* в шаблон .env не входят — проверьте, что строка добавлена вручную, и повторите ./doqa stop && ./doqa start.

📚 Смотрите также

Последнее обновление: