Configuring Open Banking API Management for Berlin

Follow the below-mentioned steps to deploy the Open Banking API Management (WSO2-OB-APIM) module.

Copy the <WSO2_OB_APIM_HOME>/repository/resources/finance/scripts/wso2-obam-conf/deployement/bg/deployment.toml file to the <WSO2_OB_APIM_HOME>/repository/conf/ directory and replace the existing one.
Do the below-mentioned configurations in <WSO2_OB_APIM_HOME>/repository/conf/deployment.toml and restart the Open Banking API Manager server.

Make sure the Identity and Access Management server is running before you start the API Manager server.
To start, go to the <WSO2_OB_APIM_HOME>/bin directory and execute the following command:
```
./wso2server.sh
```

Configuration Functionality

1.

# for registry data
[database.shared_db]
url = "jdbc:mysql://<MYSQL_DB_HOST>:3306/openbank_govdb?autoReconnect=true&useSSL=false"
username = "<username>"
password = "<password>"
driver = "<driver_class_name>"

[database.shared_db.pool_options]
maxActive = "150"
maxWait = "60000"
minIdle ="5"
testOnBorrow = true
validationQuery="SELECT 1"
#Use below for oracle
#validationQuery="SELECT 1 FROM DUAL"
validationInterval="30000"
defaultAutoCommit=false

# for api manager data
[database.apim_db]
url = "jdbc:mysql://<MYSQL_DB_HOST>:3306/openbank_apimgtdb?autoReconnect=true&useSSL=false"
username = "<username>"
password = "<password>"
driver = "<driver_class_name>"

[database.apim_db.pool_options]
maxActive = "150"
maxWait = "60000"
minIdle ="5"
testOnBorrow = true
validationQuery="SELECT 1"
#Use below for oracle
#validationQuery="SELECT 1 FROM DUAL"
validationInterval="30000"
defaultAutoCommit=false

# for am-config registry
[database.config]
url = "jdbc:mysql://<MYSQL_DB_HOST>:3306/openbank_am_configdb?autoReconnect=true&useSSL=false"
username = "<username>"
password = "<password>"
driver = "<driver_class_name>"

[database.config.pool_options]
maxActive = "150"
maxWait = "60000"
minIdle ="5"
testOnBorrow = true
validationQuery="SELECT 1"
#Use below for oracle
#validationQuery="SELECT 1 FROM DUAL"
validationInterval="30000"
defaultAutoCommit=false

# for user management data
[[datasource]]
id="WSO2UM_DB"
url = "jdbc:mysql://<MYSQL_DB_HOST>:3306/openbank_userdb?autoReconnect=true&useSSL=false"
username = "<username>"
password = "<password>"
driver = "<driver_class_name>"
jmx_enable=false
pool_options.maxActive = "150"
pool_options.maxWait = "60000"
pool_options.minIdle = "5"
pool_options.testOnBorrow = true
pool_options.validationQuery="SELECT 1"
#Use below for oracle
#validationQuery="SELECT 1 FROM DUAL"
pool_options.validationInterval="30000"
pool_options.defaultAutoCommit=false

# for getting statistics to API Manager

id="WSO2AM_STATS_DB"
url = "jdbc:mysql://<MYSQL_DB_HOST>:3306/openbank_apimgt_statsdb?autoReconnect=true&useSSL=false"
username = "<username>"
password = "<password>"
driver = "<driver_class_name>"
jmx_enable=false
pool_options.maxActive = "150"
pool_options.maxWait = "60000"
pool_options.minIdle = "5"
pool_options.testOnBorrow = true
pool_options.validationQuery="SELECT 1"
#Use below for oracle
#validationQuery="SELECT 1 FROM DUAL"
pool_options.validationInterval="30000"
pool_options.defaultAutoCommit=false

[open_banking_database]
config.url = "jdbc:mysql://<MYSQL_DB_HOST>:3306/openbank_openbankingdb?autoReconnect=true&useSSL=false"
username = "<username>"
password = "<password>"
driver = "<driver_class_name>"

[open_banking_database.config.pool_options]
maxActive = "150"
maxWait = "60000"
minIdle ="5"
testOnBorrow = true
validationQuery="SELECT 1"
#Use below for oracle
#validationQuery="SELECT 1 FROM DUAL"
validationInterval="30000"
defaultAutoCommit=false

Update the URL, username, password, and driverClassName with the database credentials, and relevant database driver name. See the sample MySQL configuration on the left column.

