Try Local Setup

This document provides you with instructions on how to configure and try out WSO2 Open Banking 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

Download OpenJDK 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
```
Download and unzip the following files:
- wso2-obiam-2.0.0.zip (WSO2 Open Banking Identity and Access Management Module)
- wso2-obam-2.0.0.zip (WSO2 Open Banking API Management Module)
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 in the Download WUM page to download, and install WUM in your environment. For more information on how to use WUM, see the /wiki/spaces/updates/pages/16318500.
  1. Add the necessary product packs using the commands given below:
    
    wum add wso2-obam-2.0.0 wum add wso2-obiam-2.0.0
    
    Update the product packs using the commands given below:
    
    wum update wso2-obam-2.0.0 wum update wso2-obiam-2.0.0
    
    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-3.1.0 wum update wso2am-analytics-3.1.0 wum add wso2-obbi-2.0.0 wum update wso2-obbi-2.0.0
    
    WSO2 OB APIM Analytics provides the API analytics feature.
    WSO2 OB BI 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:

Repeat this step for all the products in the solution:
wso2-obiam-2.0.0
wso2-obam-2.0.0
wso2-obbi-2.0.0
wso2am-analytics-3.1.0
This document refers to the file paths of the product packs for the Identity and Access Management module, API Management module, API Manager Analytics, and Enterprise Integrator as <WSO2_OB_IAM_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:

Repeat this step for both the wso2-obiam-2.0.0 and wso2-obam-2.0.0 products.
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 Identity and Access Management (IAM) and the API Manager (APIM) servers according to the open banking specification, as follows:

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.

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...
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.
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
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  
```
Run the following command from the <WSO2_OB_APIM_HOME>/bin directory to start the API Manager server:
```
./wso2server.sh  
```

Configuring consumer authentication

If you're setting up WSO2 Open Banking for Australia:

By default, WSO2 Open Banking comes with basic authentication configured. For CX guideline aligned experience, you can configure Identifier-first authentication paired with a secondary identity provider. In this section, we configure SMS OTP as the secondary identity provider.

Click here to see how it is done

Configuring Identifier-first authentication

The Identifier-first login enables identifying the individuals prior to authenticating them. It retrieves the identity of the user without using authentication information and uses that identity to control the authentication flow. For more information, see Identifier-first Flow Handler.

The Identifier-first is a handler that can be configured at any step in the authentication flow. However, it is not an authenticator by itself and needs to be configured along with another authenticator for the authentication process to be successful.

Configuring SMS OTP Authenticator

Follow the steps below to configure SMS OTP Authenticator.

