API Connect

 View Only

eIDAS based PSD2 TPP authentication on API Connect v5

By Carlo Marcoli posted Tue October 02, 2018 11:52 AM



This post covers a single aspect of the implementation of PSD2 Access to Account interfaces and assumes you are familiar with IBM API Connect. For a broader view on how to design an end to end PSD2 solution you can referent to the PSD2 Reference Architecture.

The PSD2 Regulatory Technical Standards (RTS) of the European Banking Authority (EBA) mandate the use of eIDAS certificates for the identification of Third Party Providers (see Ref. 1). The eIDAS specifications recently finalized by ETSI (Ref. 2) and the latest EBA opinions on the RTS (Ref. 3) has introduced a further level of clarity on how Third Parties should be authenticated by a bank.

This post, based on live implementations of open banking solutions running on IBM API Connect, analyses how these processes can be configured in version 5 of the IBM API platform. There is still a considerable level of uncertainty on the evolution of the PSD2 ecosystem and the variations that might be introduced at a national level. However, the approach described here addresses the key technical building blocks of a solution that you can configure to suit your specific requirements.

Two aspects of the emerging ecosystem are particularly relevant in this space:

  • All the major PSD2 API standardization initiatives recommend using eIDAS transport certificates (QWAC) for TPP authentication

  • The EBA standards and opinions indicate that a bank should have no barrier to the adoption of its APIs, including unnecessary manual steps.

The PSD2 eIDAS certificates, as defined by the ETSI standards, identify only a TPP organization and not a TPP developer, or an individual TPP application. As a result they can support only a coarse grained API access management approach, unless they are combined with other industry frameworks providing additional identity services for developers and applications.

Although there are services, including the the UK Open Banking Directory, that enable these additional capabilities, this post presents a generic approach built only on the core trust framework enabled by the eIDAS certificates. The implementation of a bank can then extend this approach to leverage the additional constructs of IBM API Connect in the context of the ecosystem services that might become prevalent in its region.

Points 1) and 2) mentioned  above drive the implementation of two technical requirements:

  • Dynamic client on-boarding, based on the identity carried by eIDAS certificates

  • API client authentication based on mutual TLS

Dynamic client on-boarding

A third party will trigger the on-boarding process by calling an API endpoint secured through mutual TLS (step 1 in Figure 1).

In this example we are assuming the API gateway of API Connect acts as the point of TLS termination. However the same approach can be implemented performing TLS termination at an upstream load balancer and forwarding the eIDAS certificate information in the “X-Client-Certificate” header.

After having validated the TPP certificate, as shown in step 2, the gateway can access the PSD2 eIDAS extensions defined in Reference [2]. Indeed the certificate extensions are directly available as a context variable in the API assembly diagram. The eIDAS extensions include the field “organizationIdentifier”, a unique reference to a TPP organization across the PSD2 ecosystem.

In step 4 of Figure 1 you use that information to verify the status of the TPP against a TPP Directory. The details of this interaction depends on the directory services you are using. For example if you connect to the PRETA Directory (Ref [5]) you will leverage an application component maintaining a copy of the data exported from that service with a bulk upload.

Figure 1 – Dynamic client on-boarding

When a TPP has been successfully authenticated through certificate validation and authorized against the data maintained in the TPP directory you proceed to onboard them in API Connect.

From an API Connect configuration point of view, every TPP is mapped to an instance of a “Developer Organization”. In step 5 and 6 you check if the TPP organization already exists. If it doesn’t, you create one (step 7) and associate it to the eIDAS certificate received through the TLS connection (see step 8).

Note that these entities are created under a master organization owned by the bank. You see that represented as  “TPP Domain” in Figure 2. You use an administration identity from this “TPP” domain to dynamically create an organization for every TPP.

Figure 2 – API Connect developer organizations setup

You can automate all the steps described in Figure 1 leveraging the developer portal APIs. You find their detailed documentation at reference [8] and [9]. The APIs provides a flexible interface to create and configure an API client. You can adjust their inputs depending on your needs.

In this case we are setting both the API Connect developer organization and the client id to the unique identifier carried by the eIDAS certificate. Alternatively, you could decouple those values and return a generated client_id to the TPP. We have privileged the first option because it frees the TPP from the burden of maintaining additional keys for every single bank it connects to.

