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

How to log in to the system with an employee credentials

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

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

  • Update a JWK

  • Validate bank's JWT

  • Check list of JWKs by DCM

  • JWT format

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

  • GET /user_auth

  • GET /key

  • GET /external_id

Опис

Для обміну 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

application/json

Responses

200

OK

application/json

Responseobject

400

json with error msg

application/json

put

/counterparty/{counterparty_guid}/jwk/{jwk_guid}

HTTPcURLJavaScriptPython

PUT /api/v1/counterparty/{counterparty_guid}/jwk/{jwk_guid} HTTP/1.1
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

400

json with error msg

application/json

post

/counterparty/{counterparty_guid}/jwk/authenticate

HTTPcURLJavaScriptPython

POST /api/v1/counterparty/{counterparty_guid}/jwk/authenticate HTTP/1.1
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

400

json with error msg

application/json

get

/.well-known/jwks.json

HTTPcURLJavaScriptPython

GET /api/v1/.well-known/jwks.json HTTP/1.1
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":"[phone]",
"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"
}