This documentation is for WSO2 Open Banking version 1.4.0. View documentation for the latest release.
Skip to end of metadata
Go to start of metadata

WSO2 Open Banking is a PSD2-compliant solution that provides secure mediation flow of information between Payment Service Providers (PSPs), Third Party Providers (TPPs) and Payment Service Users (PSUs). This document guides you through the configurations and troubleshooting that you need to set up the solution in your local environment. 

The scripts for the below local setup in the Quick Start Guide are configured for a Linux and MySQL/MSSQL environment. Notice that WSO2 Open Banking solution is applicable to Windows/Linux and MySQL/MSSQL and Oracle environments.

Prerequisites

  1. Download Oracle JDK 1.8 in all the nodes of the setup.
    • In the environment variables, update the JAVA_HOME and PATH variables. For instance, you can do this on a Mac/Linux server by adding the following to the ~/.bashrc file:
    export JAVA_HOME="<JDK_LOCATION>"
    
    export PATH=$PATH:$JAVA_HOME/bin
  2. Download and unzip the following files: 
    • wso2-obam-1.4.0.zip (WSO2 Open Banking API Manager) 

    • wso2-obkm-1.4.0.zip (WSO2 Open Banking Key Manager)

       Click here to see how to download the packs from WUM

      Set up the WSO2 Update Manager (WUM). 

      • WUM is a simple command-line tool that connects to the WSO2 update service, determines which updates are new and relevant, and downloads them. You can get the latest version of the WSO2 Open Banking product packs through WUM.

        License

        WSO2 Open Banking is not distributed under the Apache Community License and is only available under the WSO2 Software License. You need a WSO2 subscription to install and update the WSO2 Open Banking solution via WUM. Contact us to find out how you can access a free evaluation copy...

      • Follow the guidelines provided on the Download WUM page to download, and install WUM in your environment. For more information on how to use WUM, see the WUM documentation.

          1. Add the necessary product packs using the commands given below:

            wum add wso2-obam-1.4.0              		 	                	     
            wum add wso2-obkm-1.4.0 
          2. Update the product packs using the commands given below:

            wum update wso2-obam-1.4.0	                	     
            wum update wso2-obkm-1.4.0               	     
          3. Additionally, download and update the other instances of WSO2 Open Banking product.

            wum add wso2ei-6.4.0
            wum update wso2ei-6.4.0
            
            wum add wso2am-analytics-2.6.0    
            wum update wso2am-analytics-2.6.0 
               
            wum add wso2-obbi-1.4.0
            wum update wso2-obbi-1.4.0

            WSO2 OB APIM Analytics(wso2am-analytics-2.6.0) provides the API analytics feature.

            WSO2 OB BI(wso2-obbi-1.4.0) provides the following features:

            • API Analytics

            • Transaction Risk Analysis

            • Fraud Detection

            • Data Reporting

      • The product packs reside in the <WUM_HOME>/products/<Product_Name>/<version>/full directory as <Product_name-<version>+<timestamp>.full.zip. Copy the product packs to a preferred location in each node, and extract them.

      WSO2 Updates Manager (WUM) is deprecated and will be unavailable from July 2021 onwards. WSO2 Updates is the new tool to include the solution and security improvements that are released by WSO2 Open Banking, on top of a released version. For more information, see WSO2 Updates.

       Click here to see how to update the solution via WSO2 Update tool...

      The WSO2 Update tool delivers hotfixes and updates seamlessly on top of products as WSO2 Updates. They include improvements that are released by WSO2. You need to update all the products using the relevant script.

      • Go to <PRODUCT_HOME>/bin and run the WSO2 Update tool: 

        ./wso2update_linux 
        ./wso2update_darwin
        ./wso2update_windows.exe
      • Repeat this step for all the products in the solution:
        • wso2-obkm-1.4.0 
        • wso2-obam-1.4.0 
        • wso2-obbi-1.4.0
        • wso2am-analytics-2.6.0

      This document refers to the file paths of the product packs for the Key Manager, API Manager, API Manager Analytics, and Enterprise Integrator as <WSO2_OB_KM_HOME>, <WSO2_OB_APIM_HOME>, <WSO2_AM_ANALYTICS_HOME>,<WSO2_OB_BI_HOME> and <WSO2_EI_HOME> respectively.

      WSO2 Updates Manager (WUM) is deprecated and will be unavailable from July 2021 onwards. WSO2 Updates is the new tool to include the solution and security improvements that are released by WSO2 Open Banking, on top of a released version. For more information, see WSO2 Updates.

       Click here to see how to update the solution via WSO2 Update tool...

      The WSO2 Update tool delivers hotfixes and updates seamlessly on top of products as WSO2 Updates. They include improvements that are released by WSO2. You need to update all the products using the relevant script.

      • Go to <PRODUCT_HOME>/bin and run the WSO2 Update tool: 

        ./wso2update_linux 
        ./wso2update_darwin
        ./wso2update_windows.exe
      • Repeat this step for both the wso2-obkm-1.4.0 and wso2-obam-1.4.0 products.
  3. Setup a database server using MySQL 5.7, Microsoft SQL Server 2016 or, Oracle 12c.

