Try Local Setup

This document provides you with instructions on how to configure and try out WSO2 Open Banking in your local environment.

Prerequisites

Setting up the databases and starting the servers

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

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

   • Specify the hostnames for the API Management and Identity and Access Management servers.

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

   • Configure the databases related properties.

     Database Property	Description
     DB_TYPE	Type of the database you installed
     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 - PostgreSQL JDBC Driver = org.postgresql.Driver

     If you are using a MS SQL, Oracle, or a PostgreSQL database, see the following topics and configure the databases.

     • Configuring Databases for UK
     • Configuring Databases for Berlin
     • Configuring Databases for Australia

2. Run the <WSO2_OB_IAM_HOME>/repository/resources/finance/scripts/configure-iam.sh file according to your specification:

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

    Click here to see the field to be updated...

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.

   If you are setting up WSO2 Open Banking for Berlin:

   WSO2 Open Banking contains a mock back end. To configure the mock back end for Berlin specification:

   • Open the deployment.toml files: 

     • <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml

     • <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml

   • Update the mock back end URL as follows: 

     [open_banking]
     sharable_accounts_retrieve_endpoint ="https://localhost:9443/api/openbanking/backend-berlin/services/v130/accounts/shareable" 
     payable_accounts_retrieve_endpoint = "https://localhost:9443/api/openbanking/backend-berlin/services/v130/accounts/payable"

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

    Click here for more information

   The configure.sh scripts configure the solution according to the given specification:

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

   • UK specification - https://www.openbanking.org.uk/
   • Berlin specification - https://www.berlin-group.org/
   • AU specification - https://consumerdatastandardsaustralia.github.io/standards/
   • STET specification - https://www.stet.eu/en/psd2/

   If you are setting up WSO2 Open Banking for Australia:

   1. According to Consumer Data Standards , an access token must expire between 2 minutes to 10 minutes after issuing it.  To configure the validity period of the access token in seconds, add the given configurations to the  <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml  file. 

      [oauth.token_validation]
      user_access_token_validity = 120

   2. To enable Request-URI validation during the account retrieval process; validate the account ID against the account ID in the consent, open  the <WSO2_OB_IAM_HOME>/repository/conf/deployment.toml   file and set the following property to  true: 

      [open_banking.account_id_validation_on_retrieval]
      enable = true

5. You are now ready to start the servers. In the command line, navigate to the  <WSO2_OB_IAM_HOME>/bin  directory, and run the following command to start the Identity and Access Management server:

   ./wso2server.sh  

6. Run the following command from the <WSO2_OB_APIM_HOME>/bin directory to start the API Manager server:

   ./wso2server.sh  

Configuring consumer authentication

Configuring users and roles

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 Portal (https://localhost:9443/publisher) with the credentials for mark@gold.com.
   

2. In the APIs tab, select CREATE NEW API > I Have an Existing REST API. 

   

3. Set the Input Type to OpenAPI File. 
   
4. Click BROWSE FILE TO UPLOAD and select the Swagger definition (.yaml file) from the <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/ directory based on your specification and version of the API.
   
5. Click Next. 
6. Set the endpoint according to your API. For more details, see the table below.
7. Set the business plan to Unlimited : Allows unlimited  requests unless you want to limit the requests. 
   
8. Click Create to create the API.
9. Once you get the message that the API is successfully updated, go to Runtime Configurations using the left menu panel.
   
10. Click the edit button under Request > Message Mediation. 
    
11. Now, select the Custom Policy option.
12. Upload the relevant in-sequence file and click SELECT. For more details, see the table below. 
    
13. Scroll down and click SAVE.
14. Now, go to Properties using the left menu panel.
    
15. Click Add New Property.
    
16. Add the API Properties according to your API and click the Add button.  For more details, see the table below.
    For example:
    
17. Click SAVE.
18. Go back to Overview using the left menu panel. 
    
19. Click PUBLISH.
    
20. The published API is available in the Developer Portal at https://localhost:9443/devportal.

Summarized information for configuring APIs

Configuring a consent management application

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

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. By default, the mode is set to Manual Configuration. Leave it as it is.
4. Enter consentmgt as the Service Provider’s name. 
   
5. Click Register.
6. Click Inbound Authentication configuration > OAuth/OpenID Connect configuration > Configure.
   

7. Set the values for the following parameters and keep the default value for the other parameters.

   Parameter	Value
   OAuth Version	2.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.

   

8. Click Add.
   

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

   

9. Open the < WSO2_OB_IAM_HOME> /repository/deployment/server/jaggeryapps/consentmgt/configs/conf.json file. Modify the following parameters:

   Parameter	Description
   apimHost	Hostname of the API Management server
   applicationId	OAuth Client Key generated in the above step
   authCredential	Base64 encoded CLIENT_ID:CLIENT_SECRET in the given format.
   redirectUrl
   logoutUrl
   DeployedSpecification	Possible values are UK, BERLIN, AU, and STET. By default, the value is set to UK.

   Given below is a sample file for the Australian specification:

   
   

   {
   	"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" : "AU"
   }

Try out the consent revocation apps in WSO2 Open Banking.

• Configuring Consent Revocation Apps for UK
• Configuring Consent Revocation Apps for Berlin
• Configuring Consent Management Dashboards for Australia

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:

• Try Out WSO2 Open Banking UK
• Try Out WSO2 Open Banking Berlin
• Try Out WSO2 Open Banking for Australia