Configuring the Open-Banking.xml File for Berlin

Configure open-banking.xml files in both WSO2 Open Banking Key Manager(WSO2_OB_KM) and WSO2 Open Banking API Manager(WSO2_OB_APIM) nodes based on the configurations listed below.

The open-banking.xml files are in below locations:

<WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml
<WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml

Do the following configurations in both the Key Manager and API Manager nodes and restart the servers.

Configuration

1

Define the specification that you plan to deploy.

Possible values: UK, BERLIN, STET

<DeployedSpecification>BERLIN</DeployedSpecification>

2

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

<SCA>
<SelectedSCAApproach>REDIRECT</SelectedSCAApproach>
</SCA>

3

The endpoint to retrieve OIDC Discovery metadata.

<SCA>
	<OAuthMetadataEndpoint>https://<WSO2_OB_APIM_HOST>:8243/.well-known/openid-configuration</OAuthMetadataEndpoint>
</SCA>

4

Following links represent the templates of the self links for the newly created accounts and payments resources.

<AccountConsentSelfLink>https://<WSO2_OB_APIM_HOST>:8243/xs2a/1.3.3/consents/%s</AccountConsentSelfLink>
<PaymentResourceSelfLink>https://<WSO2_OB_APIM_HOST>:8243/xs2a/1.3.3/%s/%s/%s</PaymentResourceSelfLink>

5

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

<Berlin>
	<MandatoryParameters>
		<!--<Parameter>PSU-ID</Parameter>-->
		<!--<Parameter>PSU-ID-Type</Parameter>-->
	</MandatoryParameters>
</Berlin>

6

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

<Berlin>
<AuthorizeCancellation>false</AuthorizeCancellation>
</Berlin>

7

Sharable accounts - accounts that are accessible online.

<SharableAccountsRetrieveEndpoint>: Configures the endpoint to retrieve sharable accounts that required to list on the consent page.

<SharableAccountsRetrieveEndpoint>http://<WSO2_OB_APIM_HOST>:9763/open-banking/services/bankaccounts/bankaccountservice/sharable-accounts</SharableAccountsRetrieveEndpoint>

Payable accounts - accounts from which a PSU can make a payment.

<PayableAccountsRetrieveEndpoint>: Configures the endpoint to retrieve payable accounts that required to list on the consent page.

<PayableAccountsRetrieveEndpoint>http://<WSO2_OB_APIM_HOST>:9763/open-banking/services/bankaccounts/bankaccountservice/payable-accounts</PayableAccountsRetrieveEndpoint>

In some banks, some PSUs may have a certain number of accounts, but not all accounts have the ability to be shared externally or to make a payment online. In a bank, the sharable account list and the payable account list can either be the same or different.

In the default WSO2 Open Banking solution, at least two APIs are expected to return sharable and payable accounts when passing the user_id, and the given JSON response must be returned. Then it automatically loads the accounts list in the consent page.

The bank's backend endpoint for retrieving the user's accounts returns a response in the following format:

Account:
    type: object
    properties:
      iban:
        type: string
        example: DE12345678901234567890
        description: IBAN of account
  GetAccountsResponse:
    type: object
    properties:
      customerNumber:
        type: string
      accounts:
        type: array
        items:
          $ref: '#/definitions/Account'
    description: The response related to the get method of Account

By default, mock backend deployed in WSO2_OB_APIM is configured. Required parameters can be passed as query parameters to those endpoints. An example of configuring the endpoint to retrieve payable accounts:

https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/v130/accounts/shareable

An example of configuring the endpoint to retrieve payable accounts:

https://<WSO2_OB_APIM_HOST>:9443/open-banking-berlin/services/v130/accounts/payable

8

The link to the payment initiation resource, which 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.

<SCA>
<UpdatePSUIdentification>https://<WSO2_OB_KM_HOST>:9446</UpdatePSUIdentification>
</SCA>

9