Setting up the databases and starting the servers

In order to start the servers, configure the databases in both the API Manager (APIM) and the Key Manager (KM) according to the open banking specification, as follows:

  1. Open the <WSO2_OB_KM_HOME>/repository/resources/finance/scripts/startup.properties file and configure the following:

    • Specify the hostnames for the APIM and KM servers.

      # Specify the hostname you want to configure
      APIM_HOSTNAME=localhost
      IAM_HOSTNAME=localhost
    • Configure the databases related properties.

      Database PropertyDescription
      DB_TYPE

      Type of the database you installed

      DB_TYPE=mysql
      DB_USER Database user
      DB_PASS Password set for the database connection
      DB_HOST Name of the database server
      DB_DRIVER

      Configure DB_DRIVER according to the database installed:

      - Mysql JDBC Driver = com.mysql.jdbc.Driver 
      - MSSQL JDBC Driver = com.microsoft.sqlserver.jdbc.SQLServerDriver
      - Oracle JDBC Driver = oracle.jdbc.driver.OracleDriver

      If you are using an MS SQL or an Oracle database, see Configuring Databases and configure the databases.

      If you're setting up Open Banking for Berlin and using an Oracle database, update the data type of the given field:  

       Click here to see the field to be updated...
      Databaseopenbank_apimgtdb
      TableAM_APPLICATION_REGISTRATION
      FieldINPUTS
      Data typeCLOB
  2. Run the <WSO2_OB_KM_HOME>/repository/resources/finance/scripts/configure-km.sh file using the following command:

    ./configure-km.sh

    If you're setting up Open Banking for Berlin:

    Update the data type of the given field to CLOB

    Databaseopenbank_apimgtdb
    TableAM_APPLICATION_REGISTRATION
    FieldINPUTS
    Data typeCLOB
  3. Go to the <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts directory and configure the database properties in the startup.properties file, similar to Step 1.

  4. Run the <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/configure-am.sh file.

    You have configured databases in step 1. By running configure.sh files, you set the database credentials with reference to the configuration files.

  5. Configure the deployed open-banking specification accordingly. 

    By default, values are set for the UK specification. Other supported specifications include:


    • The following configurations are used to define the deployed specification at runtime:

      ProductFileConfigAllowed Values
      APIM

      <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml 

      <DeployedSpecification>UK or BERLIN or STET
      APIM

      <WSO2_OB_APIM_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json

      <DeployedSpecification>UK or BERLIN or STET
      KM

      <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml   

      <DeployedSpecification>

      UK or BERLIN or STET

      KM

      <WSO2_OB_KM_HOME>/repository/deployment/server/jaggeryapps/ccportal/configs/conf.json 

      <DeployedSpecification>UK or BERLIN or STET
      KM

      <WSO2_OB_KM_HOME>/repository/deployment/server/jaggeryapps/consentmgt/configs/conf.json

      <DeployedSpecification>UK or BERLIN or STET
  6. WSO2 Open Banking contains a mock back end. To configure the mock back end according to your specification:

    1. Open the open-banking.xml files. 
      1. <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml 
      2. <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml 
    2. Update the above files as follows:

      By default, the solution contains the UK configurations.

      <PayableAccountsRetrieveEndpoint>
      http://localhost:9763/open-banking/services/bankaccounts/bankaccountservice/payable-accounts
      </PayableAccountsRetrieveEndpoint>
      
      <SharableAccountsRetrieveEndpoint>
      http://localhost:9763/open-banking/services/bankaccounts/bankaccountservice/sharable-accounts
      </SharableAccountsRetrieveEndpoint>
      <PayableAccountsRetrieveEndpoint>
      https://localhost:9443/open-banking-berlin/services/v130/accounts/payable
      </PayableAccountsRetrieveEndpoint>
      
      <SharableAccountsRetrieveEndpoint>
      https://localhost:9443/open-banking-berlin/services/v130/accounts/shareable
      </SharableAccountsRetrieveEndpoint>
  7. You are now ready to start the Key Manager and API Manager servers. In the command line, navigate to the <WSO2_OB_KM_HOME> /bin directory, and run the following command:

    ./wso2server.sh -Dsetup
  8. Run the same command from the <WSO2_OB_APIM_HOME>/bin directory to start the WSO2 OB APIM server.


