Посилена автентифікація PSU (SCA)
Цей розділ описує вимоги до посиленої автентифікації PSU (SCA) в Open Banking Ukraine, включно з HTTP header-параметрами для контексту та ідентифікації PSU, керуванням підходами SCA, а також особливостями Redirect, Decoupled та OAuth2 SCA.
Примітка: термін PSU використовується для позначення користувача послуги навіть у випадках, коли послуга не пов’язана з ініціацією платежу.
8.1. Header параметри для даних контексту PSU
Наступні елементи даних передають інформацію про інтерфейс між PSU та API client, щоб покращити процедури управління ризиками ASPSP, інтегровані в процедури SCA. Рекомендовано надсилати ці елементи даних у всіх Transaction Initiation Requests, які включають автентифікацію PSU.
Параметри header, визначені в цьому розділі, не будуть повторюватися в специфікаціях послуг для покращення читабельності документа, але специфікації по відповідних послугах будуть посилатися на цей документ у відповідних розділах. Всі застосовні header містить yaml файл.
Єдиним винятком є випадки, коли на конкретні request messages застосовуються умови, відмінні від optional, наприклад, для IP-адреси PSU. Більше деталей може бути надано в розділі огляду даних у межах специфікації кожної послуги.
| Атрибут | Формат | Умова | Опис |
|---|---|---|---|
| PSU-IP-Address | String | Conditional | Поле заголовка IP-адреси, що пересилається, складається з відповідного поля IP-адреси request HTTP між PSU і TPP. Якщо воно недоступне, TPP повинен використовувати IP-адресу, яку використовує TPP під час направлення цього запиту до ASPSP. Умови визначаються у відповідних специфікаціях послуг. |
| PSU-IP-Port | String | Optional | Поле пересланого IP Port header складається з відповідного поля IP-порту HTTP-request між PSU та TPP, якщо доступно. |
| PSU-Accept | String | Optional | Переадресовані поля IP Port header складаються з відповідних полів header HTTP request Accept між PSU та TPP, якщо такі є. |
| PSU-Accept-Charset | String | Optional | див. вище |
| PSU-Accept-Encoding | String | Optional | див. вище |
| PSU-Accept-Language | String | Optional | див. вище |
| PSU-User-Agent | String | Optional | Поле header пересланого Agent HTTP-request між PSU та TPP, якщо доступно. |
| PSU-Http-Method | String | Optional | HTTP-метод, використаний на інтерфейсі PSU – TPP, якщо доступно. Можливі значення: GET, POST, PUT, PATCH, DELETE. |
| PSU-Device-ID | String | Optional | UUI або IMEI для пристрою, який використовується PSU, якщо доступно. UUID/IMEI ідентифікує або пристрій, або залежну від пристрою інсталяцію застосунку. У випадку ідентифікації інсталяції цей ID має залишатися незмінним до видалення з пристрою. |
| PSU-GeoLocation | Geo Location | Optional | Переслане геолокаційне значення відповідного HTTP-request між PSU та TPP, якщо доступно. |
Примітка: інформація про інтерфейс між PSU та API client може використовуватися ASPSP як вхідні дані для його систем виявлення шахрайства та управління ризиками. Деякі ASPSP використовують цю інформацію також для виключення певних методів автентифікації (наприклад, деякі ASPSP не дозволяють отримувати OTP через SMS на тому ж смартфоні, який використовується для самої транзакції). Крім того, ASPSP може знадобитися отримати специфічну інформацію про пристрій, щоб підтримати оптимізовану процедуру перенаправлення «app-2-app» для API client.
З цих причин рекомендується, щоб API client включав всю цю інформацію в пов’язані Transaction Initiation Request messages. Відсутність інформації може призвести до оцінки користувацького пристрою як непридатного для методу автентифікації або до класифікації поточної транзакції як «транзакції з високим ризиком», наприклад, через атаки на сесію. Це може збільшити ймовірність відхилення цієї транзакції внаслідок результатів виявлення шахрайства та/або управління ризиками.
8.2. Header параметри ідентифікації PSU
Фреймворк відкритого банкінгу підтримує передачу даних ідентифікації PSU у request параметрах для всіх Transaction Initiation Request messages. ASPSP може вимагати ці елементи, що має бути відображено в відповідній документації ASPSP на порталі для TPP.
Header параметри, визначені в цьому розділі, не будуть повторюватися в рекомендаціях щодо реалізації специфікацій послуг для покращення читабельності документа, але рекомендації щодо реалізації будуть посилатися на цей документ у відповідних розділах. Однак детальні специфікації викликів послуг через пов’язані yaml файли міститимуть всі застосовні headers.
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| PSU-ID | Max140Text | Conditional | Ідентифікатор PSU-фізичної особи в клієнтському інтерфейсі ASPSP. Може бути обов’язковим згідно з документацією ASPSP, наприклад, якщо використовується Decouple SCA — цей атрибут передається обов’язково. |
| PSU-ID-Type | Max35Text | Conditional | Тип PSU-ID фізичної особи, необхідний у сценаріях, коли PSU мають кілька типів ідентифікаторів, як можливість доступу. Можливі значення: PHONE; IBAN; TAXCODE; та інші, які точно відомі PSU та дозволяють ASPSP ідентифікувати PSU (ASPSP має зазначити це на своєму порталі). ASPSP не має використовувати ідентифікатори, які будуть перешкоджати PSU інціювати виконання платіжної операції або надати згоду на надання відомостей з рахунків через TPP. Може бути обов’язковим згідно з документацією ASPSP, наприклад, якщо використовується Decouple SCA — цей атрибут передається обов’язково. |
| PSU-Corporate-ID | Max140Text | Conditional | Ідентифікатор суб’єкту господарювання (ФОП) в онлайн-каналах ASPSP. Може бути обов’язковим згідно з документацією ASPSP, наприклад, якщо використовується Decoupled SCA. |
| PSU-Corporate-ID-Type | Max35Text | Conditional | Тип ідентифікатора суб’єкту господарювання (PSU-Corporate-ID), необхідний у сценаріях, коли PSU мають кілька типів ідентифікаторів, як можливість доступу. Можливі значення: PHONE; IBAN; TAXCODE; та інші, які точно відомі PSU та дозволяють ASPSP ідентифікувати PSU (ASPSP має зазначити це на своєму порталі). ASPSP не має використовувати ідентифікатори, які будуть перешкоджати PSU інціювати виконання платіжної операції або надати згоду на надання відомостей з рахунків через TPP. Може бути обов’язковим згідно з документацією ASPSP, наприклад, якщо використовується Decoupled SCA — цей атрибут передається обов’язково. |
Примітка: у якості PSU-Corporate-ID-Type, PSU-ID-Type не може використовуватись номер платіжної картки.
Примітка: ASPSP може підтримувати спеціальні символи для ідентифікації PSU в їх клієнтських інтерфейсах. Для підтримки цього на рівні API рекомендований набір символів для header параметрів, пов’язаних з ідентифікацією PSU, базується на ISO8859-1.
На додаток до простого кодування ISO8859-1 згідно зі специфікацією HTTP, ASPSP може запропонувати кодування Base64. (Ілюстрацію з вихідного документа опущено.)
Кодування header параметрів заголовка в UTF-8, яке використовується клієнтом API, може призвести до відмов з Message Code PSU_CREDENTIALS_INVALID (більш детально коди помилок описані у документі «Data Dictionary»). Відхилення від цих рекомендацій повинні бути детально задокументовані ASPSP.
8.3. Header параметри для SCA
Header параметри, визначені в цьому розділі, не будуть повторюватися в специфікаціях для покращення читабельності документа, але специфікації будуть посилатися на цей документ у відповідних розділах. Однак, yaml файли міститимуть усі header.
8.3.1. Request header параметри для управління підходами SCA
Наступні request headers можуть бути використані API client у Transaction Initiation Request для передачі SCA до ASPSP для авторизації транзакції.
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| Client-SCA-Approach-Preference | Max35Text | Optional | Cписок атрибутів, де перший елемент матиме вищий пріоритет ніж наступний або ніж будь-який підхід SCA, який взагалі не зазначений, наприклад: "decoupled, redirect" або "decoupled". Цей атрибут може бути проігнорований ASPSP. |
| Client-Redirect-URI | String | Conditional | URI TPP, куди потік транзакції має бути перенаправлений після Redirect. Обов’язковий для підходу Redirect SCA. Див. розділ 8.5 для подальших вимог щодо цього заголовка. Рекомендується завжди використовувати це поле в header. |
| Client-Nok-Redirect-URI | String | Optional | Якщо цей URI міститься, TPP просить перенаправити потік транзакції на цю адресу замість Client-Redirect-URI у випадку негативного результату методу Redirect SCA. Це може бути проігноровано ASPSP. Див. розділ 8.5 для подальших вимог щодо цього header. |
| Client-Explicit-Authorisation-Preferred | Boolean | Optional | Якщо значення дорівнює true, API client віддає перевагу окремому запуску процесу авторизації, наприклад, через використання асинхронної авторизації. Якщо значення дорівнює false або якщо параметр не використовується, у API client немає особливих уподобань. Це особливо вказує на те, що API client здійснює пряму авторизацію транзакції на наступному кроці. В Україні використовується тільки explicit start authorization, тому, якщо цей параметр використовується — то коректно передавати значення true. |
8.3.2. Пов’язані Response Headers
Наступний header використовується ASPSP для передачі рішень щодо обраного підходу SCA TPP.
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
| ASPSP-SCAApproach | String | Conditional | Цей елемент даних має бути включений, якщо підхід SCA вже визначений. Можливі значення: DECOUPLED, REDIRECT. Підхід OAuth SCA буде включений до REDIRECT. |
8.4. Відокремлений підхід SCA (Decoupled SCA)
Decoupled SCA використовує платіжний застосунок ASPSP для посиленої автентифікації PSU.
8.5. Підхід перенаправлення SCA (Redirect SCA)
У підході Redirect SCA TPP на певному етапі отримає посилання scaRedirect у відповіді від ASPSP. Це посилання веде на сторінку автентифікації, пов’язану з транзакцією, яка має бути авторизована, і TPP має перенаправити user agent PSU на це посилання як наступний крок.
При доступі до сторінки PSU буде автентифікуватися за допомогою відповідних даних (credentials) PSU, перегляне представлену інформацію про транзакцію і зможе завершити авторизацію звідти.
Коли авторизація буде завершена PSU, PSU (header PSU-User-Agent) знову перенаправляється ASPSP на Client-Redirect-URI, який був наданий у відповідному Transaction Initiation Request. Якщо авторизація не була успішною, ASPSP може використовувати Client-Nok-Redirect-URI, наданий у тому ж виклику, якщо це підтримується.
Примітка: Посилання scaRedirect може включати query параметри. ASPSP не повинні включати у query параметри з назвою state у свої посилання scaRedirect. Такий параметр зарезервований для TPP для використання в управлінні сесією.
8.6. Підхід OAuth SCA
Протокол OAuth2, який використовується опціонально для цього API, визначений у RFC 6749. У цьому розділі визначені додаткові вимоги до протоколу OAuth2. Пов’язаний протокол має використовуватися TPP, якщо ASPSP передає посилання типу scaOAuth.
Примітка: Більш стандартизований профіль безпеки, заснований на перенаправленні, наприклад, профіль FAPI PAR, поки що не підтримується в рамках відкритого банкінгу.
Вимоги до обміну даними між TPP і OAuth Server ASPSP щодо транспортного рівня ідентичні вимогам обміну даними.
Примітка: Вимоги щодо використання MTLS також застосовуються до використання протоколу OAuth2. Однак загальні вимоги до прикладного рівня, такі як підписання request, не застосовуються до OAuth2 messages.
Специфікація рекомендує використовувати тип відповіді code та типи дозволу authorization_code і refresh_token. Крім того, рекомендується TPP та ASPSP дотримуватися найкращих практик безпеки, визначених у OA-SecTop.
Примітка: У випадку підходу OAuth SCA TPP повинен додатково згенерувати nonce для параметра виклику (challenge). Це також має бути прив’язано до сесії user agent PSU.
ASPSP зобов’язаний надавати TPP конфігураційні дані, що відповідають специфікації «OAuth 2.0 Authorisation Server Metadata».
8.6.1. Authorization Request
Для «Authorization Request» (див. RFC 6749, розділ 4.1.1) до endpoint OAuth2authorization, наданого в Metadata сервера, визначені наступні параметри.
Query Parameters
| Атрибут | Умова | Опис |
|---|---|---|
| response_type | Mandatory | Рекомендується використовувати code як тип відповіді. |
| client_id | Mandatory | organizationIdentifier, як зазначено в QWAC. |
| scope | Mandatory | PIS: це посилання на ресурс платежу у формі PIS:<paymentId>. AIS: це посилання на ресурс згоди для доступу до рахунку у вигляді AIS:<consentId>. Примітка: Ідентифікатори ресурсів, обрані ASPSP, повинні бути унікальними, щоб уникнути конфліктів ресурсів під час процесу SCA. |
| state | Mandatory | Динамічне значення, встановлене TPP і використане для запобігання XSRF-атакам. |
| redirect_uri | Mandatory | URI TPP, куди сервер OAuth2 перенаправляє user agent PSU після авторизації. |
| code_challenge | Mandatory | Виклик PKCE відповідно до RFC 7636, використаний для запобігання атакам з впровадженням коду. |
| code_challenge_method | Optional | Метод трансформації перевірки коду: S256 або plain. S256 рекомендований цією специфікацією. |
Приклад
GET /authorize?response_type=code&client_id=PSDES-BDE-3DFD21&scope=ais%3A3d9a81b3-a47d-4130-8765-a9c0ff861100+offline_access&state=S8NJ7uqk5fY4EjNvP_G_FtyJu6pUsvH9jsYni9dMAJw&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&code_challenge_method="S256"&code_challenge=5c305578f8f19b2dcdb6c3c955c0aa709782590b4642eb890b97e43917cd0f36 HTTP/1.1
Host: api.testbank.com
8.6.2. Authorization Response
Відповідь на авторизацію (див. RFC 6749, розділ 4.1.2) від ASPSP міститиме наступні дані.
Зауваження: оскільки запит не надсилається TPP, а user agent PSU — він не буде захищений QWAC TPP.
HTTP Response Code
HTTP Response Code дорівнює 302.
Query Parameters
| Атрибут | Умова | Опис |
|---|---|---|
| Location | Mandatory | URI перенаправлення API client |
| code | Mandatory | Код авторизації |
| state | Mandatory | Те ж значення, що і для request |
Приклад
HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=S8NJ7uqk5fY4EjNvP_G_FtyJu6pUsvH9jsYni9dMAJw
8.6.3. Request Access Token
Як описано у RFC 6749, розділ 4.1.3, TPP надсилає POST-request до token endpoint з метою обміну наданого коду авторизації на токен доступу та, за бажанням, на токен оновлення.
Request Parameters
| Атрибут | Умова | Опис |
|---|---|---|
| grant_type | Mandatory | authorization_code рекомендований як тип відповіді. |
| client_id | Mandatory | Див. визначення в розділі 8.6.1 |
| code | Mandatory | Код авторизації з response на авторизацію |
| redirect_uri | Mandatory | Точний URI TPP, куди сервер OAuth2 перенаправив user agent PSU для цієї конкретної транзакції |
| code_verifier | Mandatory | Перевірка PKCE відповідно до RFC 7636, використовується для запобігання атакам з впровадженням коду |
Приклад
POST /token HTTP/1.1
Host: https://api.testbank.com
Content-Type: application/x-www-form-urlencoded
client_id=PSDES-BDE-3DFD21&grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&code_verifier=7814hj4hjai87qqhjz9hahdeu9qu771367647864676787878
TPP автентифікується під час цього request за допомогою «OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens» (див. RFC 8705) у поєднанні з сертифікатом QWAC TPP.
8.6.4. Access Token Response
ASPSP відповідає з наступними параметрами.
Response Parameters
| Атрибут | Умова | Опис |
|---|---|---|
| access_token | Mandatory | Access Token, прив’язаний до області дії, як зазначено у authorisation request і підтверджено PSU. |
| token_type | Mandatory | Встановлено значення Bearer. |
| expires_in | Optional | Термін дії Access Token в секундах. |
| refresh_token | Optional | Refresh Token, який може бути використаний для отримання нового Access Token у випадку, якщо попередній Access Token закінчився або був відкликаний. Особливо корисно в контексті AIS. |
| scope | Mandatory | Область дії Access Token. |
Приклад
{
"access_token": "SlAV32hkKG",
"token_type": "Bearer",
"expires_in": 3600,
"refresh_token": "tGzv3JokF0XG5Qx2TlKWIA",
"scope": "exampleScope"
}
8.6.5. Refresh Token Grant Type
ASPSP може видавати Refresh Token на власний розсуд, наприклад, для ситуації коли AISP використовує стандартне значення області offline_access або якщо recurringIndicator встановлено на true.
8.6.6. API Requests
При використанні підходу OAuth SCA наступні API requests авторизуються за допомогою відповідного Access Token OAuth. Access Token надсилається до API, використовуючи header Authorization і схему авторизації Bearer, як визначено в RFC 6750.
Приклад API-запиту:
GET /psd2/v2/payments/credit-transfers/3d9a81b3-a47d-4130-8765-a9c0ff861100/status HTTP/1.1
Host: https://api.testbank.com
Authorization: Bearer SlAV32hkKG