iac/apps/auth-flow/ENDPOINTS.md

Эндпоинты, с которыми взаимодействует auth-flow-frontend

Документ описывает внешние эндпоинты, внутренние роуты и каналы межвкладочной коммуникации микрофронтенда аутентификации auth-flow-frontend.

Как устроено взаимодействие

Приложение отвечает только за аутентификацию по протоколу OIDC (Authorization Code Flow + PKCE). Прямых REST-запросов к бэкенд-сервисам Sarex у него нет — всё сетевое взаимодействие идёт с провайдером идентификации Zitadel через обёртку @sarex-team/sdk-js/zitadel (поверх oidc-client).

Клиент создаётся в src/config/zitadel.ts (createZitadelAuth(configZitadel)). Базовый адрес провайдера (authority, issuer) и client_id берутся из localStorage во время работы, а не задаются сборкой. OIDC-клиент сам находит конкретные эндпоинты issuer'а через discovery-документ /.well-known/openid-configuration.

Провайдер идентификации (Zitadel) по окружениям

Фактический authority подставляется хостовым приложением через localStorage (STORAGE.AUTHORITY) — в самом auth-flow-frontend хосты не захардкожены. Ниже — известные для платформы Sarex значения (справочно):

Окружение	authority (issuer)
stage	https://idp.dev.stage.sarex.io
prod	https://login.sarex.io

OIDC-эндпоинты провайдера

Обнаруживаются через discovery и вызываются oidc-client относительно authority. Итоговые пути определяются метаданными issuer'а.

Эндпоинт (метаданные)	Метод	Где инициируется	Назначение
/.well-known/openid-configuration	GET	инициализация UserManager	Discovery метаданных провайдера
authorization_endpoint	GET (redirect)	LoginPage → zitadel.authorize()	Старт авторизации, редирект на форму входа
token_endpoint	POST	AuthCallbackPage → zitadel.userManager.signinCallback()	Обмен code → access/refresh/id токены
jwks_uri	GET	oidc-client	Ключи для проверки подписи токенов
userinfo_endpoint	GET	oidc-client (при необходимости)	Профиль пользователя
end_session_endpoint	GET (redirect)	LogoutPage → zitadel.signout()	Завершение сессии (логаут)

Параметры OIDC-запросов (из configZitadel):

• response_type: code
• scope: openid profile email offline_access urn:zitadel:iam:user:metadata
• redirect_uri: ${window.location.origin}/auth/callback
• post_logout_redirect_uri: ${window.location.origin}/login
• revokeTokensOnSignout: false, automaticSilentRenew: false

Внутренние роуты приложения

Диспетчеризация — в src/App.tsx по window.location.pathname (роуты из src/config/urls.ts).

Роут	Страница	Метод	Назначение
/auth/callback	AuthCallbackPage	—	Обработка OIDC-колбэка: signinCallback(), установка токенов, рассылка события в login_channel. Дефолт для неизвестных путей
/auth/error	AuthErrorPage	—	Отображение ошибки аутентификации (параметры error, error_description, state, message из query)
/login	LoginPage (dev)	—	Кнопка входа (zitadel.authorize())
/logout	LogoutPage (dev)	—	Кнопка выхода (zitadel.signout())
/	MainPage (dev)	—	Dev-навигация (login/logout)
/ping	nginx	GET	Healthcheck, отдаёт {"result": "ok"}

Поток аутентификации (кратко)

1. LoginPage вызывает zitadel.authorize() → редирект на authorization_endpoint Zitadel.
2. Провайдер возвращает пользователя на redirect_uri = /auth/callback с code.
3. AuthCallbackPage вызывает signinCallback() → обмен code на токены через token_endpoint.
4. Токены сохраняются (setTokensInfo → storage.setAccessToken/setRefreshToken/setIdentityToken), снимается флаг логаута.
5. Результат рассылается остальным вкладкам, происходит закрытие overlay-окна (window.opener) или переход на / (HOME).
6. При ошибке — редирект на /auth/error с деталями.

Межвкладочная и оконная коммуникация

Канал	Ключ / имя	Назначение
BroadcastChannel	login_channel	Сообщения { type: "login_success" } и { type: "login_error", reason } между вкладками
localStorage	sarex_logout (LOGOUT_STORAGE_KEY)	Состояние логаута между вкладками (logoutAt, owner, reason)
window events	setTokensInfoIntoWindowEvents (@sarex-team/sdk-js)	Оповещение хостового приложения об обновлении токенов (reason: "auth_callback")
window.opener	—	Режим overlay: после успешного входа окно закрывается (window.close())

Обработка ошибок

Логика — в src/utils/authError.ts; отображение — AuthErrorPage.

• Параметры ошибки читаются из query-строки колбэка: error, error_description, state, message (parseAuthErrorFromSearch).
• Причина ошибки: error_description → message → error → "Unknown error" (getAuthErrorReason).
• URL страницы ошибки собирается buildAuthErrorUrl (query из непустых параметров, иначе просто /auth/error).
• Если контекста ошибки нет — редирект на / (HOME).
• Пользователю доступны кнопки «Скопировать детали ошибки» (formatAuthErrorForCopy) и «Вернуться на форму входа» (/login), а также ссылка в поддержку mailto:support@sarex.io.