If you are using Oracle, update the validationQuery in each datasource by uncommenting the below configuration:

#Use below for oracle
validationQuery="SELECT 1 FROM DUAL"

2.

[super_admin]
username = "<username>"
password = "<password>"
create_admin_account = true

[realm_manager]
data_source= "WSO2UM_DB"

[user_store]
type = "database_unique_id"
class = "org.wso2.carbon.user.core.jdbc.UniqueIDJDBCUserStoreManager"

[user_store.properties]
UsernameJavaRegEx = "a-zA-Z0-9@._-{3,30}$"
UsernameJavaScriptRegEx = "^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,4}$"
SCIMEnabled = false
IsBulkImportSupported = false
LeadingOrTrailingSpaceAllowedInUserName = false
UsernameWithEmailJavaScriptRegEx = "^[\\S]{3,30}$"

[authorization_manager]
class = "org.wso2.carbon.user.core.authorization.JDBCAuthorizationManager"

[authorization_manager.properties]
AdminRoleManagementPermissions = "/permission"
AuthorizationCacheEnabled = true
GetAllRolesOfUserEnabled = false

Update username, password, UsernameJavaRegEx, UsernameJavaScriptRegEx, IsBulkImportSupported, and UsernameWithEmailJavaScriptRegEx

properties.

3.

[[apim.gateway.environment]]
http_endpoint = "http://<WSO2_OB_APIM_HOST>:${http.nio.port}"
https_endpoint = "https://<WSO2_OB_APIM_HOST>:${https.nio.port}"

Update the endpoint URLs for the APIs hosted in this API Gateway.

4.

[apim.analytics]
enable = false

receiver_username = "$ref{super_admin.username}@carbon.super"
store_api_username = "$ref{super_admin.username}@carbon.super"

Enable analytics for the API Manager by setting the value for enable property as true and update the reciever_username, store_api_username.

5.

[apim.key_manager]
service_url = "https://<WSO2_OB_IAM_HOST>:9446${carbon.context}services/"
key_manager_client_impl = "com.wso2.finance.open.banking.sca.keymanager.SCABasedKeyManagerClient"

Add the port to the service_url parameter of authentication service and update the key_manager_client_impl parameter with relevant values.

6.

[apim.oauth_config]
enable_outbound_auth_header = true

Remove OAuth headers from an outgoing message by updating the value for enable_outbound_auth_header as false.

7.

white_listed_scopes = ["^device_.*", "openid", "^OB_.*", "^TIME_.*"]

By default, white_listed_scopes are configured as in the left column. If you want to change, update with the relevant values.

8.

[apim.devportal]
enable_comments = false
enable_ratings = false

By default, display the comment editing facility and ratings are set to "false". If you want to enable, set the values for enable_comments and enable_ratings as true.

9.

[apim.throttling]
enable_data_publishing = true
jms.topic_connection_factory = "amqp://admin!wso2.com!carbon.super:$ref{super_admin.password}@clientid/carbon?brokerlist='tcp://${carbon.local.ip}:${jms.port}'"
receiver_username = "$ref{super_admin.username}@carbon.super"

By default jms.topic_connection_factory is configured. If you want to change, update with relevant values.

10.

[open_banking]
deployed_spec = "BERLIN"

Define the specification that you plan to deploy.

11.

[open_banking.berlin.sca]
selected_approach = "REDIRECT"

Configure an SCA approach. Currently, the solution supports only the Redirect approach (OAUTH2 is subsumed by this).

12.

[open_banking.berlin.sca]
oauth_metadata_endpoint = "https://<WSO2_OB_APIM>:<HOST>/.well-known/openid-configuration"

Configure the endpoint to retrieve OIDC Discovery metadata.

13.

[open_banking.berlin]
accounts_retrieve_endpoint = "https://<WSO2_OB_APIM>:<HOST>/api/openbanking/backend-berlin/services/accounts/accounts"
account_consent_self_link = "https://<WSO2_OB_APIM>:<HOST>/xs2a/v1/consents/%s"
payment_resource_self_link = "https://<WSO2_OB_APIM>:<HOST>/xs2a/v1/%s/%s/%s"
cof_resource_self_link = "https://<WSO2_OB_APIM>:<HOST>/xs2a/v2/consents/confirmation-of-funds/%s"

owing links represent the templates of the self links for the newly created accounts and payments, and confirmation of funds resources.

14.

