

Regulatory Aggregator - Quick Start Guide¶

This section guides you to set up WSO2 Open Banking Accelerator as a Regulatory Aggregator.

Setting up JAVA_HOME¶

Install Oracle Java 8 or above to your node.
Set your JAVA_HOME environment variable to point to the directory where the Java Development Kit (JDK) is installed. For more information, see Setting up JAVA_HOME.

Installing base products¶

The accelerators run on top of WSO2 Identity Server and WSO2 API Manager, which are referred to as base products. Before setting up the accelerator, download and install the base products:

Install WSO2 Identity Server 5.11.0
Install WSO2 API Manager 4.1.0 or WSO2 API Manager 4.0.0

Installing WSO2 Open Banking Accelerator¶

If you have an active WSO2 Open Banking subscription, contact us via WSO2 Online Support System to download Open Banking Accelerator 3.0.0.

Note

If you don't have a WSO2 Open Banking subscription, contact us for more information.
Extract the downloaded WSO2 Open Banking Accelerator zip files. WSO2 Open Banking Accelerator contains the following accelerators.
- wso2-obiam-accelerator-3.0.0
- wso2-obam-accelerator-3.0.0
Go to the root directories of WSO2 Identity Server and API Manager. These root directories are the product homes.

Tip

This documentation will refer to the product homes as <IS_HOME> and <APIM_HOME> respectively.

Getting WSO2 Updates¶

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 the base products and accelerators using the relevant script.

Go to the /bin directory and run the WSO2 Update tool:
On Linux
```
./wso2update_linux 
```
On Mac
```
./wso2update_darwin
```
On Windows
```
./wso2update_windows.exe
```
Repeat this step for all the products and accelerators. For more information, see Getting WSO2 Updates.

Setting up servers¶

This setup consists of the following components. We are using 2 WSO2 Identity Servers (vanilla) as the identity servers of banks ABC and DCB. However, you can use any standard identity servers with this setup.

Tip

Port offsets are mentioned assuming that this setup is done using a single node. If you are using multiple nodes, you can ignore the port offsets.

regulatory_aggregator_setuo

Take 3 copies of the updated WSO2 Identity Server.
Place 2 of them in a preferred location in the node. These 2 will be the identity servers of the banks.

Setting up accelerators¶

This section explains how to set up the remaining WSO2 Identity Server and API Manager.

Place the Identity Server and API Manager base products in the node.
Place the relevant accelerator in their respective product homes:

Accelerator Directory location to place the Accelerator

wso2-obiam-accelerator-3.0.0 <IS_HOME>

wso2-obam-accelerator-3.0.0 <APIM_HOME>

Tip

This documentation will refer to above accelerator root directories as <OB_IS_ACCELERATOR_HOME> and <OB_APIM_ACCELERATOR_HOME> respectively.
To copy the accelerator files to the API Manager server, go to the <APIM_HOME>/<OB_APIM_ACCELERATOR_HOME>/bin directory and run the merge.sh script as follows:
```
./merge.sh
```
To copy the accelerator files to the Identity Server, go to the <IS_HOME>/<OB_IS_ACCELERATOR_HOME>/bin directory and run the merge.sh script as follows:
```
./merge.sh
```
To configure the Identity Server with the API Manager, install WSO2 IS Connector.

Extract the wso2is-extensions zip file. Copy the following files to the Identity Server as follows:

File to copy	Copy to
`wso2is-extensions-1.2.10/dropins/wso2is.key.manager.core-1.2.10.jar`	`<IS_HOME>/repository/components/dropins`
`wso2is-extensions-1.2.10/dropins/wso2is.notification.event.handlers-1.2.10.jar`	`<IS_HOME>/repository/components/dropins`
`wso2is-extensions-1.2.10/webapps/keymanager-operations.war`	`<IS_HOME>/repository/deployment/server/webapps`

Configuring database scripts¶