You might note we are also assuming that every organization has a single “Application” linked to an eIDAS certificate. This is not a limitation of a platform, but a constraint related to the information carried in an eIDAS certificate, as explained in the introduction.

OAuth2.0 client authentication based on mutual TLS

The TPP can now call the Access to Account interfaces of the bank, using eIDAS certificate as authentication mechanism.

IBM API Connect v5 supports, out of the box, application authentication based on digital certificates, including eIDAS certificates. However if you use OAuth2.0 for authorizing access on the basis of customer consent,  you need to link the generation of security tokens to the API client identity carried by the certificate.

At the time of writing the IETF standards covering this OAuth2.0 aspect are still in evolution, however at Reference [6] you can find a description of how to configure API Connect  in line with the most recent draft of the specification (Reference [7]). That post (Ref [6]) describes in details how to identify OAuth2.0 clients using mutual TLS authentication and then generate access tokens bound to the client certificates.


This post, read in conjunction with the one mentioned at Reference [6], explains the technical aspects of TPP on-boarding and authentication based on the EBA Regulatory Technical Standards and opinions for PSD2. The technical ecosystem of PSD2 is still in evolution, however the material presented here shows how banks can configure IBM API Connect version 5 to support the latest requirements.


[1] EBA RTS on Strong Customer Authentication and Secure Communication

[2] ETSI eIDAS certificates for PSD2

[3] EBA option on the implementation of SCA and SC

[4] UK Open Banking Directory

[5] PRETA Directory

[6] OAuth 2.0 Mutual TLS and Certificate Bound Access Tokens in IBM API Connect v5

[7] Draft IETF OAuth MTLS

[8] Using the Developer Portal REST APIs

[9] Developer Portal API reference




Tue October 23, 2018 12:49 PM


Mon October 22, 2018 08:03 PM

Thanks Carlo. So in this case, your proposal is to create for example an API with an endpoint like /enroll (for example) so the TPP will only interact with that API the first time it needs to subscribe to the API. The invocation of this API will create in the API Manager (as described in figure 1) all the stuff (developer org, application, arrange the subscriptions) and after that, the TPP will be able to interact with the XS2A APIs. Is that correct?

Mon October 22, 2018 03:11 PM

Hi Jose,
Correct, the TPP on-boarding needs to be managed through an APIs, as mentioned at the very beginning of the "Dynamic on-boarding" section. Note that the endpoint exposed by the API Gateway, as shown in Figure 1, is not invoked for every call to XS2A apis. It is a individual step that the TPP performs once to subscribe to the APIs of the bank. This enables the bank to monitor the activity of the TPP. The flow of that diagram can be implemented in the APIConnect assembly diagram, using the gateway script primitive. Note that in your end to end implementation you will also check the status of the TPP authorization for every call to XS2A endpoints, however that's outside the scope of this post that focuses on the initial TPP onboarding.

Sun October 21, 2018 05:19 PM

Great article. I need some clarifications. First, if we enable in an API the field "Lifecycle > Authenticate Application" it is true that the gateway will act as a TLS termination and the application certificate context variables (application.certificate.Base64, application.certificate.Subject, etc) will be readable, but we need to specify in the Developer Portal the known X509 files (if not, we will be getting errors such as "Application is not using mutual TLS") so we will be unable to auto-enroll organizations. Second, I need some additional info about "Figure 1 – Dynamic client on-boarding": how do you recommend to implement that logic? For example as a Datapower Extension? Or as a user-defined policy that will be executed in the assembly on every call to /accounts /funds-confirmations /payments? Thank you

Mon October 08, 2018 01:00 PM

IBM API Connect, as a platform, is industry agnostic and supports a large number of API economy use cases. For this reason the content of the trust store is not controlled by IBM, but by the API provider organization (the ASPSP in the PSD2 context).

Sun October 07, 2018 08:45 PM

very good article.
Could you please elaborate on "IBM API Connect v5 supports, out of the box, application authentication based on digital certificates, including eIDAS certificates", QWAC certificate are released by QTSP and QTSP are authorized frequently in this new ecosystem. Are all QTSP certificate loaded into API Connect trust store? How APIC manages updates of QTSP certificates ?
Is this applicable for IBM Cloud or just OnPremises deployment?

thank you