The link to the payment initiation resource, which 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.

<SCA>
<UpdatePSUAuthentication>https://<WSO2_OB_KM_HOST>:9446</UpdatePSUAuthentication>
</SCA>

10

This is a link to a resource, where the TPP can select the applicable strong customer authentication methods for the PSU if there were several available authentication methods.

<SCA>
<SelectAuthenticationMethod>https://<WSO2_OB_KM_HOST>:9446</SelectAuthenticationMethod>
</SCA>

11

The link to the payment initiation resource, where the "Payment Authorisation Request" is sent to. This is the link to the resource which will authorise the payment by checking the SCA authentication data within the Embedded SCA approach.

<SCA>
<AuthorizeTransaction>https://<WSO2_OB_KM_HOST>:9446</AuthorizeTransaction>
</SCA>

12

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.

<Berlin>
	<SCA>
		<SCAMethods>
			<AuthenticationObject>
				<AuthenticationType>SMS_OTP</AuthenticationType>
				<AuthenticationVersion>1.0</AuthenticationVersion>
				<AuthenticationMethodId>sms-otp</AuthenticationMethodId>
				<Name>SMS OTP on Mobile</Name>
				<Explanation>SMS based one time password</Explanation>
				<Default>true</Default>
			</AuthenticationObject>
		</SCAMethods>
	</SCA>
</Berlin>

13

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

<DuplicateCheck>
            <TimeIntervalInMinutes>60</TimeIntervalInMinutes>
</DuplicateCheck>

14

Enable IBAN validation for single accounts by adding the <EnableIBANBasedSingleAccountRetrievalValidation> configuration as follows. By default, the IBAN validation is enabled for bulk accounts through the <EnableIBANBasedAccountRetrievalValidation> configuration.

<EnableIBANBasedSingleAccountRetrievalValidation>true</EnableIBANBasedSingleAccountRetrievalValidation>
<EnableIBANBasedAccountRetrievalValidation>true</EnableIBANBasedAccountRetrievalValidation>

15

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

<FrequencyPerDay>4</FrequencyPerDay

16

This is for the Data Reporting feature, to enable data publishing set the <Enabled> 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.

