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, AU, 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 are listed on the consent page and in a detailed consent scenario, to validate the user accounts against the accounts mentioned in the consent.

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

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

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

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

<EnableIBANBasedSingleAccountRetrievalValidation>: Set this to true, to enable IBAN validation for single account retrieval.
<EnableIBANBasedAccountRetrievalValidation>: Set this to true, to enable IBAN validation for a bulk retrieval.

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

15

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

<AccountReferenceType>iban</AccountReferenceType>

16

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:

<!-- Enable frequency per day throttling for eligible API GET calls -->
<EnableFrequencyPerDay>true</EnableFrequencyPerDay>
<FrequencyPerDay>4</FrequencyPerDay>

17

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>

18

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>

19

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>

20

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, use the following configuration, which is placed just above the <TransportCertificateHeader> tag:

<ClientTransportCertAsHeaderEnabled>true</ClientTransportCertAsHeaderEnabled>

21

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>

22

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>

23

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.

24

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

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

Click here to see the parameter descriptions...

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 Port of the proxy server that does the TPP certificate revocation.

25

By default, MTLS token binding is disabled in WSO2 Open Banking. To enable, locate <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml and change the <EnableMTLSTokenBinding> parameter value to true as follows:

<APISecurity>
        <EnableMTLSTokenBinding>true</EnableMTLSTokenBinding>
</APISecurity>

Upon enabling the feature, you need to 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.

26

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 February 11, 2021 (02-11-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.