Аутентификация¶

Доступ к Milkyway защищён по OAuth 2.0 (Client Credentials Grant). Банк-отправитель получает access token в Keycloak Planet9 и передаёт его в каждом запросе к Milkyway в заголовке Authorization: Bearer <access_token>.

Эта страница описывает, как банку-отправителю получить и использовать токен в окружениях stage и production.

Получение реквизитов¶

Planet9 при подключении создаёт для вас OAuth-клиента в Keycloak и выдаёт пару client_id / client_secret. Самостоятельная регистрация клиента не предусмотрена.

Реквизиты выдаются отдельно для stage и production — это разные realm'ы.
client_secret — секрет: храните его в защищённом хранилище, не коммитьте в репозиторий и не логируйте.
Для смены или отзыва реквизитов обратитесь к команде Planet9.

Окружения¶

Keycloak один на оба окружения; они разделены realm'ами.

Окружение	Realm	Token endpoint
stage	`planet9-stage`	`https://keycloak.ac8o.planet9.ae/realms/planet9-stage/protocol/openid-connect/token`
production	`planet9`	`https://keycloak.ac8o.planet9.ae/realms/planet9/protocol/openid-connect/token`

Полную OIDC-конфигурацию realm'а (endpoints, поддерживаемые алгоритмы, JWKS) можно получить по discovery-URL:

https://keycloak.ac8o.planet9.ae/realms/<realm>/.well-known/openid-configuration

Реквизиты не переносятся между окружениями

client_id / client_secret от stage не работают в production и наоборот. Используйте realm и реквизиты того окружения, к которому обращаетесь.

Получение токена¶

Запрос на token endpoint своего окружения по grant_type=client_credentials (пример для stage):

curl -s -X POST \
  'https://keycloak.ac8o.planet9.ae/realms/planet9-stage/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials' \
  -d 'client_id=<ваш client_id>' \
  -d 'client_secret=<ваш client_secret>'

Для production замените realm planet9-stage на planet9.

Ответ:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...",
  "expires_in": 300,
  "token_type": "Bearer",
  "scope": "..."
}

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

Передавайте полученный access_token в каждом запросе к Milkyway в заголовке Authorization:

curl 'https://<milkyway-api>/payments/v1/precheck' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'

Базовый URL Milkyway API

Адрес Milkyway API для stage и production согласуется при подключении и здесь не приводится — токен из соответствующего realm'а используется против API того же окружения.

Срок жизни и обновление¶

Access token короткоживущий (см. expires_in, в секундах). По истечении запросите новый тем же запросом — Client Credentials Grant не использует refresh token.
Кэшируйте токен и переиспользуйте его до истечения; не запрашивайте новый токен на каждый вызов API. Рекомендуется обновлять токен заранее, с небольшим запасом до expires_in.

sequenceDiagram
    autonumber
    participant S as Банк-отправитель
    participant K as Keycloak
    participant M as Milkyway

    S->>K: POST token (client_credentials)
    K-->>S: access_token (+ expires_in)
    Note over S: Кэшировать до истечения
    S->>M: Запрос + Authorization: Bearer <token>
    M-->>S: Ответ

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

Симптом	Вероятная причина
`401 invalid_client` от Keycloak	Неверные `client_id` / `client_secret` или обращение не в тот realm (перепутано окружение).
`401 Unauthorized` от Milkyway	Токен истёк, отсутствует заголовок `Authorization`, либо токен выдан в другом окружении.
`400 unauthorized_client`	Для клиента не включён Client Credentials Grant — обратитесь к команде Planet9.