<DataPublishing>
	<!-- Include all configurations related to Data publishing -->
	<!-- Enable data publishing in WSO2 Open Banking-->
	<Enabled>true</Enabled>
	<!-- Server URL of the remote BI server used to collect statistics. Must
            be specified in protocol://hostname:port/ format. -->
	<ServerURL>{tcp://<WSO2_OB_BI_HOST>:7612}</ServerURL>
	<!-- Administrator username to login to the BI server for data publishing. -->
	<Username>admin@wso2.com@carbon.super</Username>
	<!-- Administrator password to login to the BI server for data publishing. -->
	<Password>wso2123</Password>
</DataPublishing>

17

To enable Transaction Risk Analysis, set the <IsEnabled> property under <TRA> to true. Replace the <WSO2_OB_BI_HOST> place holder with the hostname of Open Banking Business Intelligence server.

Use the <AccountValidationEnabled> and <PaymentValidationEnabled> properties to enable TRA for Accounts and Payments respectively.

<TRA>
	<!-- Include all configurations related to Transaction Risk Analysis -->
	<!-- Enable TRA in WSO2 Open Banking-->
	<IsEnabled>true</IsEnabled>
	<!-- following configurations are used to enable TRA for specific flows only-->
	<!-- Enable TRA for Payments-->
	<PaymentValidationEnabled>true</PaymentValidationEnabled>
	<!-- Enable TRA for Accounts-->
	<AccountValidationEnabled>true</AccountValidationEnabled>
	<!-- Configurations related to TRA Receivers-->
	<Receivers>
		<!-- Administrator username to login to the remote BI server. -->
		<Username>admin@wso2.com@carbon.super</Username>
		<!-- Administrator password to login to the remote BI server. -->
		<Password>wso2123</Password>
		<!-- Receiver URLs of the Siddhi Apps used to validate for TRA.-->
		<TRAAccountValidationURL>http://<WSO2_OB_BI_HOST>:8007/TRAAccountValidationApp/TRAValidationStream</TRAAccountValidationURL>
		<TRAPaymentValidationURL>http://<WSO2_OB_BI_HOST>:8007/TRAPaymentValidationApp/TRAValidationStream</TRAPaymentValidationURL>
	</Receivers>
	<TimePeriodOfRecurringPayment>90</TimePeriodOfRecurringPayment>
	<MaxFrequencyOfTransactionsWithoutSCA>5</MaxFrequencyOfTransactionsWithoutSCA>
	<TotalAmountLimitOfTransactionsWithoutSCA>100</TotalAmountLimitOfTransactionsWithoutSCA>
	<LastSCATimeLimit>90</LastSCATimeLimit>
	<TransactionAmountLimit>30</TransactionAmountLimit>
    <!-- Number of maximum days of transaction history that can be accessed with the first-time consent use for Berlin.-->
    <FirstAccessHistoryLimit>90</FirstAccessHistoryLimit>
</TRA>

18

You can enable the Fraud Detection feature by setting the <IsEnabled> value to true. Replace the <WSO2_OB_BI_HOST> placeholder with the hostname of Open BankingBusiness Intelligence server.

<FraudDetection>
	<!-- Include all configurations related to Fraud Detection -->
	<!-- Enable FD in WSO2 Open Banking-->
	<IsEnabled>true</IsEnabled>
	<!-- Configurations related to FD Receivers-->
	<Receivers>
		<!-- Administrator username to login to the remote BI server. -->
		<Username>admin@wso2.com@carbon.super</Username>
		<!-- Administrator password to login to the remote BI server. -->
		<Password>wso2123</Password>
		<!-- Receiver URLs of the Siddhi Apps used to validate for FD.-->
		<FraudDetectionURL>http://<WSO2_OB_BI_HOST>:8007/FraudDetectionApp/FraudDetectionStream</FraudDetectionURL>
		<InvalidSubmissionURL>http://<WSO2_OB_BI_HOST>:8006/InvalidSubmissionsApp/InvalidSubmissionsStream</InvalidSubmissionURL>
	</Receivers>
</FraudDetection>

19

If Mutual Transport Layer Security (MTLS) is terminated before the request reaches the Gateway, retrieve the TPP's certificate from the MTLS session and include as a transport certificate header. By default, the gateway expects ssl.client.auth.cert.X509 as the transport header. Include the value for the transport certificate header in TransportCertificateHeader under CertificateManagement element. See the sample configuration below.

 <CertificateManagement>
        <!-- In order to enable the client certificate validation feature (Certificate Expiry, Signature and
        Revocation validation during MTLS), the following module needs to be engaged under the "Global Engaged
        Modules" section in the axis2.xml file.

        <module ref="mtlscertvalidator"/>
        -->

        <!--Set the value of the transport certificate header sent in the request if MTLS is terminated before the
        gateway default value is ssl.client.auth.cert.X509-->
        <TransportCertificateHeader>ssl.client.auth.cert.X509</TransportCertificateHeader>
</CertificateManagement>

The load balancer should not allow the TPP to send its certificate as a transport certificate header that is configured in the open-banking.xml under <TransportCertificateHeader> element.

If such header was found in the TPP’s request, it is mandatory to remove that header from the TPP’s request. This is applicable even when the MTLS session is not terminated at the load balancer.

When TLS is terminated before reaching the Gateway, to send the client certificate as a transport header, add the following configuration just above the <TransportCertificateHeader> tag:

<ClientTransportCertAsHeaderEnabled>true</ClientTransportCertAsHeaderEnabled>

20

In order to enable certificate revocation validation for API security, make sure that the following configurations are added under the server root element. For more information, see certificate revocation validation.

<CertificateManagement>
	<!-- Expiry time for the cache (in seconds) for storing the validation result of the certificates-->
	<ClientCertificateCacheExpiry>3600</ClientCertificateCacheExpiry>
	
	<!-- Enable/Disable certificate OCSP and CRL validation. Default value has been set to true -->
	<CertificateRevocationValidationEnabled>true</CertificateRevocationValidationEnabled>
</CertificateManagement>

21

This feature is available as a WUM update from September 3, 2019 (09-03-2019) onwards.

To extend the certificate revocation validation by adding alternative approaches, configure the CertificateManagement configurations as follows:

<CertificateManagement>
	<ClientTransportCertAsHeaderEnabled>true</ClientTransportCertAsHeaderEnabled>
	<!-- Validate the issuer of the certificate when the client cert is received as a transport header -->
	<TransportCertIssuerValidationEnabled>true</TransportCertIssuerValidationEnabled>
	<!--Manager class implementation responsible for verifying certificate revocation status-->
	<RevocationValidationManagerImplClass>com.wso2.finance.open.banking.mtlscert.validator.service.CertRevocationValidationManagerImpl</RevocationValidationManagerImplClass>
	<!-- Retry count for validating certificate OCSP and CRL revocation status -->
	<CertificateRevocationValidationRetryCount>3</CertificateRevocationValidationRetryCount>
	<!-- List of issuer DNs whose issued certificates needs to be skipped from certificate revocation
    validation.
    e.g. <IssuerDN>CN=Test Pre-Production Issuing CA, O=Test, C=GB</IssuerDN>
    -->
	<RevocationValidationExcludedIssuers>
		<IssuerDN></IssuerDN>
	</RevocationValidationExcludedIssuers>
	<!--Truststore dynamic loading interval (in seconds). Default value has been set to 86400 seconds-->
	<TrustStoreDynamicLoadingInterval>86400</TrustStoreDynamicLoadingInterval>
</CertificateManagement>

22

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 Key Manager Management Console.

Open the <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml file.
Update the credentials under <APISecurity><Global> with the created user details.
By default, this is set to the username and password of the super admin.
```
<APISecurity>
	<Global>
		<Username>admin@wso2.com</Username>
		<Password>wso2123</Password>
	</Global>
</APISecurity>
```

See configuring basic authentication for Consent Management APIs for more information.

23

If the TPP certificate revocation validation is failing due to no internet connectivity, update the parameter values under <CertificateRevocationProxy> in <WSO2-OB-APIM-HOME>/repository/conf/finance/open-banking.xml, so that TPP certificate revocation will be done via a proxy server.

<CertificateRevocationProxy>
            <Enabled>false</Enabled>
            <ProxyHost>PROXY_HOSTNAME</ProxyHost>
            <ProxyPort>8080</ProxyPort>
</CertificateRevocationProxy>

Click here to see the parameter descriptions...

Parameter	Description	Possible Values
Enabled	Enabling the TPP certificate revocation to be done via a proxy server. Once this parameter is set to true, it is mandated for you to update the below two parameters	true, false
ProxyHost	Hostname of the proxy server that does the TPP certificate revocation.
ProxyPort	Port of the proxy server that does the TPP certificate revocation.

24

Configure the client certificate header name in the <ClientAuthenticationHeader> parameter under <CertificateManagement>:

<CertificateManagement>
         <!--Mutual TLS Authenticator Certificate header-->
      <ClientAuthenticationHeader>x-wso2-mutual-auth-cert</ClientAuthenticationHeader>
 </CertificateManagement>

In addition to the above steps, follow the instructions described under MTLS bound access token .

25

To enforce regulatory certificates for API invocations, add the following configuration under the <CertificateManagement> tag:

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

<EnforceRegulatoryCertificates>true</EnforceRegulatoryCertificates>

Once you add the configuration, you can add the eIDAS certificates to the client trust stores.