Start the WSO2 Open Banking Identity and Access Management (WSO2 OB IAM) server. Sign in to the Management Console (https://<WSO2_OB_IAM_HOST>:9446/carbon) as an administrator.
Navigate to the Main menu to access the Identity menu. Click Add under Identity Providers.
Fill the Basic Information section and name this identity provider SMSAuthentication .
Expand the Federated Authenticators > SMS OTP Configuration section.
Select both the Enable and Default checkboxes. This is to enable and make the SMSAuthentication authenticator the default one.
Based on your SMS provider, fill out the SMS OTP configurations.
If Twilio is used as the SMS provider,
Go to https://www.twilio.com/try-twilio and create an account.
While registering the account, verify your mobile number and click on console home https://www.twilio.com/console to get free credits (Account SID and Auth Token).
Twilio uses a POST method with headers and the text message and phone number are sent as the payload. So the fields would be as follows.

If you pass the text message and the phone number in any field, you have to replace them with $ctx.num and $ctx.msg respectively.
E.g., Body=$ctx.msg&To=$ctx.num&From=+12345678
Currently, the WSO2 Open Banking Identity and Access Management module supports only the following SMS providers.
Click Register to add the Identity Provider.
Open the <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml file. Update the value of the idp_name parameter with the name of the identity provider.
```
[open_banking.sca]
idp_name = "SMSAuthentication"
```
To verify the SMSAuthentication authenticator:
Click here to see how to verify the SMSAuthentication authenticator configurations...
Follow the steps below to verify whether the SMSAuthentication authenticator is properly configured.
Create an application in the WSO2 Open Banking API Management module.
Generate Access Tokens and Security Keys.
Log in to the Management Console as the super admin.
In the Main menu under the Identity section, click List under Service Providers. The list of service providers created appears.
Select the service provider with the application name you created in step A. The service provider name is in the following format:
<WSO2_OB_APIM_ USERNAME>_<APPLICATION_NAME>_<ENVIRONMENT>
Click on the corresponding Edit link.
Expand Local & Outbound Authentication Configuration. Select Advanced Configuration. You can configure additional authentication steps and additional authentication options.
If you have successfully configured the SMSAuthentication authenticator, you will see how it’s configured as the Federated Authenticator under Authentication Step Configuration > Step 2.

Add a Local Claim. 
 Click here to see how to add a Local Claim...
In the  Main  menu under the  Identity  section, click Add   under  Claims 
Select Add Local Claim  
 
Use the following configurations:
    Parameter NameTest Configuration
Claim URI http://wso2.org/claims/identity/failedSmsOtpAttempts 
Display NameFailed SMS OTP Attempts
DescriptionFailed SMS OTP Attempts
Mapped Attribute  User Store Domain Name
PRIMARY
 Mapped AttributefailedSmsOtpAttempts
Click    Add.

Configure a Login Policy:
Click here to see how to configure a Login Policy...
1. In the Main menu under the Identity section, click Resident under Identity Providers.
2. Expand Login Policies > Account Locking.
3. Select the Account Lock Enabled checkbox to enable the account locking.
4. Set the value of Maximum Failed Login Attempts to 5.
5. Click Update.
Add mobile phone as a mandatory claim:
Click here to see how to add mobile phone as a mandatory claim...
1. In the Main menu under the Identity section, click List under Claims
2. Select http://wso2.org/claims from the list.
3. Scroll down the available claims for http://wso2.org/claims and locate the Mobile claim.
4. Click Edit.
5. Select the Required checkbox to make mobile a mandatory claim.
6. Click Update.
When you log in using the admin username in the authentication flow, a notification will pop up asking for the mobile number in the first attempt to log in. Enter your mobile in the format of 94123456789.

Restart the servers after configuration changes.

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:

If you are setting up WSO2 Open Banking UK:

If you are using WSO2 Open Banking API Manager Level 2.0.0.134 or above with WSO2 Open Banking Identity Server Level 2.0.0.144 or above, follow these steps:

Open the <WSO2_OB_APIM_HOME>/repository/resources/api_templates/velocity_template.xml file.
Find the <handler class="com.wso2.finance.open.banking.common.identity.validation.SignatureAlgorithmValidatorHandler"/> tag.

Replace the above handler with the following:

<handler class="com.wso2.finance.open.banking.gateway.validation.SignatureAlgorithmValidatorHandler"/>

Restart the API Manager server.

Sign in to the API Publisher Portal (https://localhost:9443/publisher) with the credentials for mark@gold.com.
In the APIs tab, select CREATE NEW API > I Have an Existing REST API.
Set the Input Type to OpenAPI File.
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.
Click Next.
Set the endpoint according to your API. For more details, see the table below.
Set the business plan to Unlimited : Allows unlimited requests unless you want to limit the requests.
Click Create to create the API.
Once you get the message that the API is successfully updated, go to Runtime Configurations using the left menu panel.
Click the edit button under Request > Message Mediation.
Now, select the Custom Policy option.
Upload the relevant in-sequence file and click SELECT. For more details, see the table below.
Scroll down and click SAVE.
Now, go to Properties using the left menu panel.
Click Add New Property.
Add the API Properties according to your API and click the Add button. For more details, see the table below.
For example:
Click SAVE.
Go back to Overview using the left menu panel.
Click PUBLISH.
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.

Go to the Identity and Access Management Console at https://localhost:9446/carbon.
On the Main tab, click Home > Identity > Service Providers > Add.
By default, the mode is set to Manual Configuration. Leave it as it is.
Enter consentmgt as the Service Provider’s name.
Click Register.
Click Inbound Authentication configuration > OAuth/OpenID Connect configuration > Configure.

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.

Click Add.

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

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 Customer Care Portal at https://localhost:9446/ccportal.Sign in to the Customer Care Portal with the credentials for ann@gold.com Internal/CustomerCareOfficer.

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:

Parameter Name	Test Configuration
Claim URI	http://wso2.org/claims/identity/failedSmsOtpAttempts
Display Name	Failed SMS OTP Attempts
Description	Failed SMS OTP Attempts
Mapped Attribute	User Store Domain Name	PRIMARY
Mapped Attribute	Mapped Attribute	failedSmsOtpAttempts