Gotcha

SSO и вход через провайдеров

Помимо пароля, Gotcha умеет входить через внешних провайдеров: универсальный OIDC (любой совместимый IdP — Keycloak, Authentik, Auth0 и т.п.), Яндекс ID и VK ID. Каждый провайдер включается независимо переменными окружения сервера — настройка на уровне инсталляции, доступа из UI для неё нет.

Секреты живут только в памяти процесса (в env), в базе не хранятся.

Общий принцип

Провайдер включается булевым флагом *_ENABLED; если он включён, но обязательные для него переменные (client id/secret и т.п.) не заданы — сервер откажется стартовать с понятной ошибкой конфигурации. Включённые провайдеры появляются кнопками входа на странице логина.

Callback (redirect URI), который нужно зарегистрировать в настройках приложения у провайдера, всегда имеет вид:

{GOTCHA_BASE_URL}/auth/oauth/{provider}/callback

где {provider} — oidc, yandex или vk в зависимости от провайдера, а {GOTCHA_BASE_URL} — тот же адрес, что задан в GOTCHA_BASE_URL сервера (например, https://gotcha.example.com). Например, для generic OIDC это будет https://gotcha.example.com/auth/oauth/oidc/callback. URI не конфигурируется отдельно — он всегда строится по этой схеме, поэтому важно зарегистрировать у провайдера точно такой же адрес.

Generic OIDC — пошагово

  1. В консоли своего IdP (Keycloak, Authentik, Auth0, Zitadel и т.п.) заведите новое OAuth/OIDC-приложение (client) типа “confidential”/“web”.
  2. В качестве redirect URI укажите {GOTCHA_BASE_URL}/auth/oauth/oidc/callback — точно так, с вашим реальным GOTCHA_BASE_URL.
  3. Скопируйте Issuer (обычно вида https://idp.example.com/realms/myrealm — базовый адрес, по которому доступен .well-known/openid-configuration), Client ID и Client secret из настроек приложения в IdP.
  4. Задайте переменные окружения сервера:
GOTCHA_OIDC_ENABLED=true
GOTCHA_OIDC_ISSUER=https://idp.example.com/realms/myrealm
GOTCHA_OIDC_CLIENT_ID=<client id из IdP>
GOTCHA_OIDC_CLIENT_SECRET=<client secret из IdP>
GOTCHA_OIDC_SCOPES=openid email profile   # необязательно, это и есть значение по умолчанию
GOTCHA_OIDC_NAME=Corp SSO                 # необязательно, подпись кнопки на /login (по умолчанию "OIDC")
  1. Перезапустите сервер. На странице /login появится кнопка «Войти через {GOTCHA_OIDC_NAME или OIDC}».

Gotcha сам сходит по {issuer}/.well-known/openid-configuration за адресами авторизации/токена и JWKS — вручную их указывать не нужно.

Яндекс ID

  1. Зарегистрируйте приложение в Яндекс OAuth (или ID.Yandex — консоль разработчика Яндекса).
  2. Redirect URI: {GOTCHA_BASE_URL}/auth/oauth/yandex/callback.
  3. Скопируйте ID и Пароль (secret) приложения.
  4. Переменные окружения:
GOTCHA_YANDEX_ENABLED=true
GOTCHA_YANDEX_CLIENT_ID=<ID приложения>
GOTCHA_YANDEX_CLIENT_SECRET=<пароль приложения>

Кнопка на /login подписана «Войти через Яндекс».

VK ID

  1. Зарегистрируйте приложение в кабинете VK ID для разработчиков.
  2. Redirect URI: {GOTCHA_BASE_URL}/auth/oauth/vk/callback.
  3. Скопируйте ID приложения и защищённый ключ (client secret).
  4. Переменные окружения:
GOTCHA_VK_ENABLED=true
GOTCHA_VK_CLIENT_ID=<ID приложения>
GOTCHA_VK_CLIENT_SECRET=<защищённый ключ>

Кнопка на /login подписана «Войти через VK».

Как это работает при входе

  • Если email из провайдера уже привязан к существующему аккаунту (или совпадает с verified email существующего пользователя) — вход сразу выпускает сессию.
  • Если аккаунта с таким email ещё нет — провайдер провизионирует нового пользователя, только если на этот email есть действующее приглашение (см. Приглашение участников); без приглашения вход по email, не заведённому в системе, отклоняется.
  • Из профиля (/profile) залогиненный пользователь может дополнительно привязать провайдера к своему существующему аккаунту тем же потоком (?link=1).

Отличие от enterprise-SSO по домену

Отдельно от этих инстанс-уровневых провайдеров у каждой организации есть собственная опциональная секция SSO в /orgs/{id}/settings (только owner): свой OIDC-провайдер для входа только участников с определённым доменом email, с опцией «enforced» (принудительный SSO для этого домена — пароль и общие провайдеры перестают работать для таких email). Это отдельная возможность уровня организации, не описанная здесь подробно — настраивается прямо в UI, а не через env.

Что дальше

  • Команды и роли — приглашения, без которых новый пользователь через OAuth не заведётся.
  • Конфигурация — остальные серверные переменные окружения.