Advanced Use Cases — Relying Party Developer Guide

1. Web Application Firewalls

The protocol flow is dynamic in many places. Some web application firewalls (WAFs) need special configurations for this protocol flow. In particular, the following features can create challenges for WAFs:

During the discovery process, your application needs to retrieve information from non-hardcoded URLs. More precisely, your application will first retrieve the so-called issuer URL from the platform. Typically, this URL will point to a domain of the bank or banking group the user selected in the account chooser. Your application will append the path /.well-known/openid-configuration to this URL and retrieve the IDP’s configuration from there. Some firewalls block requests from your application to arbitrary URLs to protect against server-side request forgery (SSRF) attacks. SSRF attacks are not an issue in this setup, though, as the URLs come from a trusted party, namely the platform, and do not contain dynamic parts. An additional protection by the firewall, at least for this part of your application, is therefore not necessary. If the firewall cannot be set up to trust the application for SSRF protection, setting up an external proxy not affected by the firewall may be an option.
Your application will determine the URL of the authorization server from the discovery process described above. The user needs to be redirected to this URL to give the authorization. Some WAFs block redirections to arbitrary URLs to protect against open redirectors. Open redirectors occur when a web application redirects to arbitrary URLs acquired from a URL parameter or other untrusted input. In the setup, authorization URLs come from trusted partners and do not contain dynamic parameters. Thus, if your application follows the protocol, there is no open redirector that can be exploited. It is therefore advised to set up your WAF to allow redirections from this part of your application. Alternatively, you can perform the redirection in the web browser using JavaScript or a meta-refresh redirect. These are typically not covered by the WAF redirection protection.

In both cases, whitelisting the endpoints in the WAF might be another solution. Please note, however, that

you MUST NOT use a static list of endpoints for the WAF, since the endpoints can change at any time and without further notice; and
even if some banks or banking groups use predictable URLs (like as.bankinggroup-somecity.de), you MUST NOT use pattern-matching for whitelisting (e.g., whitelist as.bankinggroup-*.de) as exceptions to these patterns exist and endpoints or banks can be added or changed at any time and without further notice.

An automated approach that extracts the endpoint URLs from the platform and updates the WAF rules at least every 24 hours is therefore the only solution for whitelisting. If you are interested in pursuing this option, please contact the identity service for advice on how to extract the respective endpoints.

2. Combined Flows

Different services can be combined in the same flow, in particular the signing and payment initiation services. In this case, a sign and a payment_initiation object need to be provided in the authorization_details in the pushed authorization request.

Combined flows must always use Pushed Authorization Requests as described in the PIS and Signature flows.

Example 1. authorization_details for combined flow

[
   {
      "type": "sign",
      "locations": [
         "sp:yes.com:6a256bca-1e0b-4b0c-84fe-c9f78e0cb4a3"
      ],
      "credentialID": "qes_eidas",
      "documentDigests": [
         {
            "hash": "sTOgwOm+474gFj0q0x1iSNspKqbcse4IeiqlDg/HWuI=",
            "label": "Kreditvertrag"
         },
         {
            "hash": "HZQzZmMAIWekfGH0/ZKW1nsdt0xg3H6bZYztgsMTLw0=",
            "label": "Vertrag Restschuldversicherung"
         }
      ],
      "hashAlgorithmOID": "2.16.840.1.101.3.4.2.1"
   },
   {
      "type": "payment_initiation",
      "paymentProduct": "sepa-credit-transfers",
      "instructedAmount": {
         "currency": "EUR",
         "amount": "123.50"
      },
      "creditorName": "Merchant123",
      "creditorAccount": {
         "iban": "DE02100100109307118603"
      },
      "remittanceInformationUnstructured": "Ref Number Merchant"
   }
]

The user’s consent will be requested both for the signature and the payment.

Other parts of the respective flows work as described in the respective sections of this developer guide. The access token created can be used both for retrieving the payment status as well as the signature process.

3. Account Chooser Features

The account chooser can be called with special parameters for advanced use cases.

Besides client_id, prompt, and state described here, the following parameters can be used:

3.1. Selecting a Bank on the User’s Behalf

Parameter: preselect_bic

This parameter can be used to select a bank based on a provided BIC on the user’s behalf. You can use this when you know the user’s bank from a different source, but in general, normal usage of the account chooser is recommended.

Any previously selected bank of the user will be overridden and the new bank (if any) will be saved as the user’s choice. The account chooser response will be returned immediately, and the account chooser UI is not displayed. MUST NOT be used together with prompt=select_account. If there is no bank with the provided BIC, the account chooser will redirect back to your account chooser redirect URI with the parameter error=invalid_request and a description of the error in the parameter error_description.

Example 2. Redirection to Account Chooser with preselect_bic

HTTP/1.1 302 Found
Location: https://accounts.sandbox.openbanking.verimi.cloud/?client_id=sandbox.yes.com:
          3630BF72-E979-477A-A8FF-8A338F058932&preselect_bic=TESTDEY0001

The user can still click on "select another bank" in the bank’s web interface. You must handle this condition as described here.

3.2. Returning the Bank’s BIC

Parameter: return_bic

Set this to true to request that the BIC of the user’s selected bank is returned in parameter called selected_bic in the account chooser response.

Example 3. Redirection to Account Chooser with return_bic

HTTP/1.1 302 Found
Location: https://accounts.sandbox.openbanking.verimi.cloud/?client_id=sandbox.yes.com:
          3630BF72-E979-477A-A8FF-8A338F058932&return_bic=true

Example 4. Account Chooser Response with Selected BIC

GET /yes/accb?issuer_url=https://testidp.sandbox.openbanking.verimi.cloud/issuer/10000001
    &selected_bic=TESTDEY0001 HTTP/1.1
Host: rpbackend.acme.com