Version Control

Overview

This specification defines the APIs for a TPP to submit a Software Statement Assertion to an ASPSP for the purpose of creating OAuth clients that are registered with ASPSP. 

The document goes on to identify a set of situations when a TPP may need to modify the client. The ASPSPs may implement optional APIs defined here to achieve that behaviour or implement a service management capability to deal with these changes.

The API supercedes the Open Banking OpenID Connect (OIDC) Dynamic Client Registration Profile. 

This follows on from recommendations made in /wiki/spaces/WOR/pages/619643199:

6.3.4 Dynamic Client Registration

It is the opinion of the OBIE that ASPSPs will need to ensure that TPPs can be registered in a seamless, ideally fully automated basis with registrations processed and TPP responses provided in real-time to avoid the perception / imposition of obstacles. Capability is already provided by the OBIE to support this via the Participant Identification API.

6.4.2 Re-registration at ASPSPs

As a result of impact 6.3.1 or 6.3.2, TPPs may be required to re-onboard with ASPSPs that upgrade their Authorisation server capabilities. OBIE suggests that future delivery phases determine the materiality of this issue and the feasibility of ASPSPs parallel running solutions to enable a smooth migration. It is the expectation of IESG TPP representatives that steps be taken to avoid re-registration requirements.

Document Structure

This document consists of the following parts:

Overview: Provides an overview of the scope of the API and the key decisions and principles that contributed to the specification.

Basics: Identifies the resources, operations that are permitted on those resources, and various special cases.

Endpoints: Provides the list of endpoints for the API specification.

Authentication: Specifies the means for TPPs to authenticate themselves prior to calling the APIs

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Usage Examples: Examples for how the APIs can be used

Basics

Problem Space

The Open Banking Read/Write API standard relies on FAPI-RW as a means for authenticating PSUs and TPPs. To enable this capability a TPP must register one or more clients with the ASPSP.

The Dynamic Client Registration APIs allow this to be carried out in a manner that offers very low friction and removes hurdles and barriers to entry for the TPP to interact with the ASPSP.

The specification is designed to offer a high degree of flexibility of implementation.

Underlying Specifications

The Open Banking Dynamic Client Management specification builds upon the capabilities and concepts introduced by the following standards:

RFC 7591: OAuth 2.0 Dynamic Client Registration

RFC 7592: OAuth 2.0 Dynamic Client Registration Management Protocol

OpenID Connect Dynamic Client Registration 1.0 incorporating errata set 1 

Software Statement

RFC 7591 defines a Software Statement as

Software Statement
      A digitally signed or MACed JSON Web Token (JWT) [RFC7519] that
      asserts metadata values about the client software.  In some cases,
      a software statement will be issued directly by the client
      developer.  In other cases, a software statement will be issued by
      a third-party organization for use by the client developer.  In
      both cases, the trust relationship the authorization server has
      with the issuer of the software statement is intended to be used
      as an input to the evaluation of whether the registration request
      is accepted.  A software statement can be presented to an
      authorization server as part of a client registration request.

In our context, a Software Statement may be issued by any actor that is trusted by the authorisation server. This may include, but is not limited to:

• The TPP itself
• The Directory solution provided by OBIE
• Another Directory service provider

A software statement that is signed by its issuer is referred to as a Software Statement Assertion (SSA). An SSA is represented as a JSON Web Signature (JWS) [RFC7515].

This specification does not dwell upon the parties that should be trusted by an ASPSP.

An ASPSP must specify on its Developer Portal the parties that it trusts and accepts SSAs from.

This specification does not include the claims that should form a part of the software statement or the steps the ASPSP must carry out in processing those claims.

These details should be provided by the software statement issuer and may differ from one issuer to another.

Self-signed SSA

An ASPSP may opt to accept SSAs that are issued directly by a TPP without a central issuer.

In such situations, the ASPSP may accept SSAs that are not signed (indicated by a JOSE claim of alg set to none)

Where ASPSPs accept self-signed SSAs, they must specify this on their Developer Portal along with the claims that it expects to be included in the SSA.

Discovery

The URL of the registration end-point should be advertised on the ASPSP's OIDC Discovery Endpoint using the registration_endpoint claim as defined in https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata.

Of JWS & JWKS

The request payload for a Dynamic Client Registration call and the software statement included in the call is structured as a JWS.

In order to verify the contents of the request and the SSA the ecosystem has to rely on a set of JSON Web Key Stores (JWKS) that store the public part of key used to sign the JWT.

The structure and URL of the JWKS must be agreed between the SSA issuer and its consumers (TPPs and ASPSPs).

The mechanism for determining the key that is used is not part of this specification but is subject to the following limitations:

