Files

T

Zimin A.N. d5268b9395 docs: Diplodoc setup + полное руководство интеграции по API

Новая документация-as-code на платформе Diplodoc (Yandex open-source) с
YFM (Yandex Flavored Markdown). Build → static HTML, deployable куда угодно.

Что добавлено:
- package.json + .yfm + toc.yaml — Diplodoc setup, навигация для sidebar
- index.md — главная страница с tabs для разных audiences
- README.md — инструкция для contributors

Раздел integration/api/ — 11 страниц про интеграцию consumers:
- index — обзор + глоссарий
- auth — Keycloak service accounts, scope mapping
- read-endpoints — GET /dictionaries, list/by-key, spatial filters
- events — Kafka outbox топики, partition keys, idempotency, DLQ
- webhooks — HMAC, SSRF guard, retry policy, test ping endpoint
- bitemporal — validFrom/validTo + history, future-dated entries, bulk close/export
- x-references — FK syntax, validation errors, scope hiding, orphan scanner, v2 cascade preview
- caching — TTL / push / snapshot strategies, hybrid pattern
- errors — full error code reference (validation/auth/conflict/server), retry strategy
- best-practices — 33 numbered rules для consumers
- bundle-cuod — все 40 справочников с FK графом и сценариями

Обновлены:
- ops/README.md — link на новую integration/api/, убран inline <br>
- ops/slo.md — broken cross-repo links заменены на text references

Build:
  cd docs && pnpm install && pnpm build
  → ./_dist (20 HTML files, 7.1M)
  pnpm serve  # → http://localhost:8088

CI deploy job для GitLab Pages — в roadmap (см. docs/README.md).

Существующий tech/api-integration.md оставлен в toc как legacy
(содержимое мигрировано + расширено в integration/api/).

2026-05-07 23:19:02 +03:00

3.9 KiB

Raw Blame History

Авторизация

Ordinis принимает JWT от Keycloak realm nstart:

Issuer: https://auth.nstart.space/realms/nstart
Алгоритм: RS256
JWK Set discoverится через /.well-known/openid-configuration

Service account (m2m)

Для backend-to-backend интеграции (типичный сценарий):

Запросить у Ordinis team создание клиента в realm nstart.
Назначить role: ordinis-public / ordinis-internal / ordinis-restricted (по нужному scope, см. ниже).
Получить client_id + client_secret. Хранить в Vault либо secret manager, никогда в коде.

Получение access token

curl -X POST https://auth.nstart.space/realms/nstart/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=altum-backend" \
  -d "client_secret=<SECRET>"

Ответ:

{
  "access_token": "eyJhbGciOi...",
  "expires_in": 300,
  "token_type": "Bearer"
}

{% note warning %}

Кэшируй токен с TTL = expires_in - 30 (буфер на retries) в backend memory. Не делай новый token request на каждый API call — Keycloak rate limits и латентность.

{% endnote %}

Использование

Каждый запрос требует header:

Authorization: Bearer eyJhbGciOi...

Без header → 401 Unauthorized. С невалидным/expired токеном → 401. Token валиден но scope не позволяет доступ к словарю → 403 Forbidden.

Маппинг ролей в DataScope

Ordinis использует трёхуровневый доступ к словарям через scope field в DictionaryDefinition:

Keycloak роль	Доступные scopes
`ordinis-public`	`PUBLIC`
`ordinis-internal`	`PUBLIC` + `INTERNAL`
`ordinis-restricted`	`PUBLIC` + `INTERNAL` + `RESTRICTED`

Альтернативный синтаксис ролей (для compat с другими сервисами в realm): суффикс -PUBLIC|INTERNAL|RESTRICTED (например altum-PUBLIC, geoportal-INTERNAL). Маппинг определяется в ordinis-auth/.../ScopeContext.java.

{% note info %}

Альтум consumer на проде использует role ordinis-internal — доступ к PUBLIC + INTERNAL справочникам. RESTRICTED закрытый только для специально authorized clients.

{% endnote %}

Refresh tokens

client_credentials flow не поддерживает refresh tokens — это m2m flow без user session. Получай новый access token при истечении.

Если используешь user-on-behalf flow (rare для backend) — refresh token работает, см. Keycloak документацию.

Multiple environments

Среда	Issuer	Realm
prod	`https://auth.nstart.space/realms/nstart`	`nstart`
staging	same	same
local	same либо local Keycloak (опц)	same

Один Keycloak realm для всех сред. Service accounts shared (но client_id обычно различается per env: altum-backend-prod, altum-backend-staging).

Troubleshooting

Симптом	Причина	Fix
401 на каждый запрос	Token expired	Refresh с TTL buffer
401 на новый token	Invalid client_secret	Re-fetch у Ordinis team
403 на конкретные dictionaries	Scope mismatch	Запросить upgrade role у Ordinis team
500 от Ordinis	Issuer unreachable / JWK fetch fail	Check `auth.nstart.space` health

Дальше

→ Read-side endpoints — что можно читать с этим токеном.

3.9 KiB Raw Blame History Unescape Escape