iac/apps/auth-flow/CONFIGURATION.md

Конфигурация проекта auth-flow-frontend

Документ описывает способы конфигурирования микрофронтенда аутентификации auth-flow-frontend (React + webpack), а также все переменные сборки, деплоя и рантайма.

Способы конфигурирования

В отличие от бэкенд-сервисов, приложение не читает .env и не использует dotenv. Это статический фронтенд, собираемый webpack, поэтому конфигурация распределена по трём уровням:

1. Сборка (build-time). Переменная ENDPOINT определяет окружение. Её значение подставляется в код на этапе сборки через webpack.DefinePlugin (webpack.config.ts) — заменяет обращения process.env.ENDPOINT и process.env.IS_DEV на строковые литералы. Выбор режима (development/production) и флага isDev выполняется в webpack/build.config.ts.
2. Установка зависимостей. Пакеты @sarex-team/* тянутся из приватного npm-реестра (.npmrc → nexus.infra.sarex.io). Для доступа нужен токен NPM_NEXUS_TOKEN.
3. Рантайм (runtime). Параметры OIDC-провайдера — authority и client_id — читаются из localStorage (src/config/zitadel.ts) по ключам STORAGE.AUTHORITY и STORAGE.CLIENT_ID из @sarex-team/sdk-js. Их задаёт хостовое приложение, а не сборка.

Источники переменных по способам запуска:

Способ запуска	Откуда берутся переменные
Локально (dev)	npm run dev → ENDPOINT=local webpack serve. Dev-сервер на https://localhost:9000
Локально (build)	npm run build → webpack --config webpack.config.ts (по умолчанию ENDPOINT=prod, см. build.config.ts)
Docker	Dockerfile: build-args ENDPOINT и NPM_NEXUS_TOKEN; сборка dist → отдача через nginx
Kubernetes (Helm)	.helm/values.yaml (чарт universal-chart): блок services.frontend, global.env
CI/CD (GitLab)	.gitlab-ci.yml: workflow.rules (ветка/тег → STAND, ENDPOINT, CHART_VERSION), BUILD_ARGS, HELM_SET_ARGS

Переменные сборки (build-time)

Подставляются в код на этапе сборки; в рантайме это уже константы.

Переменная	Тип	Значение по умолчанию	Назначение
ENDPOINT	enum	prod (в build.config.ts, если не задана)	Окружение сборки: local/stage/prod/preprod/contour. Определяет mode (development для local, иначе production) и isDev
IS_DEV	bool	— (вычисляется)	true, если ENDPOINT === 'local'. Включает dev-роуты (/login, /logout, /). Задаётся автоматически через DefinePlugin, вручную указывать не нужно
NPM_NEXUS_TOKEN	string	—	Токен авторизации в приватном npm-реестре @sarex-team (.npmrc). Обязателен для npm i

mode по окружениям (webpack/build.config.ts): local → development, stage/prod/preprod/contour → production. Неизвестное значение ENDPOINT приводит к ошибке сборки.

Переменные рантайма (localStorage)

Читаются в браузере во время работы приложения; задаются хостовым приложением, не сборкой.

Ключ	Источник	Назначение
STORAGE.AUTHORITY	@sarex-team/sdk-js	URL issuer'а Zitadel (authority OIDC). Обязателен — при отсутствии src/config/zitadel.ts бросает Error("Authority or client ID is not set")
STORAGE.CLIENT_ID	@sarex-team/sdk-js	client_id OIDC-клиента. Обязателен (та же проверка)
sarex_logout (LOGOUT_STORAGE_KEY)	src/config/logout.ts	Состояние логаута между вкладками ({ logoutAt, owner, reason }). Снимается только валидным токеном в setTokensInfo
access / refresh / id токены	storage из @sarex-team/sdk-js	Устанавливаются в setTokensInfo (storage.setAccessToken/setRefreshToken/setIdentityToken) после успешного колбэка

Конфигурация OIDC (Zitadel)

Задаётся в src/config/zitadel.ts (configZitadel: ZitadelConfig), клиент создаётся через createZitadelAuth.

Параметр	Значение	Назначение
authority	из localStorage (STORAGE.AUTHORITY)	Issuer Zitadel
client_id	из localStorage (STORAGE.CLIENT_ID)	Идентификатор клиента
response_type	code	Authorization Code Flow
scope	openid profile email offline_access urn:zitadel:iam:user:metadata	Запрашиваемые области
redirect_uri	${window.location.origin}/auth/callback	URL возврата после логина
post_logout_redirect_uri	${window.location.origin}/login	URL после логаута
redirectMethod	replace	Замена записи в истории браузера
revokeTokensOnSignout	false	Не отзывать токены при выходе
automaticSilentRenew	false	Фоновое обновление токенов выключено
validateSubOnSilentRenew	false	—
silentRequestTimeoutInSeconds	100	Таймаут silent-запроса

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

Определены в src/config/urls.ts, диспетчеризация в src/App.tsx.

Роут	Константа	Доступность	Назначение
/auth/callback	CALLBACK	всегда	Обработка OIDC-колбэка (по умолчанию для неизвестных путей)
/auth/error	ERROR	всегда	Страница ошибки аутентификации
/login	LOGIN	только dev	Dev-страница входа
/logout	LOGOUT	только dev	Dev-страница выхода
/	HOME	только dev	Dev-навигация

В production разрешены только /auth/callback и /auth/error (ALLOWED_PATHS); в dev дополнительно /login, /logout, / (ALLOWED_PATHS_DEV). Неразрешённый путь заменяется на /auth/callback (history.replaceState).

Сборка (webpack)

webpack.config.ts + webpack/build.config.ts.

Параметр	Значение	Примечание
entry	src/index.tsx	Точка входа
output.path	dist/
output.filename	index.js
output.publicPath	/ (dev) или /auth/callback/ (prod)	Зависит от isDev
loader	esbuild-loader, target es2015	Для .tsx?/.jsx?
devServer	https, port: 9000, hot, historyApiFallback, open	Только dev
plugins	HtmlWebpackPlugin (public/index.html), DefinePlugin (ENDPOINT, IS_DEV)

Node-версия для разработки: v20.0.0 (.nvmrc; в package.json заявлено v20.0.0, реальная база образа — node:20).

Docker

Dockerfile — двухстадийная сборка.

Стадия	База	Действия
build	cr.yandex/crp3ccidau046kdj8g9q/node:20	npm i (с NPM_NEXUS_TOKEN), npm run build (с ENDPOINT)
runtime	cr.yandex/crp3ccidau046kdj8g9q/nginx:latest	Копирует /app/dist/ → /dist/, nginx/nginx.conf → /etc/nginx/nginx.conf

Build-args: ENDPOINT, NPM_NEXUS_TOKEN.

Nginx

nginx/nginx.conf — отдача статики и healthcheck.

Локация	Поведение
= /auth/callback/index.js	alias /dist/index.js
^~ /auth/callback	try_files $uri $uri/ /index.html; заголовки Cache-Control: no-store,..., кеш отключён
= /ping	200 {"result": "ok"} (healthcheck)

listen 80, root /dist, логи в stdout/stderr, gzip on.

Helm-чарт (.helm/values.yaml)

Деплой через зонтичный чарт universal-chart (oci://cr.yandex/crp3ccidau046kdj8g9q/charts, версия 0.1.7; Chart.yaml приложения — auth-flow-frontend 1.0.0). Значения задаются с ключами по окружениям (_default/stage/preprod/production).

Параметр	Значение	Назначение
global.env	stage (_default в файле)	Активное окружение чарта
services.frontend.enabled	true	Включение сервиса
deployment.name._default	auth-flow-frontend	Имя деплоймента
deployment.replicaCount	_default: 1, production: 2	Число реплик
deployment.port._default	80	Порт контейнера
deployment.revisionHistoryLimit._default	5	Хранимые ревизии
deployment.resources.requests	memory: 128Mi, cpu: 100m	Реквесты ресурсов
deployment.probes.liveness/readiness	httpGet / : 80	Пробы
image.name._default	cr.yandex/crp3ccidau046kdj8g9q/auth-flow-frontend	Образ
image.pullPolicy._default	IfNotPresent
imagePullSecrets.name._default	dockerhub (enabled false)	Секрет реестра
service	ClusterIP, port/targetPort 80, portName http, имя auth-flow-frontend-service	Service
envs	[]	Переменные окружения контейнера (пусто)
volumes._default	[]	Тома
commitSha/gitlabUri/gitlabJobUrl/owner	заполняются из CI (owner по умолчанию team-abc)	Метаданные

CI (.gitlab-ci.yml)

Подключает общие шаблоны generic/common-ci (common-security-scan.yaml, universal-pipeline.yaml ref apps-business).

Базовые переменные: SERVICE_NAME=auth-flow-frontend, DOCKERFILE_PATH=./Dockerfile, CI_TRIGGER_SOURCE=app.

Переключение окружения по workflow.rules:

Условие	STAND	ENDPOINT	CHART_VERSION	K8S_HUSTLER_BRANCH
merge_request_event	—	—	— (ENABLE_BUILD_IMAGE=false)	—
ветка stage	stage	stage	0.0.1-stage	universal-chart-stage
тег (CI_COMMIT_TAG)	production	prod	0.0.1-prod	universal-chart-production

Правило для ветки master → preprod присутствует, но закомментировано. NAMESPACE для всех окружений — platform, RELEASE_NAME/CHART_NAME — ${SERVICE_NAME}.

BUILD_ARGS прокидывают --build-arg ENDPOINT=<env> и --build-arg NPM_NEXUS_TOKEN=${NPM_NEXUS_TOKEN}. HELM_SET_ARGS устанавливают universal-chart.services.frontend.image.name.<env>, global.env, а также commitSha, gitlabUri, gitlabJobUrl, owner.

Замечания и потенциальные проблемы

• Обязательные runtime-параметры. Если в localStorage нет AUTHORITY или CLIENT_ID, src/config/zitadel.ts бросает ошибку при инициализации — приложение не стартует. Эти значения должен положить хостовый сервис до загрузки микрофронтенда.
• Нет .env. Приложение не читает dotenv; process.env.ENDPOINT/IS_DEV существуют только на этапе сборки (замена через DefinePlugin). Значение ENDPOINT задаётся только через CLI/--build-arg/CI.
• publicPath в prod — /auth/callback/: приложение обслуживается nginx под префиксом /auth/callback, что согласовано с redirect_uri OIDC.
• silentRenew отключён намеренно (automaticSilentRenew: false) — обновление токенов не выполняется в фоне.