Open the <APIM_HOME>/<OB_APIM_ACCELERATOR_HOME>/repository/conf/configure.properties file.
Configure the hostnames of the API Manager and Identity Server.
Configure databases related properties and database names.
Open the <IS_HOME>/<OB_IS_ACCELERATOR_HOME>/repository/conf/configure.properties file and repeat steps 2 and 3.
Run the configure.sh files in <APIM_HOME>/<OB_APIM_ACCELERATOR_HOME>/bin and <IS_HOME>/<OB_IS_ACCELERATOR_HOME>/bin respectively:
```
./configure.sh
```

Configuring regulatory aggregator¶

Download the regulatory aggregator resources.

Copy the following files to the Open Banking Identity Server:

File to copy	Copy to
`com.wso2.openbanking.sample.aggregator.gateway-3.0.0.96-SNAPSHOT.jar`	`<APIM_HOME>/repository/components/libs`
`com.wso2.openbanking.sample.aggregator.identity-3.0.0.96-SNAPSHOT.jar`	`<IS_HOME>/repository/components/libs`
`org.wso2.carbon.identity.custom.federated.authenticator-1.0.0.jar`	`<IS_HOME>/repository/components/dropins`

Copy the provided api#openbanking#backend.war file to the <BANK_IS_HOME>/repository/deployment/server/webapps directories of ABC and DCB banks' identity servers.
- This is to provide mock bank APIs from ABC and DCB banks.
Open the <ABC_IS_HOME>/repository/conf/deployment.toml file of ABC bank and configure it as follows:

a. Set the offset to 1:
```
[server]
offset = 1
```
b. Add the following configurations to the end of the file. This is to protect the added web application with OAuth2 Authentication.
```
[[resource.access_control]]
context = "(.*)/api/openbanking/backend/(.*)"
secure="true"
http_method="all"
permissions=["/permission/admin"]
allowed_auth_handlers = "OAuthAuthentication"
```
Repeat step 4 for DBC bank's <DBC_IS_HOME>/repository/conf/deployment.toml. But set the offset to 2.
Configure an executor: a. Open the <APIM_HOME>/repository/conf/deployment.toml file. b. Locate the executors section and add the following as the 6^th executor of the Default flow.
```
[[open_banking.gateway.openbanking_gateway_executors.type.executors]] name = "com.wso2.openbanking.sample.aggregator.gateway.AggregatorExecutor" priority = 6
```
For example:
Configure the Open Banking Identity Server:

a. Open the <IS_HOME>/repository/conf/deployment.toml file.

b. Under the [authentication.endpoint.redirect_params] tag, add 5 additional parameters as follows:
```
parameters = ["sessionDataKeyConsent","relyingParty", "authenticators", "authFailureMsg", "authFailure", "scope", "client_id","redirect_uri", "response_type", "state"]
```
c. Change the class parameter under the [[oauth.custom_response_type]] tag as follows:
```
class = "com.wso2.openbanking.sample.aggregator.identity.AggregatorHybridResponseTypeHandler"
```
d. Update the following [open_banking.dcr] configurations:
```
jwks_url_sandbox = "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/0015800001HQQrZAAX.jwks"
jwks_url_production = "https://keystore.openbankingtest.org.uk/0015800001HQQrZAAX/0015800001HQQrZAAX.jwks"
applicationupdater = "com.wso2.openbanking.sample.aggregator.identity.AggregatorApplicationUpdaterImpl"
```
e. Locate the [[open_banking.consent.authorize_steps.retrieve]] tag with priority=2 to and change its class to class = "com.wso2.openbanking.sample.aggregator.identity.AggregatorConsentDisplayStep".

For example:

f. Locate the [[open_banking.consent.authorize_steps.persist]] tag with priority=1 to and change its class to class = "com.wso2.openbanking.sample.aggregator.identity.AggregatorConsentCreateStep".

For example:

g. Change the validator attribute under the [open_banking.consent.validation] tag as follows:
```
validator="com.wso2.openbanking.sample.aggregator.identity.AggregatorConsentValidator"
```
h. Update the value of request_object_validator under the [open_banking.identity.extensions] tag:
```
request_object_validator="com.wso2.openbanking.accelerator.identity.auth.extensions.request.validator.OBRequestObjectValidator"
```
i. Under the [open_banking.identity.extensions] tag, add the given new parameter:
```
response_type_handler="com.wso2.openbanking.sample.aggregator.identity.OBAggregatorResponseTypeHandler"  
```
Upload the root and issuer certificates in OBIE (Sandbox certificates/ Production certificates) to the client trust stores:
- <APIM_HOME>/repository/resources/security/client-truststore.jks
- <IS_HOME>/repository/resources/security/client-truststore.jks
Use the following command:
```
keytool -import -alias <alias> -file <certificate_location> -storetype JKS -keystore <truststore_location> -storepass wso2carbon
```

Starting severs¶

Start all Identity Servers (including the ABC and DBC banks' servers). Go to the <IS_HOME>/bin directory using a terminal and run the wso2server script:
On Linux/macOS
```
./wso2server.sh
```
On Windows
```
./wso2server.bat
```
Start the API Manager server. Go to the <APIM_HOME>/bin directory using a terminal and run the api-manager script:
On Linux/MacOS
```
./api-manager.sh
```
On Windows
```
./api-manager.bat
```

Creating Service Providers¶

This section explains how to create Service Providers in the Identity Servers at the banks.

Log in to the Management Console of ABC bank's Identity Server at https://localhost:9444/carbon/ using admin credentials.
On the Main menu, click Identity > Service Providers > Add.
Fill in the Service Provider Name as ABC_BANK:
Click Register to add the new service provider. The Service Provider Details page appears.
Expand the Inbound Authentication Configuration > OAuth/OpenID Connect Configuration section.
Click Configure.
Set the Callback URL to https://localhost:9446/commonauth.
Click Add. Note that client key and client secret get generated. Note these values for future use.
Expand the Local and Outbound Authentication Configuration section.
Select the Skip Login Consent box.
Click Update and save the configurations.
Log in to the Management Console of DBC bank's Identity Server at https://localhost:9445/carbon/ and repeat the same steps to create the DBC_BANK Service Provider.

Configuring a Federated Authenticator¶

This section explains how to configure a Federated Authenticator in the Open Banking Identity Server.

Log in to the Management Console of the Identity Server at https://localhost:9446/carbon/ using admin credentials.
On the Main tab, click Identity > Identity Providers > Add.
Fill in the Identity Provider Name as Bank-Identity-Server.
Expand Federated Authenticators > Custom Federated Authenticator.
Fill in the information regarding ABC and DCB banks.
- Provide the client key and client secret generated from the section above.
- Extract the authorization endpoint and token endpoint from the well-known endpoints of each bank's identity server.
- Set the Callback URL to https://localhost:9446/commonauth.
Click Register.

Configuring Adaptive Authentication Script¶

This section explains how to configure an Authentication Script in the Open Banking Identity Server.

Before you begin

Follow the Dynamic Client Registration documentation and create a DCR Application.

Log in to the Management Console of the Identity Server at https://localhost:9446/carbon/ using admin credentials.
On the Main menu, click Identity > Service Providers > List. The list of service providers you added appears.
Locate the service provider generated for DCR and click on the corresponding Edit link.
Expand Local & Outbound Authentication Configuration.
Select Advanced Configuration as the Authentication Type.

Use the following script for Script Based Adaptive Authentication:

var onLoginRequest = function(context) {
    executeStep(1, {
        stepOptions: {
            forceAuth: 'true'
        }
    }, {});
};

Make sure that the previously created Bank-Identity-Server is the selected Authentication Step. For example:
Click Update.

Deploying Accounts API¶

Log in to API Publisher, Deploy, and Publish the Accounts API by following the Try out API Flow documentation.

Note

Use the provided accounts-dynamic-endpoint-insequence.xml file as the Message Mediation instead of the default file.

Top

Accelerator	Directory location to place the Accelerator
wso2-obiam-accelerator-3.0.0	`<IS_HOME>`
wso2-obam-accelerator-3.0.0	`<APIM_HOME>`