• The public key must not be embedded in the payload itself (e.g. by using x5c claim in the JOSE header)
• The URL for the JWKS must not be embedded in the payload itself (e.g. by using x5u claim in the JOSE header)
• The JWKS must be secured over TLS using TLS 1.2 and the FAPI approved set of ciphers as defined in https://openid.net/specs/openid-financial-api-part-2.html#tls-considerations.

Endpoints

This section provides a list of available API endpoints for Dynamic Client Registration. 

The ASPSP may have a different URL for the endpoints as long as it is advertised appropriately in the ASPSP's Discovery endpoint.

The ASPSP must have the same URL for all the HTTP operations on that endpoint.

POST /register

POST /register

The API allows the TPP to request the ASPSP to register (create) a new client.

The TPP submits a JWS payload that describes the characteristics of the client to be created. 

If client creation is successful, the ASPSP responds with a JSON payload that describes the client that was created.

The TPP can then use the client to access resources on the ASPSP's resource server.

If client creation is unsuccessful, the ASPSP responds with an error payload.

GET /register/{ClientId}

GET /register/{ClientId}

The API allows the TPP to retrieve the details for a client that has already been registered.

This API is wholly optional for an ASPSP to implement.

The ASPSP may provide a service desk function for a TPP to request their client details. This is optional for an ASPSP to provide.

The request consists of one path parameter - the ClientId - that the TPP wants to retrieve details for.

If the request is successful and the identifier matches the client to whom the Client Credentials grant access token was issued, the ASPSP must return an object of type OBClientRegistrationRequest1.

If the ClientId is unknown, the ASPSP responds with an Unauthorized status code and immediately revokes the access token.

PUT /register/{ClientId}

PUT /register/{ClientId}

The API allows the TPP to request the ASPSP to modify one or more attributes related to an existing client.

This API is wholly optional for an ASPSP to implement.

The ASPSP may provide a service desk function for a TPP to modify their client details. This is optional for an ASPSP to provide.

The TPP submits the ClientId path parameter and a JWS payload that describes the characteristics of the client to be modified. This must include all the claims - including ones that will not be modified.

The ASPSP may reject the request if it does not support changes to certain claims.

The ASPSP must not invalidate long lived access tokens that are issued to the client.

If client modification is successful, the ASPSP responds with a JSON payload that describes the client that was created.

If the ClientId is unknown, the ASPSP responds with an Unauthorized status code and immediately revokes the access token.

If client modification is unsuccessful, the ASPSP responds with an error payload.

DELETE /register/{ClientId}

DELETE /register/{ClientId}

The API allows the TPP to request the ASPSP to delete an existing client.

This API is wholly optional for an ASPSP to implement.

The ASPSP may provide a service desk function to cater to this functionality. This is optional for an ASPSP to provide.

The request consists of one path parameter - the ClientId - that the TPP wants to delete.

If the request is successful and the client Id matches the client to whom the client-credentials grant access token was issued, the ASPSP must delete the client and invalidate long lived access tokens that were issued to the client.

If the ClientId is unknown, the ASPSP responds with an Unauthorized status code and immediately revokes the access token.

Authentication

POST Operations

These APIs rely on TLS Mutual Authentication for authenticating the TPP.

GET, PUT and DELETE operations

TPPs must authenticate themselves with a client credentials grant in order to get access to the GET, PUT and DELETE operations.

A scope need not be specified for the grant.

Data Model

OBClientRegistrationRequest1

Data Dictionary

The table below identifies the claims that may be included in a JWT body for a Dynamic Client Registration POST and PUT requests.

The API responds with the same set of claims, but as part of a JSON object. It includes all the claims in the software_statement provided in the request, but each of these is flattened out as a top-level attribute of the JSON object.

The last column identifies whether the claims are provided in the request, response or both.

Prior to making a request, the TPP must query the ASPSP's OIDC .well-known end-point to identify the subset of code values that are supported by the ASPSP.

If the requests contains a value that the ASPSP does not support, the ASPSP must either:

• reject the request with an appropriate error message and error code
• accept the request and modify the value of the field to one that it supports. It must return the modified value as part of the response.

An ASPSP may ignore claims in the request that it cannot process.

tls_client_auth_subject_dn

Error Structure

In the case where the ASPSP makes a negative determination and refuses to create a client, the ASPSP MUST return a client registration error response to the TPP conforming to Section 3.2.2 of [RFC7591].

Data Mapping

This section of the specification is non-normative. The objective is to provide an overview of the various data items in the ecosystem and how they flow across from one to the other.

Swagger Specification

The Swagger Specification for the Dynamic Client Registration API can be downloaded from the following links:

• JSON
• YAML

Appendix 1: OBIE Directory SSA

This specification does not include the claims that should form a part of the software statement as this should be provided by the software statement issuer and may differ from one issuer to another.

For organizations that rely upon OBIE Directory-issued SSAs, the swagger specification can be found in the repository at https://github.com/OpenBankingUK/directory-api-specs in the YAML file.