[open_banking.berlin]
mandatory_params = <Parameter>

This configuration decides the optional parameters sent in the request.

The ASPSP can decide on the optional parameters they need to mandate. For example, PSU-ID, PSU-ID-Type, PSU-Corporate-ID, PSU-Corporate-ID-Type.

15.

[open_banking.berlin.sca]
auth_cancellation.enable = false

The auth_cancellation_enable property defines whether a PSU authorization is required for payment cancellation.

`True`	Required to authorize the cancellation by completing authorization flow.
`False`	Authorization is not required.

16.

[open_banking]
sharable_accounts_retrieve_endpoint ="http://<WSO2_OB_APIM_HOST>:9443/api/openbanking/backend-berlin/services/v130/accounts/shareable"

payable_accounts_retrieve_endpoint = "http://<WSO2_OB_APIM_HOST>:9443/api/openbanking/backend-berlin/services/v130/accounts/payable"

Configure the endpoint to retrieve sharable and payable accounts that are required to list on the consent page.

The given endpoints connect the solution to the mock back end available in WSO2 Open Banking.

17.

[open_banking.berlin.sca]
update_psu_identification_endpoint = "https://<WSO2_OB_IAM_HOST>:<PORT>"
update_psu_authentication_endpoint = "https://<WSO2_OB_IAM_HOST>:<PORT>"
auth_transaction_endpoint = "https://<WSO2_OB_IAM_HOST>:<PORT>"

Configure the following links for the payment initiation resource:

update_psu_identification_endpoint: needs to be updated by the PSU identification. This might be used in an embedded, redirect or decoupled SCA approach, where the PSU ID was missing in the first request.
update_psu_identification_endpoint: needs to be updated by a PSU password and eventually the PSU identification if not delivered yet. This is used in case of the Embedded or Decoupled SCA approach.
auth_transaction_endpoint: authorises the payment by checking the SCA authentication data within the Embedded SCA approach.

18.

[open_banking.berlin.sca]
auth_object.auth_type = SMS_OTP
auth_object.auth_version = 1.0
auth_object.name = sms-otp
auth_object.explanation = SMS OTP on Mobile
auth_object.default.enable = true

Configure SCA Methods for API responses. Depending on the risk management of the ASPSP this choice might be offered before or after the PSU has been identified with the first relevant factor, or if an access token is transported.

Following are the possible SCA authentication types:

SMS_OTP	An SCA method, where an OTP linked to the transaction to be authorised is sent to the PSU through an SMS channel.
CHIP_OTP	An SCA method, where an OTP is generated by a chip card.
PHOTO_OTP	An SCA method, where the challenge is a QR code or similar encoded visual data which can be read in by a consumer device or specific mobile app.
PUSH_OTP	An OTP is pushed to a dedicated authentication APP and displayed to the PSU.

19.

[open_banking.berlin]
duplicate_check.time_interval_in_minutes = 60

The time interval for duplicate checking of payment consent initiation requests using X-Request-ID.

20.

[open_banking.berlin]
iban_single_acc_retrieval_validation.enable = "false"
iban_acc_retrieval_validation.enable = "true"
acc_ref_type = "iban"

By default, the IBAN validation is enabled for a bulk account retrieval, to enable the validation for single account retrieval use the following configurations:

iban_single_acc_retrieval_validation.enable: Sets this to true, to enable IBAN validation for single account retrieval.
iban_acc_retrieval_validation.enable: Sets this to true, to enable IBAN validation for a bulk retrieval.
acc_ref_type: Sets the reference type of the account use the following configuration:
By default, this is set to iban. The specification supports only iban, bban, and pan reference types.

21.

[open_banking.berlin]
supported_challenge_methods = ["S256"]

Configure and limit the supported code challenge methods:

This is available only as a WUM update and is effective from June 04, 2021 (06-04-2021). For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

By default, the code challenge method in OB IAM is used.
To limit the code challenge methods, add the supported_challenge_methods tag and configure them.
This is an optional configuration.

22.

[open_banking.berlin.freq_per_day]
enable = true
val = 4

The frequency per day property defines the requested maximum frequency for an account access per day using a recurring consent. The maximum value is 4 unless agreed bilaterally between TPP and ASPSP.

23.

[open_banking.bi_server.data_publishing]
enable = false
server_url = "{tcp://<WSO2_OB_BI_HOST>:7612}"

