Signing Service — Relying Party Developer Guide

OAuth 2.0 (grant type authorization code) is the technical foundation of the protocol. It is combined with further OAuth extensions, such as PKCE and OAuth 2.0 Mutual TLS Client Authentication and Certificate Bound Access Tokens, to achieve an appropriate protection level.

The API for creating electronic signatures is provided by a Qualified Trust Service Provider (QTSP). Those remote signatures are based on on-demand, short-term certificates created by the QTSP using data asserted by the IDP. This API is based on ETSI TS 119 432.

Besides signing just signing PDF or text files, you can use this service for other use cases as well:

As always, please refer to your contract for pricing information.

On a technical level, you can decide for each request if you want the user to sign a custom PDF or text document or a default document (QES/QESID vs. QID) and if you want to include additional user claims. You can also mix default documents with custom documents in the same flow.

The following table shows the additional user claims ("identity assurance claims") that are defined and the location where the data will end up in the X.509 signer certificate:

In case of a QES or QESID, you present the user one or more documents (e.g., a contract proposal PDF document) and ask whether the user accepts and wants to sign the document(s) electronically.

In case of QID, you take one of the default documents for the selected QTSP from the service configuration, described below. This default document must not be modified and must be handled like a text document in the following. The AS will show the text of the document to the user and ask the user if they want to sign this text.

Default documents are available in various languages. You can select the language when selecting the default document from the service configuration, as explained later.

You need to calculate the hash(es) of the PDF or text document(s). To this end, you take the raw bytes of the document, hash them using one of the hash algorithms listed in the following, and encode the hash bytes in Base64, as defined in RFC4648, Section 4.

The hash algorithm SHA-256 is supported by all QTSPs, the use of other hash algorithms depends on the QTSP. The following algorithms are defined (based on ETSI TS 119 432):

You need to store the documents, the hashes, and the hash algorithm OIDs for later use, securely bound to the user’s browser session.

At this point, you must show a button to the user (as explained in the base document) to start the signature process.

The next step, just as in other flows, is to send the user through the OP (Bank) selection at the account chooser. Please refer to the base document for details.

As a result from the previous step, you will be provided with the Issuer URL of the chosen Bank. You now need to obtain the service configuration from the Service Configuration service.

To do that, send an HTTP GET request from your backend to the service configuration service URL, attaching the issuer URL in the iss parameter.

For the sandbox, the URL is as follows (here shown with an example issuer): https://api.sandbox.openbanking.verimi.cloud/service-configuration/v1/?iss=https://testidp.sandbox.openbanking.verimi.cloud/issuer/10000001

For production, the URL is the following: https://api.openbanking.verimi.de/service-configuration/v1/?iss={issuer_url}

The API returns an HTTP status code and the service configuration document.

If an error is indicated, a JSON document explaining the error is contained in the response body, e.g.: {"error":"invalid_request","error_description":"The issuer 'https://accounts.inactivetestbank.de' is not active"}

When a service configuration document is returned, it is of the following form:

You need to select one of the QTSPs, store its configuration, and store the OAuth issuer URL obtained from the identity element.

First, you (or your OAuth library) need to retrieve the OAuth Configuration, or Authorization Server Metadata document. This document will tell you about the endpoints that you need to use in the following.

The URL of this document is created as follows:

{oauth_issuer_url}/.well-known/oauth-authorization-server

The pushed authorization request endpoint, authorization endpoint, and token endpoint URLs are used in the following.

The authorization request is sent as a Pushed Authorization Requests to the authorization server. That means that most of the parameters usually sent in the OAuth authorization request are sent in an MTLS-protected POST request to the backend of the authorization server instead.

This ensures that the data contained in the authorization request remains confidential and cannot be altered by the user or an attacker.

The parameters in the pushed authorization request are shown in the following:

In the next step, you need to redirect the user’s browser to the authorization endpoint of the bank, passing the request_uri and client_id parameters.

Screen control is with the OP now which will guide your user through login and consent. The OP requires information about your app in the course of this flow. You therefore have to provide a privacy policy and may provide an optional terms of service document and label upon registration.

After successful authentication, authorization, and consent, the OP will redirect (HTTP status code 302) your user to the {redirect_uri} given in the Authentication Request including the following request parameters:

Errors according to OAuth 2.0 Authorization Error Response and OAuth 2.0 Error Response may occur and must be handled. In case of an error the parameter error will deliver an error code with optional details in the parameter error_description.

The error unable_to_meet_service_requirements is sent in case the user’s data is not sufficient to create the signature.

If your app received a successful authentication response, your backend at {redirect_uri} needs to exchange the authorization code for an access token at the token_endpoint . The token request is a POST request with content type application/x-www-form-urlencoded and the following parameters:

The IDP will respond with a JSON object, i.e., the response will contain the header Content-Type: application/json;charset=UTF-8.

The JSON object has the following attributes (and may have others)

Errors according to OAuth 2.0 Error Response, or OIDC 1.0 Token Error Response may occur and must be handled. In case of an error the returned JSON object will normally contain an error attribute.

The signature request is authenticated using mutual TLS and is a POST request containing a JSON body. The contents of the request follow the definition given in ETSI TS 119 432, as can be seen in the following annotated example:

If an error occurs while processing the request, the QTSP returns an HTTP status code 400 along with error information as specified in ETSI TS 119 432, Section 7.24.2.

Otherwise, the QTSP returns a document as follows:

You can now add the signature data to the signed document and present the signed document to the user.