Авторизаційні запити

How to log in to the system with an employee credentials

Зміст сторінки

Опис

Для обміну API запитами банк має реалізувати можливість аутентифікуватися та авторизуватися на платформі Прозорої Мережі.

JWT токен має бути підписано банком для будь-якого запиту на кроці 1 (див. малюнок)

Додатковий крок 3 також має бути підписано банком.

Як імплементувати сервіс авторизації за JWT?

Зразок схеми реєстрації клієнта.

  • Як зазначено на схемі, на кроці 2 банк генерує JWT (зазначено блакитним) і відправляє його на кроці 5 у заголовку CX-Authorization.

  • На кроці 6 DCM перевіряє та валідує JWT

  • Згодом, на кроці 7 DCM формує власний JWT та надсилає його до Банку API endpoint /user_auth у заголовку X-Session-ID.

  • На кроці 8 банк перевіряє чи значення з X-Session-ID підписане ключем DCM

Кроки 3-4 не обов'язкові та можуть використовуватися для перевірки валідності JWT.

Update a JWK

Початковий JWK зареєстровано на платформі Прозорої Мережі під час функціональної інтеграції та розгортання тестового середовища.

Щойно строк дії вашого ключа сплив, необхідно зареєструвати новий JWT ключ за допомогою даного методу.

Update jwk

put

Update jwk

Path parameters
counterparty_guidstringRequired

Counterparty GUID

jwk_guidstringRequired

JWK GUID

Body
Responses
200
OK
application/json
Responseobject
put
PUT /api/v1/counterparty/{counterparty_guid}/jwk/{jwk_guid} HTTP/1.1
Host: your_host
Content-Type: application/json
Accept: */*
Content-Length: 47

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}
{}
Request body example (JWK)
{"data": {
	"alg": "RS256",
	"e": "AQAB",
	"kid": "54321",
	"kty": "RSA",
	"n": "14FGZls6nrBLY2XH9Dn6UVoY24oynIXJX1PGz6c4wB2Q3DpBj-zPwouhXCQSAGyQB4Co0FN0_pML5g1xSOMY1SccBGZ_CxhdSvyskP01Fr0_rHidIdRIc69k-UPzhnk6Nx_F1uFp8105jUD2Tq_VYIS49rqtct4UQOL5PPzfTOUqBMAEBwvL65KqUAOciC1ae_LV6SHZQXdIqv3EZzA3PxZ4pTa6DvnjgVAbP2zNANUFSnuemvTmQbH05E0qTtGkXugwcc4jCfnOWS4gix2GWDoIhwCi8AbK4aAN-H3D770rF4z4Tb59DEw8-8hZQZtyoJeEi8FWNM1Y6Ki5FMxzpQ",
	"use": "sig"
}}

Validate bank's JWT

Метод, що дозволяє банку валідувати власний JWT для авторизації на платформі Прозора Мережа

Authenticate

post

Authenticate

Path parameters
counterparty_guidstringRequired

Counterparty GUID

Header parameters
CX-AuthorizationstringRequired

Counterparty JWT

Responses
200
OK
application/json
post
POST /api/v1/counterparty/{counterparty_guid}/jwk/authenticate HTTP/1.1
Host: your_host
CX-Authorization: text
Accept: */*

{
  "session_token": "text"
}

Check list of JWKs by DCM

Метод, що дозволяє отримати публічний ключ DCM. Таким чином, банк зможе перевірити та провалідувати JWT запит, підписаний DCM

Get list of registered keys for DCM JWT

get

Get list of registered keys for DCM JWT

Responses
200
OK
application/json
get
GET /api/v1/.well-known/jwks.json HTTP/1.1
Host: your_host
Accept: */*

{
  "keys": [
    {
      "alg": "text",
      "e": "text",
      "kid": "text",
      "kty": "text",
      "n": "text",
      "use": "text"
    }
  ]
}

JWT format

JWT використовується для всіх 3 API запитів у заголовку X-Session-ID, щоб зазначити "хто" (суб'єкт) має намір зробити з "чим" (об'єкт). Зміст JWT повинен бути підписаний приватним ключем банку.

Приклад змісту (payload) JWT:

{
  "flow": "sign-in" // constant: sign-in
  "obj": "123456789", // object - identifer of a customer (e.g. IBAN or phone number)
  "sub": "[email protected]", // subject identifier
  "iat": 1684501806, // issued at
  "exp": 1684501806, // expires at
}

Таким чином, при отриманні банком зворотнього запиту (callback), банківська система перевіряє підпис, об'єкт та суб'єкт, які було вказано у початковому API запиті до платформи Прозорої Мережі.

Приклад підписаного JWT:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjljMzdlYjc5LWI2YmYtNDQzNC1hYzNhLTM1NTZjOGI0YjBmNyIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTIxNzIzODUsImZsb3ciOiJzaWduLXVwIiwiaWF0IjoxNjkyMTcyMDg1LCJvYmoiOiJlbWlzc2lvbl8wIiwic3ViIjoiYWRtaW5fYmFuazFAc3RhZ2UudGVzdCJ9.Woh-N-4jeK90rmSbOtAZLno4rCBnWBUOi-PaB6as1lnips966Io19tiK5RQ0aDOoFTrRkGbm01HlDZpHxquI2-BMJfqifY7_QYknge1mHiGIn1lw6W4fBaYcHT2MPJ59ATvzAlt-WMxI6jppsH0tK4ITIUXOfsf6F6flFr1gfWu2HAmys1jxWnKuzRcFpm24Vjoij5exoBlb3wJUaIzJCezJmEAeAqtENZyzpozwRzthDbxhFvkDrm78mMfmjvvvwqdsSAjmKj7apnx0qOqRuKhiFZNbs9aftQqWIGPZ3VaTWIXgksLxiY5xVcf275awYmtZBD7mHeRNIwVYUDWzMQ

Вміст можна розшифрувати тут.

Якщо на стороні банку всі перевірки виконано без помилок, то має бути надіслана успішна відповідь (див. деталі нижче). В іншому випадку очікується відповідь HTTP 401 (неавторизовано).

Авторизація за допомогою колбеків

Для забезпечення прозорості та безпечності платежів необхідно, щоб будь-який запис за рахунком клієнта було авторизовано обидвома учасниками процесу (Банк та Прозора Мережа).

Для цього потрібно реалізувати три API методи авторизації:

Метод
Шлях
Значення

GET

/user_auth

user data

GET

/key

user secret key

GET

/external_id

authentication

Час відповіді за кожним із методів не повинен перевищувати 1 секунди.

Callback специфікація

GET /user_auth

Приклад запиту:

curl "https://{bank's auth host}/user_auth" --header "X-Session-ID:token"

Приклад відповіді:

{
"external_id":"123456789", // up to 500 symbols
"first_name":"mock",
"last_name":"mock",
"email":"[email protected]",
"phone":"+12345678901",
"key":"secret"
}

Атрибути external_id , key та phone є обов'язковими у відповіді.

GET /key

Приклад запиту:

curl "https://{bank's auth host}/key" --header "X-Session-ID:token"

Приклад відповіді:

{
"key":"secret"
}

GET /external_id

Приклад запиту:

curl "https://{bank's auth host}/external_id" --header "X-Session-ID:token"

Приклад відповіді:

{
"external_id":"123456789"
}

PreviousПовідомлення про помилкиNextКлієнти

Last updated