UK OPEN BANKING CONFIGURATION GUIDE
This document includes following topics:
- Objective and Scope
- Technology Stack
- Pre-requisites
- Headers Configuration
- Properties
- SAML
- OAuth Configuration
- Extensibility and Code Conventions
1. Objective and Scope
Background
Open Banking Configuration Document provides the various configurations required to enable UK Open Banking in OBAPI
Scope
- Headers Configuration
- Properties
- SAML Integration
- OAuth Configuration
- Code Convention and Extensibility
2. Technology Stack
| Software Version | Software Version |
| Java | Java JDK or JRE version 8 |
| OBDX/OBAPI | 18.3.0.1.0 |
| OAuth | OBDX Internal OAuth |
Abbreviations
| OOTB | Out of the Box |
| TPP | Third Party A party is any individual or business entity having a banking relationship with the bank. Providers |
| ASPSP | Account Servicing Payment Service Provider |
| SAML | Security Assertion Markup Language |
3. Pre-requisites
- Java JDK or JRE version 7 or higher must be installed. For installation of Java please refer installation guide.
- OAuth Setup
- Weblogic Server with SAML Assertion capability
4. Headers Configuration
There are two types of headers configuration available for UK Open Banking.
- System Headers (i.e. Mandatory Headers and its respective value validation)
- Configuration Headers (i.e. Mandatory Headers).
Below are the configuration steps and Out of the box header already configured in the system.
System Headers:- As of now in OOTB one header has been added as mandatory “x-fapi-financial-id” with value as “491308330388688” (This is a random value and can be changed. This value is issued by OBIE and corresponds to the Organization Id of the ASPSP in the Open Banking Directory). This value needs to be configured by Bank or ASPSP. This header needs to be sent by the TPP to the ASPSP mandatorily with the same value. Both Header name and Header value are validated for System Headers.
For configuring more system headers, below script is to be executed in the OBAPI Admin schema.
Insert into DIGX_FW_CONFIG_ALL_B (PROP_ID, CATEGORY_ID, PROP_VALUE, FACTORY_SHIPPED_FLAG, PROP_COMMENTS, SUMMARY_TEXT, CREATED_BY, CREATION_DATE, LAST_UPDATED_BY, LAST_UPDATED_DATE, OBJECT_STATUS, OBJECT_VERSION_NUMBER) values ('%%HEADER NAME%%','OpenbankingSystemHeaders','%%HEADERVALUE%%','N',null,'Open Banking','ofssuser',sysdate,'ofssuser',sysdate,'Y',1);
Below Query is used to check the System Headers in the system
select * from digx_fw_config_all_b where category_id = 'OpenbankingSystemHeaders';
Configuration Headers :- As of now in OOTB one header has been added as mandatory - “x-fapi-interaction-id”. This header is required to be sent by the TPP to the ASPSP mandatorily with any value.
Only header name is validated in case of Configuration Headers.
For configuring more config headers, below script is to be executed in the OBDX/OBAPI Admin schema.
Insert into DIGX_FW_CONFIG_ALL_B (PROP_ID, CATEGORY_ID, PROP_VALUE, FACTORY_SHIPPED_FLAG, PROP_COMMENTS, SUMMARY_TEXT, CREATED_BY, CREATION_DATE, LAST_UPDATED_BY, LAST_UPDATED_DATE, OBJECT_STATUS, OBJECT_VERSION_NUMBER) values ('%%HEADER NAME%%',' OpenbankingConfigHeaders',null,'N',null,'Open Banking','ofssuser',sysdate,'ofssuser',sysdate,'Y',1);
Below Query is used to check the System Headers in the system
select * from digx_fw_config_all_b where category_id = 'OpenbankingConfigHeaders';
5. Properties
Below are the properties required to be updated in the UK Open Banking. Please find the below properties, its purpose and OOTB values.
Table:- DIGX_FW_CONFIG_ALL_B
Category-Id :- OpenBankingConfig
| Property Id | Property Value (Out of the Box) | Purpose |
| CONSENT_EXPIRYDAYS | 90 | This value is used to check if expiry date send by TPP for the Account Access Consent is not more than 90 days and if it is more than 90 days then ASPSP will reject this value |
| CONSENT_HANDLER | com.ofss.digx.app.openbanking.consent.handler.uk.UKConsentHandler | Handler defines the Region specific behavior of the Open Banking framework. By default UK Consent Handler is used for UK Open Banking compatibility |
Token Settings
Category-Id :- SecurityConstants
| Property Id | Property Value (Out of the Box) | Purpose |
| SIGNER | MAC/no row – MAC Signer X509RS256 – x509 signed token with RS256 algorithm X509PS256 - x509 signed token with PS256 algorithm | The algorithm used to generate JWT token. |
6. SAML
SAML Setup
SAML Setup is required for propagating User Identification for account selection as part of consent authorization. Follow the 7th section of the document available at below location for SAML setup :
SAML Integration
SAML Integration is required for asserting User Identification for account selection as part of consent authorization. Steps to be followed for SAML Integration are as below.
URL for SAML Account Rest should be as :- http://<host>:<port>/ob/saml/accounts
One default Internal Touch Point configuration will be required to handle Access to FETCH and POST Accounts through SAML.
Create a new TouchPoint for SAML services Access and configure in the web.xml of obdx.app.rest.idm.ear for the URL “ob/saml/accounts” as “init-param :- obdx.saml.accesspoint”. So through Role Transaction Mapping of the newly created touchpoint, the access would be provided for the SAML services of Open Banking FETCH and POST account.
As part of User Onboarding in OBAPI, the created touchpoint needs to be associated to the user being onboarded.
7. OAuth Configuration
UI configuration
OAuth Identity Domain Maintenance will require below maintenance to configure UI User Interface Component for Authorizing consent.
The value of Consent Page URL ( Menu -> OAuth -> Identity Domain Maintenance) is configured as http://host:port?homeComponent=authorize-consent&homeModule=open-banking&applicationType=digx-auth
Weblogic configuration
OAuth Maintenance will require below maintenance in weblogic to configure an URL.
Step 1: Login to weblogic
Step 2: Go to Security Realms
Step 3: Go to myrealm
Step 4: Go to Providers
Step 5: Go to OBDXJWT
Step 6: Go to Provider Specific
Step 7: Edit Oauth URL and add the following url and save.
“http://{{host}}:{{manage-server-port}}/digx-auth/v1/token/info”
8. Extensibility and Code Conventions
Code Convention of Account API’s
Accounts related API should use below arguments and return type for working with UK Open Banking
Arguments
- SessionContext sessionContext
- com.ofss.digx.app.openbanking.dto.accounts.uk.AccountRequestDTO accountRequestDTO
Return Type
- BaseResponseDTO<T>
Where T extends DataTransferObject
Any service implemented with the above type of argument will be compatible with UK Open Banking.
Code Convention of Payment API’s
Payment related API should use below arguments and return type for working with UK Open Banking
Arguments
Create and Read Method
- SessionContext sessionContext
- Any DTO Object which extends com.ofss.digx.app.openbanking.dto.consent.uk.UKPaymentDTO
Any service implemented with the above type of argument will be compatible with UK Open Banking.
Error Message Framework
The Error Message Framework helps convert the OBAPI error response according to the UK Open Banking Specifications.
The error response structure for Open Banking Read/Write APIs is as follows:
|
{ "Code": "...", "Id": "...", "Message": "...", "Errors": [ { "ErrorCode": "...", "Message": "...", "Path": "...", "Url": "..." } ] } |
The UK Open Banking specified error response is handled using DIGX_OB_UK_OBDX_ERROR_MAP table.
The contents of the table are as follows:
| Column Name | Description |
| DIGX_ERROR_CODE | Represents the OBAPI error codes. This is a Primary and Unique Key |
| UK_ERROR_CODE | Represents the Open Banking specified error code |
| PATH | Represents the reference to the JSON Path of the field with error. Can be null. |
| URL | Represents the URL to help remediate the problem, or provide more information etc. Can be null. |
For mapping OBAPI error codes with UK Open Banking specified codes below script can be used:
Insert into DIGX_OB_UK_OBDX_ERROR_MAP (DIGX_ERROR_CODE,UK_ERROR_CODE,PATH,URL) values ('%%OBDX Error Code%%',%%Open Banking specified error code%%', '%%Path%%', '%%URL%%');
For example –
Insert into DIGX_OB_UK_OBDX_ERROR_MAP (DIGX_ERROR_CODE,UK_ERROR_CODE,PATH,URL) values ('DIGX_OB_0010','UK.OBIE.Field.Missing', 'Data.Initiation ',null);
Below Query is used to check the OBAPI errors mapped with UK Open Banking specified error codes in the system
select * from DIGX_OB_UK_OBDX_ERROR_MAP;
For configuring HTTP status codes with custom message, below script can be used:
Insert into DIGX_FW_CONFIG_ALL_B (PROP_ID, CATEGORY_ID, PROP_VALUE, FACTORY_SHIPPED_FLAG, PROP_COMMENTS, SUMMARY_TEXT, CREATED_BY, CREATION_DATE, LAST_UPDATED_BY, LAST_UPDATED_DATE, OBJECT_STATUS, OBJECT_VERSION_NUMBER)
values ('%%HTTP Status code%%','OpenBankingErrorConfig','%%Error Message%%','N',null,'OpenBanking Error Message','ofssuser',sysdate,'ofssuser',sysdate,'Y',1);
Below Query is used to check the Open Banking HTTP status codes in the system
select * from digx_fw_config_all_b where category_id = ' OpenBankingErrorConfig';
Permission Response Handler
Permissions is used in only Account API’s. Based on Permissions, Response is generated based on permissions.
OBAPI consists of Permission Handler against each type of permissions. This configuration is availble in the table DIGX_OB_UK_PERMISSIONS_MASTER
The contents of the table are as follows:
| Column Name | Description |
| SERVICEID | Represents the OBAPI Service Id for which the permission and its handler is available |
| PERMISSION | Represents Permission |
| RESPONSEHANDLER | Represent Permission Handler |
Permission Handler can be overriden or can be newly introduced. This will be required for additional fields mapping which is not available OOTB. Steps for the same are as follows
Introducing Permission Handler
New Permisison Handler should implement interface IResponseHandler
New Permission Handler should have below methods
public static <T implements IResponseHandler> getInstance()
public <T extends DataTransferObject> assembleResponse(DataTransferObject object, List<String> permissions) – This method assembles response from object to the require response object which needs shown in the API response. Object is the response got from base sevice and T will be the response object require by API specifications. Assembling of the values will be done this method
public int getPriority() – This defines the high priority of the handler to be applied for assembling response in case of permissions and its handler has been consented by the user i.e. Basic and Detail permission will have different handlers but if the consent is both the permisison the priority of the handler will decide which needs to be executed on high priority.