Relying Party Developer Guide

Welcome to the Developer Guide!

This guide is for you if you want to integrate the identity services into your application or website. We will guide you through the technical steps for visual and back-end integration.

Login with my bank
Sign with my bank
Identify with my bank

1. Before we start

While you can start implementing at any time, please note that you have to register before you can try out your relying party service in our sandbox environment. And before you can go live you will need to go through an identification process which includes an identification of your company and its legal representative. As this might take some time and involve different people in your organization you might want to start that process early.

If you have any questions please do not hesitate to contact your key account manager.

Requirements Notation and Conventions

For the use of Developer Assets, these Terms and Conditions apply.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

2. Flows

Currently, the identity service supports the following three flows:

  • Identity: An OpenID Provider (OP, often a bank) provides you (as a relying party, RP) with identity information about your user.

  • Signing: Your user electronically signs a document with the help of a Qualified Trust-Service Provider (QTSP) and identity information provided by an OpenID Provider.

  • Payment Initiation (Credit Transfer): Enable your user to initiate a SEPA payment.

All flows follow the same pattern:

  • The user starts the process by clicking on a button on your web site.

  • You redirect the user to the Account Chooser where the user selects her bank.

  • The user returns to your site and depending on your use case, you send the user either in the OpenID Connect flow (for identity information) or the OAuth flow (for other services), or even a combined OAuth and OpenID Connect flow, at the selected bank.

  • For signing, you then contact the QTSP to retrieve the signature.

  • For payment initiation, you can optionally retrieve information about the status of the payment.

  • For identity information, you can retrieve (more) information about the user from the Userinfo endpoint.

3. Flows Basics

Handling identity data, payments, and qualified electronic signatures requires requires high security and privacy standards. This means:

  • All connections established with the ecosystem must be protected by TLS version >= 1.2.

  • The identity service relies on the OAuth 2.0 and OpenID Connect Core 1.0 standards with TLS Client Authentication for OAuth. We recommend to use existing OAuth and OpenID Connect libraries for your integration.

  • If your app is a Single Page Application (SPA) or a native App, you need to perform all communication towards backend endpoints of the account chooser or the OAuth/OpenID provider from a backend. This ensures confidentiality of your private key(s) used to authenticate your app using TLS Client authentication with the certificate registered with the identity service.

  • If you use a Web Application Firewall, please take a look at Advanced Use Cases - Web Application Firewalls.

4. Starting Point: the Button

The button must appear in your app where the user confirms to use the identity service (call to action towards the Account Chooser).

4.1. The Button - Style Guide

To integrate the identity service, simply use the same element that you use for other call to actions in your corporate design. The identity service does not define, nor provide dedicated designs for a Button. Form, color and size should match your own buttons.

Everything used for the button depends on your own decision and needs like color, font, size and the html tag. The context in which the user gives the consent always appears above the Button.

Here are some examples:

Login with my bank
Sign with my bank
Save time - Pay with my bank
Ensure that the user knows what to expect when clicking the button.

When creating the button, please keep the following in mind:

  • With the identity service, the user will use her bank to log in at your site, transfer her data, initiate a payment, or to sign a document. The user must expect an interaction with her bank, or she might be surprised by the request to select her bank.

  • Many users might not already know the brand "...". Therefore, a button like "Sign in with ..." that does not mention the banking context is not sufficient.

  • There is no concept of a "... account" since the user uses her existing online banking credentials (... does not see any of the user’s data).

In our experience, there is no need for lengthy explanations, but selecting the correct wording for the context of the button is sufficient. We recommend a wording like the following (see also our example buttons above):

  • Sign with my bank

  • Login with my online banking data

  • Save time - Pay with my bank

  • Sparen Sie Zeit - übernehmen Sie die Daten aus Ihrem Onlinebanking

  • Jetzt mit meiner Bank signieren

  • Mit meiner Bank registrieren

Avoid the following wordings (and similar):

  • Log in with identity service (not mentioning banks/banking/online banking)

  • Log in (no explanation at all)

  • Use your identity service account (there is no identity service account)

  • identity service login (what is identity service?)

4.2. After the Button Click

The button click will start the process, with the bank selection as the first step. This process always takes place in a web browser.

If you are integrating the identity service into a web app, we recommend you to perform the process in the same window as your app. You may also open another top level window (pop up or new tab). For security reasons, you cannot perform the process in an iframe.

If you are integrating the identity service into a native app, we recommend you to use an in-app browser tab, such as a Safari View Controller or Chrome Custom Tabs. A WebView MUST NOT be used. For further recommendations see OAuth 2.0 for Native Apps.

In the following we will assume a web app that performs the process in the same window.

4.3. Avoiding Misleading Error Messages

During the flow, your application might encounter error conditions that it needs to handle. The details of these errors are explained throughout the rest of the document. Some of these are technical errors that are independent of a user’s actions, for example, if an invalid OAuth/OpenID Connect redirect URI is used.

