This documentation is for WSO2 Open Banking version 1.3.0. View documentation for the latest release.
Try Local Setup - WSO2 Open Banking 1.3.0 - WSO2 Documentation
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.3.0.zip (WSO2 Open Banking API Manager) 

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

    Hereafter, the installation locations of  wso2-obam-1.3.0 and wso2-obkm-1.3.0 are called <WSO2_OB_APIM_HOME> and <WSO2_OB_KM_HOME> respectively.

  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 server, 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 MSSQL or Oracle, create the following databases before executing the configure-km.sh file.

      • openbank_am_configdb   

      • openbank_apimgt_statsdb

      • openbank_apimgtdb

      • openbank_consentdb

      • openbank_govdb

      • openbank_iskm_configdb       

      • openbank_mbstoredb

      • openbank_userdb

  2. Set execution permissions to the configure-km.sh file in the <WSO2_OB_KM_HOME>/repository/resources/finance/scripts and run it using the following command:

    ./configure-km.sh
  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. Set execution permissions to the configure-am.sh file and run it.

    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. You are now ready to start the API Manager and Key Manager servers. In the command line, navigate to the <WSO2_OB_KM_HOME> /bin folder, and run the following command:

    ./wso2server.sh -Dsetup
  7. Run the same command from the <WSO2_OB_APIM_HOME>/bin directory to start the AM 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: admin@wso2.com

    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.

      • Create the following users:

        UserRoles
        mark@gold.com

        Internal/creator, Internal/publisher

        ann@gold.comInternal/CustomerCareOfficer
        tom@gold.com

        Internal/approverRole

      • Click Finish.

    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  mark@gold.com .

  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 ob-spec under the additional properties and replace testSpecification with supporting specification (uk/berlin/STET). Click + button to proceed.

  11. 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.0DynamicN/AMark as checked

Select the respective In Sequence in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk directory

ob-specuk
Payments API v3.1.0DynamicN/AMark as checked Select the respective In Sequence in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk directoryob-specuk
Funds Confirmation API v3.1.0DynamicN/AMark as checkedSelect the respective In Sequence in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk directory ob-spec uk
Event Notifications API v3.1.0

Dynamic

N/AMark as checkedSelect the respective In Sequence in the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk directoryob-specuk
Berlin specificationAccountInfo API v1.1.0DynamicN/AMark as checked Select the respective In Sequence in the <WSO2_OB_APIM_HOME> /repository/resources/finance/apis/berlin-group.org directoryob-spec berlin
Payments API v1.1.0DynamicN/AMark as checkedSelect the respective In Sequence in the wso2-obam-version/repository/resources/finance/apis/berlin-group.org directoryob-specberlin

AccountInfo API v1.3.0

Payments API v1.3.0

Confirmation of Funds API v1.3.0

DynamicN/AMark as checkedSelect the respective In Sequence in the <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 checkedSelect the respective In Sequence in the <WSO2_OB_APIM_HOME> /repository/resources/finance/apis/stet directoryob-specSTET
PaymentsAPI v1.4.0DynamicN/AMark as checkedSelect the respective In Sequence in the <WSO2_OB_APIM_HOME> /repository/resources/finance/apis/stet directoryob-specSTET
Now that you have created the APIs that allow you to initiate payments and access account information, let's configure a consent management application.


Configuring a consent management application

A consent management application is configured in order to manage consent granted to an ASPSP. After successful configurations, you can try out the Customer Care Portal. 

  1. On the Main tab of the Identity and Access Management Console, click Home > Identity > Service Providers> Add.
  2. Enter consentmgt as the Service Provider’s name. 
  3. Click Register.
  4. Click Inbound Authentication configuration > OAuth/OpenID Connect configuration > Configure.
  5. 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 redirected 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.


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

  6. Open the  wso2-obkm-version/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.

  7. Enter https://localhost:9446/ccportal URL on a web browser to access the Customer Care portal.

Troubleshooting

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

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


What's Next

We have now come to the end of the Quick Start Guide. There are some additional steps that you can take in order to enhance the security and performance of the Open Banking solution with WSO2's very own additional features.

Configuring strong customer authentication

By default, the consoles are based on basic authentication. You can secure the existing authentication with additional security by configuring Strong Customer Authentication.

Using analytics with WSO2 open banking

You can observe the statistics of the APIs deployed for WSO2 Open Banking using the WSO2 API Management Analytics profile. Click here to see how to configure analytics for WSO2 Open Banking API Manager.

Using workflows with WSO2 open banking

Workflows in WSO2 Enterprise Integrator (EI 6.4.0) allow an ASPSP and a TPP to determine orchestrated patterns to have more control over tasks that are executed within the business process. For example, an administrator can oversee sign-up requests to the API Store, and accept or reject them. This can be done using workflows. Here are the basic configurations to set up workflows using WSO2 Enterprise Integrator in WSO2 Open Banking.

 Click here to view how to work with BPS

  1. Download WSO2 EI 6.4.0 and unzip the file.
  2. Set the path and hostname to EI in the <WSO2_OB_APIM_HOME>/repository/resources/finance/script/startup.properties file.

    If you are using Microsoft SQL Server or Oracle, create databases for bpsdb and bps_configdb.
  3. Go to the <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/wso2ei-bps directory and give the execute permission to the configure-bps.sh file.

  4. Run the configure-bps.sh.

  5. Navigate to the wso2ei-6.4.0/wso2/business-process/bin directory, and execute the following command:

    ./wso2server.sh -Dsetup
  6. Sign in to the API management console https:// localhost :9443/carbon with the following user credentials.

    Sign in with a user whose role is defined as a super admin. Default credentials are:

    Username: admin@wso2.com
    Password: wso2123

  7. On the Main tab, click Resources > Browse.

  8. Navigate to system/governance/apimgt/provider and select workflow-extensions.xml registry file.

  9. In the workflow-extensions.xml registry file, navigate to Content and click Edit as text.

  10. Add the following configurations under to ProductApplicationRegisteration and UserSignup in the registry file:

    ProductApplicationRegisteration
    <ProductionApplicationRegistration executor="com.wso2.finance.tpp.prodaccess.impl.TPPProdAccessWorkFlow">
               <Property name="serviceEndpoint">http://localhost:9765/services/ApplicationRegistrationWorkFlowProcess/</Property>
               <Property name="username">admin@wso2.com@carbon.super</Property>
               <Property name="password">wso2123</Property>
               <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
            </ProductionApplicationRegistration>
    User Sign up
    UserSignUp executor="com.wso2.finance.tpp.signup.impl.TPPSignUpWorkFlow">
               <Property name="serviceEndpoint">http://localhost:9765/services/UserSignupProcess/</Property>
               <Property name="username">admin@wso2.com@carbon.super</Property>
               <Property name="password">wso2123</Property>
               <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
               <Property name="aispRole">internal/aispRole</Property>
               <Property name="pispRole">internal/pispRole</Property>
               <Property name="piispRole">internal/piispRole</Property>
           </UserSignUp>
You have now successfully configured workflows. You can configure workflows according to the business processes in your system. For more information on the usage of workflows, see TPP Onboarding.


# Specify the hostname you want to configure
APIM_HOSTNAME=localhost
IAM_HOSTNAME=localhost
  • No labels