Account-and-Transaction API (UK Open Banking) - Test Guide

This document provides a summary overview of the steps that need to be executed in order to send a valid request to the implemented API endpoints.

This API has been configured to comply with access and further security requirements as they have been specified in the UK Open Banking security profile. Consequently, additional configuration is required to have a request to the API processed successfully. The Test Client facilitates this additional configuration, which is described in detail below.

Keystore

To successfully call this API, the client has to be configured with a keystore which can be used for the following purposes:

• to access the Authorization Server (mTLS / certificate-based client authentication );
• to access the API through its mTLS endpoint.

To make use of a keystore, it needs to be uploaded in the Test Client as explained below.

API Functions and Operations

The following operations (API resources) have been implemented on this API (the remaining resources may provide a static mock response and/or may have limited security configuration in place):

• POST /account-access-consents
• GET /account-access-consents/{ConsentId}
• DELETE /account-access-consents/{ConsentId}

These resources represent the three endpoints of the Account Access Consents service offered by the Account-and-Transaction API. When an AISP requests account information, (s)he will first have to create an account-access-consent resource (commonly referred to as ‘Consent’) using POST /account-access-consents. A created ConsentId can be reviewed using GET /account-access-consents/{ConsentId}. It can be deleted using DELET /account-access-consents/{ConsentId}. Note that the Sandbox implementations offered here provide mock responses that demonstrate the expected functionality without actually creating or deleting data.

More and actual details can be found in the Open Banking IE reference documentation for this API.

Executing a test on POST /account-access-consents (happy flow)

This Digital Banking Portal provides a convenient Test Client for effective API testing. Please note that this Test Client allows for configuration settings that are needed to satisfy various security policies that have been implemented on the API endpoint (for example: OAuth2.0 and Message Validation according to the Open Banking request message specification).

Test Client can be accessed through the ‘Test Client’ button in the left navigation bar when viewing the API.

Accessing the Test Client will show details of the API about to be tested as shown in the screen capture below:

The section shows the available API Implementations (in this case, Sandbox only), available API operations, Endpoints on which the API is available (in this case, https and mutual-https); the Path field shows the path associated with the selected Operation.

Essentially, Test Client automatically shows all details as they are laid down in the API interface (Swagger/OAS). Selecting an Operation will automatically populate relevant other sections, for example Headers, Parameters and Access URL.

Steps to execute for a successful test are:

1. Select a valid client (when in API view, using Test Client’s ‘Setup’ function). The client is an App that has been generated for you specifically as part of your registration. This consuming App represents a client identity that is subject to authentication, authorization and, potentially, additional security constraints;
2. Provide valid values to any required request header and/or parameter (required elements are marked with a *);
3. Provide a valid request body (JSON object), if applicable;
4. Provide any configuration values that are required to satisfy security policies associated with the API resource (using Test Client’s ‘Security’ function).

Request headers:

Required parameters: none.

Request body: the API Documentation presents a valid sample request body that can be copied into Test Client Content field.

{ "Data": { "Permissions": [ "ReadAccountsBasic", "ReadBalances" ], "ExpirationDateTime": "2020-06-09T13:44:07.946Z", "TransactionFromDateTime": "2020-06-09T13:44:07.947Z", "TransactionToDateTime": "2020-06-09T13:44:07.947Z" }, "Risk": {} }

Client: a sample client can be selected from Test Client ‘Setup’ function. The client is an App that has been generated for you specifically as part of your registration. The App can be associated with a keystore (private and public key) for mTLS and request signing purposes.

To generate a keystore using KeyStore Explorer and associate it with your App, please refer to Akana Docs: create a keystore

Security policies: in accordance with the UK Open Banking Standard’s security profile, several security policies must be adhered to.

• OAuth2.0: client authorization is done using OAuth2.0. A request must present a valid OAuth Bearer Access Token through its Authorization header. Have the Test Client generate this token for you: hit ‘Security’ and ensure values as shown below are present:
  
  Click 'Get Token' to have the Access Token generated. The Token field show show the token and some additional information.
  Result: an Authorization header with a valid bearer access token has been added to the request, allowing the client to be authorized at the API endpoint.


Note: 'Security' configuration will show CORS as a final step; accept the defaults and click 'Finish'.

With these steps configured as documented above, the request should be accepted and return an http 201 with a generated JSON mock response. Some request and response details can be reviewed in Test Client. In addition, the 'Trace' tab (under Response) shows elements automatically added by Test Client, based on your Setup and Security configuration.
Further details of the transaction, including operational metrics and details on the generated request message and returned response can be reviewed under the 'Logs' menu item.

Alternative test cases

• Invalid payload, for example {} or removing the "Permissions" section from the JSON object will have the API Gateway block the request (http 400);
• Selecting an incorrect OAuth scope, for example 'Payments' rather than required 'Accounts', will have the API Gateway block the request (http 403).