Some of the "errors" however, indicate that the user has chosen to abort the process or to select a different bank. As such, they are part of the normal user experience and should be treated as such: An error message like "An error has occured" when the user selected "cancel" in her online banking is not helpful and may surprise the user, as a cancellation of the process is what was intended and expected. It is better to invite the user to start the process again or to select some other method to complete the transaction.

A "friendly" error message should in particular be shown for the following errors:

  • The canceled error from the account chooser (see here).

  • The access_denied OAuth error (see here).

No error message should be shown for the account_selection_requested error from the OAuth/OIDC flow. The user should be redirected to the account chooser using a special parameter in this case.

5. Bank Selection

This figure shows the steps explained in the following:

account_chooser

5.1. Account Chooser Request

Your back-end code processes the Button Click (e.g., saves state) and ultimately sends an HTTP redirect (HTTP status code 302) to the browser causing a redirect to the Account Chooser. You can also redirect the user by other means, e.g., JavaScript.

In the sandbox environment you will reach the Account Chooser at https://accounts.sandbox.openbanking.verimi.cloud and for the production environment at https://accounts.openbanking.verimi.de.

Example 1. Redirection to Account Chooser via Location Header

If you’re registered for the sandbox and your client_id is sandbox.yes.com:3630BF72-E979-477A-A8FF-8A338F058932, the redirection to the account chooser could look like this: 

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

This request has the following parameters:

  • client_id: the client_id of your app as issued by the identiy service. If the account chooser request contains an invalid client_id, the account chooser will terminate processing and show an error message to the user.

  • prompt: (CONDITIONAL) this parameter is used with value select_account in case the user wants to force selection of another bank irrespectively of an existing bank selection cookie.

The prompt parameter MUST only be used if your app receives an OpenID Connect Authorization Response with error code account_selection_requested
To reset the account chooser cookie for testing and development, go to https://accounts.sandbox.openbanking.verimi.cloud/cookie.

  • state: (OPTIONAL) you may use this parameter to pass a value to the Account Chooser that it will add unaltered to its redirect response. You can use this to identify user sessions if you have your frontend and backend service on different domains so that you do not lose access to session cookies and local storage when the Account Chooser redirect is performed.

Please do NOT use an existing session ID directly but some value derived from or bound to the session. There is no guarantee on the integrity of the state value: It could be modified by an attacker or come from a different session.

  • preselect_bic and return_bic - should only be used in special use cases, see Advanced Use Cases.

5.2. Account Chooser Response

Screen control is with the Account Chooser now. After your user selected her bank, the account chooser will redirect her, using HTTP status code 302, to your Account Chooser Redirect URI. The URL will include the following parameters:

  • issuer_url: the OpenID Connect Issuer URL of the selected OP

  • state: (CONDITIONAL) the state parameter value if you specified it in the request

Example 2. Account Chooser Response

If your RP uses the Account Chooser Redirect URI https://rpbackend.acme.com/yes/accb and your user has selected a bank with the Issuer URI https://testidp.sandbox.openbanking.verimi.cloud/issuer/10000001, the Account Chooser will redirect to this URL:

https://rpbackend.acme.com/yes/accb?issuer_url=https://testidp.sandbox.openbanking.verimi.cloud/issuer/10000001

You will receive the following request from the user’s browser: 

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

Your app needs to retain the issuer URL for further processing.

5.3. Account Chooser Error Response

Some interactions with the customer can result in the cancellation of the account chooser workflow and returning the customer to the relying party. In such a case, the account chooser will redirect to the RP with a url parameter error detailing the specific reason:

{Account Chooser Redirect URI}/?error=<code-see-table>

  • canceled: Pressing the "back" button

  • unknown_issuer: The bank search returned no results or the customer selected a bank that either has no idp (issuer) at all, or the found idp is inactive

Example 3. Account Chooser Error Response

If the user clicked on the back button, you will receive the following request from the user’s browser: 

GET /yes/accb?error=canceled HTTP/1.1
Host: rpbackend.acme.com
OAuth/OpenID Connect Error: Account Selection

Later in the flow, when the user is already in the OAuth/OpenID Connect part, the user might be redirected back to your OAuth/OpenID Connect redirect URI (NOT the account chooser redirect URI) with a specific OAuth error code account_selection_requested.

This means that the user has clicked 'Select another bank' during the online banking login. This shall cause a forced bank selection in the account chooser.

You MUST handle this error code as follows: you MUST redirect the user to the Account Chooser and append the parameter prompt with the value select_account to the request. This is the only case in which this paramter may be used. The account chooser will then ignore a previously selected bank and prompt the user for a new selection.

The following figure shows the flow in this case, using the identity flow and two IDPs (OpenID Provider 1 and OpenID Provider 2).

identity_flow_rp_view_other_idp
Example 4. Authentication Error Response 
GET /yes/oidccb?iss=https://testidp.sandbox.openbanking.verimi.cloud/issuer/10000001&
        error=account_selection_requested&error_description=User_reque
        sted_to_select_another_account&state=V1F4gV3fDx6y110UzQJpk HTTP/1.1
Host: rpbackend.acme.com

5.4. How to Proceed from Here

You now have the issuer URL as the starting point for the rest of the flow. Please refer to the next steps desribed in the context of the individual services: