Перейти к содержанию

Keycloak и API-key

В закрытом контуре доступны два режима входа:

Режим Где применяется Роли Когда выбирать
Keycloak (OIDC) Managed: Helm, synth-backend + synth-ui ADMIN, USER, LEAD, AUDITOR из IdP Команда, несколько пользователей, единый вход
API-key Standalone и managed Один ключ → ADMIN Изолированный однопользовательский контур, пилот, сервисный доступ

В Helm-чарте режимы взаимоисключающие: при одновременном включении backend.oidc.enabled и backend.auth.apiKey.enabled рендер завершается ошибкой. Выберите один профиль.

Keycloak не входит в поставку

Synth не поставляет Keycloak. IdP разворачивается отдельно в том же контуре (или уже существует). В закрытом контуре Keycloak должен быть доступен backend'у по HTTPS.

Профиль 1. Keycloak (OIDC)

Что настроить в Keycloak

  1. Создайте realm, например synth. Issuer:
https://<keycloak-host>/realms/<realm>
  1. Создайте confidential-клиент synth:
  2. Client authentication — ON;
  3. Standard flow — ON;
  4. Direct Access Grants — ON, если нужен вход по логину/паролю без редиректа;
  5. Valid redirect URIs — https://<synth-host>/auth/callback;

  6. Web origins — https://<synth-host>.

  7. Создайте realm-роли с точными именами admin, user, lead, auditor. Synth приводит их к верхнему регистру и отбрасывает неизвестные имена.

  8. Убедитесь, что мапперы ролей включают id.token.claim и access.token.claim. Если роли есть только в access_token, Synth их прочитает; если нет ни там, ни там — пользователь получит USER.

Secret

kubectl create namespace synth

kubectl -n synth create secret generic synth-secrets \
  --from-literal=SYNTH_OIDC_CLIENT_SECRET='<client-secret>' \
  --from-literal=SYNTH_PROVIDER_OPENAI_API_KEY='<api-key>'

Секрет создаётся вручную, через External Secrets Operator, sealed-secrets или другой принятый способ. Чарт Secret не создаёт.

values-keycloak.yaml

backend:
  oidc:
    enabled: true
    issuer: "https://<keycloak-host>/realms/<realm>"
    clientId: "synth"
    redirectUri: "https://<synth-host>/auth/callback"
  auth:
    apiKey:
      enabled: false
  persistence:
    enabled: true
    size: 10Gi

secrets:
  existingSecret: synth-secrets

ingress:
  enabled: true
  hosts:
    - host: <synth-host>
      paths:
        - path: /
          pathType: Prefix
  tls:
    - secretName: synth-tls
      hosts:
        - <synth-host>

Установка:

helm install synth ./synth-<version>.tgz \
  --namespace synth --create-namespace \
  -f values-keycloak.yaml

CA Keycloak

Если Keycloak подписан внутренним CA, добавьте его в доверие:

# чарт смонтирует CA и выставит NODE_EXTRA_CA_CERTS
caCert: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----

Либо используйте security.tls.existingSecret с ключами CA/клиента. Не отключайте проверку TLS: при неверном CA backend не сможет проверить JWT и обратиться к issuer.

Проверка

curl -fsS https://<keycloak-host>/realms/<realm>/.well-known/openid-configuration

В ответе issuer должен совпадать с backend.oidc.issuer символ в символ. Проверьте также, что redirect URI в Keycloak совпадает с https://<synth-host>/auth/callback.

Профиль 2. API-key

Один ключ даёт роль ADMIN. Это подходит для изолированного инстанса, пилота или сервисного доступа, но не даёт per-user ролей и аудита по пользователям. Для командной работы используйте Keycloak.

Secret

kubectl -n synth create secret generic synth-secrets \
  --from-literal=SYNTH_API_KEY='<api-key>'

values-apikey.yaml

backend:
  oidc:
    enabled: false
  auth:
    apiKey:
      enabled: true
      existingSecret: synth-secrets
      secretKey: SYNTH_API_KEY
  persistence:
    enabled: true
    size: 10Gi

secrets:
  existingSecret: synth-secrets

helm install synth ./synth-<version>.tgz \
  --namespace synth --create-namespace \
  -f values-apikey.yaml

При входе введите ключ в поле API-ключа. Смена ключа — обновить Secret и перезапустить pod'ы backend:

kubectl -n synth get deploy
kubectl -n synth rollout restart deploy/<backend-deployment>

Standalone и контейнеры

В standalone-поставке (portable-бандл, образ synth) используется API-key:

synth serve --api-key '<api-key>'
# или
export SYNTH_API_KEY='<api-key>'
synth serve

Для Docker:

docker run -d --name synth \
  -p 4300:4300 \
  -e SYNTH_API_KEY='<api-key>' \
  -v synth-data:/var/synth/data \
  gitverse.ru/itphx/synth:<version>

OIDC в standalone-контуре не является штатным режимом: для Keycloak разворачивайте managed-профиль (synth-backend + synth-ui). Если вы используете OIDC-переменные в config.yaml, сверяйтесь с разделом SSO / Keycloak.

Переменные окружения

Переменная Назначение
SYNTH_API_KEY Ключ API; в backend даёт роль ADMIN
SYNTH_OIDC_ENABLED true — включить OIDC
SYNTH_OIDC_ISSUER Issuer Keycloak
SYNTH_OIDC_CLIENT_ID Client ID, например synth
SYNTH_OIDC_CLIENT_SECRET Секрет клиента — только из Secret/env
SYNTH_OIDC_REDIRECT_URI https://<synth-host>/auth/callback

Приоритет: CLI-флаги → SYNTH_* → config.yaml → значения по умолчанию.

Частые ошибки

Симптом Причина Решение
Все получают USER, админки нет Маппер ролей не кладёт роли в токен Включить id.token.claim и access.token.claim
Роль есть в Keycloak, в Synth нет Имя роли не из списка Переименовать в admin/user/lead/auditor
redirect_uri mismatch URI в Keycloak не совпадает с values Сверить символ в символ
Backend не проверяет JWT Не доверяет CA Keycloak Настроить caCert/security.tls
401 после смены ключа Pod не перезапущен kubectl rollout restart
В Keycloak «неверный логин» Нет Direct Access Grants Включить grant или использовать редирект

Что дальше