To enable data publishing feature, set the property value to true. So, the WSO2 Open Banking Business Intelligence can capture and summarize data. Replace the <WSO2_OB_BI_HOSTNAME> placeholder with the hostname of Open Banking Business Intelligence server.

24.

[open_banking.bi_server.tra]
enable = false
payment_validation.enable = true
account_validation.enable = true

[open_banking.bi_server.tra.receivers]
account_validation_url = "http://<WSO2_OB_BI_HOST>:8007/TRAAccountValidationApp/TRAValidationStream"
payment_validation_url = "http://<WSO2_OB_BI_HOST>:8007/TRAPaymentValidationApp/TRAValidationStream"

To enable Transaction Risk Analysis, set the enable property to true. Replace the <WSO2_OB_BI_HOST> place holder with the hostname of Open Banking Business Intelligence server. Use the account_validation_url and payment_validation_url properties to enable TRA for Accounts and Payments respectively.

25.

[open_banking.bi_server.fraud_detection]
enable = false

[open_banking.bi_server.fraud_detection.receivers]
fraud_detection_url = "http://<WSO2_OB_BI_HOST>:8007/FraudDetectionApp/FraudDetectionStream"
invalid_submission_url = "http://<WSO2_OB_BI_HOST>:8006/InvalidSubmissionsApp/InvalidSubmissionsStream"

To enable the Fraud Detection feature by setting the enable property to true. Replace the <WSO2_OB_BI_HOST> placeholder with the hostname of WSO2 Open Banking Business Intelligence server. Update URLs for fraud_detection_url and invalid_submission_url.

26.

[open_banking.cert_mgt]
client_auth_header = "x-wso2-mutual-auth-cert"
client_cert_cache_expiry = 3600
cert_revocation_validation.enable = true

If MTLS is terminated before the request reaches the Gateway, retrieve the Data Recipient's certificate from the MTLS session and include as a transport certificate header. Include the value for the transport certificate header under client_auth_header property.

To enable certificate revocation validation for API security, set the cert_revocation_validation.enable property to true.

27.

[open_banking.api_security.global]
username = "$ref{super_admin.username}"
password = "$ref{super_admin.password}"

By default, the Consent Management APIs are secured with basic authentication. To access the Consent Management APIs, use the default user or create a new user using the WSO2 Open Banking Identity and Access Management Console.

Update the credentials under username and password properties.

28.

[open_banking.cert_mgt.cert_revocation_proxy]
enable = false
proxy_host = "PROXY_HOSTNAME"
proxy_port = "8080"

If the TPP certificate revocation validation is failing due to no internet connectivity, update the parameter values under open_banking.cert_mgt.cert_revocation_proxy in the API Manager. Then the certificate revocation of the TPP will happen through a proxy server:

Parameter Description

Enabled

To enable the TPP certificate revocation to happen through a proxy server. Once this parameter is set to true, it is mandatory to set the host and the port of the proxy server.

Possible values: true, false

ProxyHost The hostname of the proxy server that does the TPP certificate revocation.

ProxyPort The Port of the proxy server that does the TPP certificate revocation.

29.

[open_banking.api_security]
mtls_token_binding.enable = false

By default, Mutual Transport Later Security (MTLS) certificate bound access token is disabled. To enable, configure set mtls_token_binding.enable as true.

30.

[apim]
enable_secure_vault = true

To enable the secure vault in the API Manager, add the enable_secure_vault property and set it to true.

This is only available as a WSO2 Update from WSO2 Open Banking API Manager Level 2.0.0.186 and WSO2 Open Banking Identity Server Level 2.0.0.191 onwards. For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

To enable logs:

If you want to add/enable logs, follow the steps given below:

Open the <WSO2_OB_APIM_HOME>/repository/conf/log4j2.properties file.
Add the name and the level of the logger if they are not already available. The sample explains how to add a mtls-validation-handler logger.

Append the new logger to the list of loggers: 

loggers = mtls-validation-handler, AUDIT_LOG, trace-messages, org-apache-coyote,...

Restart the server.

Disabling weak ciphers

A cipher is an algorithm for performing encryption or decryption. When you set the SSL protocol of your server to TLS, the TLS and the default ciphers get enabled without considering the strength of the ciphers. This is a security risk as weak ciphers, also known as EXPORT ciphers, can make your system vulnerable to attacks. To prevent these types of security attacks, it is encouraged to disable the weak ciphers.

Refer to Disabling weak ciphers in the WSO2 Administration Guide and disable weak ciphers.