You have started the servers. Next, configure users, roles, and APIs.

Configuring users and roles

  1. Sign in to the Identity and Access Management console (https://localhost:9446/carbon ). Use the default super admin credentials as follows:

    Username: [email protected]

    Password: wso2123

    The above mentioned username and password credentials are used for demo purposes only. It is recommended to change the credentials in a production environment.

  2. Create the necessary user roles as follows:

    • On the Main tab, click Identity > Users and Roles > Add > Add New Role.

    • Create the following user roles:

      DomainRolePermissions

      Internal

      aispRole

      No permissions required.

      Internal

      pispRole

      No permissions required.

      Internal

      piispRole

      No permissions required.

      Internal

      approverRole

      Admin permissions.

      Internal

      CustomerCareOfficer

      No permissions required.

  3. Create the necessary user accounts as follows:

      • On the Main tab, click Identity > Users and Roles > Add > Add New User.

    Now that you’ve added some users to the system, you can log in as one of them to see how a typical user might work with the WSO2 Open Banking solution.

Configuring APIs

You can configure APIs through the API Publisher by signing in as a user whose role includes Internal/publisher. Follow the steps given below:

  1. Sign in to the API Publisher ( https:// localhost:9443/publisher ) with the credentials for  [email protected] .

  2. Click ADD NEW API > I have an existing API

  3. Select the Swagger definition from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis and configure the properties according to the open-banking specification. Find more information from the table given below.


    Click Start Creating.
  4. Click Next: Implement to navigate to the next level.
  5. Expand Managed API, and use the table below to select the relevant Endpoint Type from the drop down list.
  6. Check Select a message mediation policy to be executed in the message flow under Message Mediation Policies.
  7. Click Upload In Flow and select the corresponding In sequence file from <WSO2_OB_APIM_HOME>/repository/resources/finance/apis.

  8. Click Next: Manage to navigate to the next level.

  9. Expand Throttling Settings. Under Subscription Tiers, check the option as Unlimited : Allows unlimited requests unless you want to limit the requests.
  10. Expand API Properties and add the following values as Additional properties:

    Property Name

    ob-spec

    Property Value

    uk

    Property Name

    ob-spec

    Property Value

    berlin

    Property Name

    ob-spec

    Property Value

    stet
  11. Click the + button to save the above values.

  12. Click Save & Publish.

Summarized information for configuring APIs

Specification

APIImplement tabManage tab
Endpoint typeEndpointEnable Message mediation

In flow


API property nameAPI property value
UK specificationAccountInfo API v3.1.1DynamicN/AMark as checked

<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Accounts/3.1.1/accounts-dynamic-endpoint-insequence-3.1.1.xml

ob-specuk
Payments API v3.1.1DynamicN/AMark as checked <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Payments/3.1.1/payments-dynamic-endpoint-insequence-3.1.1.xmlob-specuk
Funds Confirmation API v3.1.1DynamicN/AMark as checked

<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/FundsConfirmation/3.1.1/funds-confirmation-dynamic-endpoint-insequence-3.1.0.xml

ob-spec uk
Event Notifications API v3.1.0

Dynamic

N/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Notifications/3.1.0/notifications-dynamic-endpoint-insequence-3.1.0.xmlob-specuk

Dynamic ClientRegistration API v3.2

DynamicN/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/DynamicClientRegistration/3.2/dcr-dynamic-endpoint-insequence-3.2.xml ob-api-type dcr
Berlin specificationNextGenPSD2XS2A Framework - 1.3.3DynamicN/AMark as checked<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/berlin-group.org/PSD2API_1.3.3/dynamic-endpoint-insequence-1.3.3.xml ob-spec berlin
STET specificationAccountsAPI v1.4.0DynamicN/AMark as checked

<WSO2_OB_APIM_HOME>/repository/resources/finance/apis/stet/Accounts/1.4.0/accounts-dynamic-endpoint-insequence-1.4.0.xml

ob-specSTET
PaymentsAPI v1.4.0DynamicN/AMark as checked

<WSO2_OB_APIM_HOME>repository/resources/finance/apis/stet/Payments/1.4.0/payments-dynamic-endpoint-insequence-1.4.0.xml

ob-specSTET

Configuring a consent management application

A consent management application is configured in order to manage consents granted to a TPP.

  1. Go to the Identity and Access Management Console at https://localhost:9446/carbon.
  2. On the Main tab, click Home > Identity > Service Providers> Add.
  3. Enter consentmgt as the Service Provider’s name. 
  4. Click Register.
  5. Click Inbound Authentication configuration > OAuth/OpenID Connect configuration > Configure.
  6. Set the values for the following parameters and keep the default value for the other parameters.

    ParameterValue
    OAuth Version2.0
    Allowed Grant Type

    code

    Callback URL

    regexp=(https://localhost:9446/consentmgt|https://localhost:9446/consentmgt)

    The first and second URLs are respectively; redirect and logout URLs.

    Regex-based consumer URLs are supported when defining the callback URL. This enables you to configure multiple callback URLs for one application by entering a regex pattern as the value for the callback URL field.

    You must have the prefix regexp= before your regex pattern. To define a normal URL, you can specify the callback URL without this prefix.


  7. Click Add.

    The OAuth client key/client ID and OAuth client secret are generated. Those are used in Configuring consent management jaggery application.

  8. Open the < WSO2_OB_KM_HOME> /repository/deployment/server/jaggeryapps/consentmgt/configs/conf.json file. Modify the apimHostapplicationIdauthCredentialredirectUrl, and logoutUrl parameters as follows. 

    In authCredential, be sure to encode the CLIENT_ID:CLIENT_SECRET with BASE64ENCODE encoding. 

    {
    	"app" : "consentmgt",
    	"applicationType" : "oauth2",
    	"tenantDomain": "carbon.super",
    	"apimHost":"http://localhost",
    	"apimNioPort":"8280",
    	"apimHttpPort":"9763",
    	"kmHost" : "https://localhost",
    	"kmPort" : "9446",
    	"kmTokenAPI" : "oauth2/token",
    	"kmAuthorizeAPI" : "oauth2/authorize",
    	"applicationId":"<CLIENT_ID>",
    	"authCredential":"<BASE64ENCODED CLIENT CREDENTIALS>",
    	"redirectUrl":"https://localhost:9446/consentmgt",
    	"logoutUrl": "https://localhost:9446/consentmgt",
    	"tokenApiName" : "token",
    	"tokenApiVersion" : "",
    	"authorizeApiName" : "authorize",
    	"authorizeApiVersion" : "",
    	"pagination" : {
    		"limit" : 11,
    		"actualLimit" : 10,
    		"offset": 0
    	},
    	"DeployedSpecification" : "UK"
    }

    Important

    Update the specification under DeployedSpecification parameter appropriately. Possible values are UK, BERLIN, and STET. By default, the value is set to UK.

Try out the Customer Care Portal at  https://localhost:9446/ccportal. Sign in to the Customer Care Portal with the credentials for [email protected] Internal/CustomerCareOfficer.

Troubleshooting

If you get hostname verification errors when accessing the Customer Care portal (https://localhost:9446/ccportal), add the following to the <WSO2_OB_KM_HOME>/bin/wso2server.sh file and restart.

  • Dhttpclient.hostnameVerifier="DefaultAndLocalhost" \
  • Dorg.wso2.ignoreHostnameVerification=true \

Try out the consent revocation apps in WSO2 Open Banking.


What's Next

Now that you have created the APIs that allow you to initiate payments and access account information, let's try out the flows in WSO2 Open Banking:

  • No labels