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 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 API Manager and Key Manager 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

     If you are using an 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 AU

     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...

     Database	openbank_apimgtdb
     Table	AM_APPLICATION_REGISTRATION
     Field	INPUTS
     Data type	CLOB

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

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 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/

   The <DeployedSpecification> value in the following files are updated according to your specification at runtime. Possible values for the DeployedSpecification tag are UK, BERLIN, AU, and STET

   • <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml 
   • <WSO2_OB_APIM_HOME>/repository/deployment/server/jaggeryapps/store/site/conf/site.json
   • <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml
   • <WSO2_OB_KM_HOME>/repository/deployment/server/jaggeryapps/ccportal/configs/conf.json
   • <WSO2_OB_KM_HOME>/repository/deployment/server/jaggeryapps/consentmgt/configs/conf.json
5. This step is required only if you're setting up Open Banking for AU:

   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, update the following configurations in the  <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml file. 

      <UserAccessTokenDefaultValidityPeriod>120</UserAccessTokenDefaultValidityPeriod>

   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_KM_HOME>/repository/conf/finance/open-banking.xml file and set <ValidateAccountIdOnRetrieval> to true: 

      <ValidateAccountIdOnRetrieval>true</ValidateAccountIdOnRetrieval>

   3. To revoke the consent with the access token, open <WSO2_OB_KM_HOME>/repository/conf/identity/identity.xml and add the following under the <EventListener> tag:

      <EventListener enable="true" name="com.wso2.finance.open.banking.identity.extensions.listeners.TokenRevocationListener" orderId="100" type="org.wso2.carbon.identity.core.handler.AbstractIdentityHandler"/>

   4. To obtain a Mutual Transport Layer Security (MTLS) certificate bound access token, open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file and configure the following: 

      1. Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file and do the following:

         1. Update the following configuration under <APISecurity><EnableMTLSTokenBinding> to enable this feature.

            <EnableMTLSTokenBinding>true</EnableMTLSTokenBinding>

         2. Configure the client certificate header name using the <CertificateManagement><ClientAuthenticationHeader> property as follows: 

            <ClientAuthenticationHeader>x-wso2-mutual-auth-cert</ClientAuthenticationHeader>

      2. Add the following handler to the <WSO2_OB_APIM_HOME>/repository/deployment/server/synapse-configs/default/api/_TokenAPI_.xml file. 

         <handler class="com.wso2.finance.open.banking.mtls.validator.handler.GatewayClientAuthenticationHandler"/>

   5. To use Identifier-first as the primary authenticator:

      1. Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml file and add the following under the <Server> <SCA> tags: 

         <!--Configure the primary authenticator / 1st step authenticator-->
         <PrimaryAuthenticator>
         	<Name>IdentifierExecutor</Name>
         	<DisplayName>identifier-first</DisplayName>
         </PrimaryAuthenticator>

      2. To configure SMS OTP as an identity provider for Identifier-first, update the <WSO2_OB_KM_HOME>/repository/conf/identity/application-authentication.xml file by adding the following. 

         <AuthenticatorConfig name="SMSOTP" enabled="true">
             <Parameter name="usecase">subjectUri</Parameter>
             <Parameter name="secondaryUserstore">primary</Parameter>

      3. Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml file. Update the value of the <IdpName> parameter with the name of your identity provider. See Configuring consumer authentication, for more information. 

         <SCA>
             <IdpName>SMSAuthentication</IdpName>

6. You are now ready to start the servers. In the command line, navigate to the <WSO2_OB_KM_HOME>/bin directory, and run the following command to start the Key Manager server:

   ./wso2server.sh -Dsetup

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

   ./wso2server.sh -Dsetup

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

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 (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 Additional properties according to the API you're publishing. For more information, see the summarized information table.

11. Click the + button to save the properties.

12. Click Save & Publish.

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. 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.

   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.

   

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 apimHost, applicationId, authCredential, redirectUrl, 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, AU, and STET. By default, the value is set to UK.

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 AU

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 AU