Client registration interceptor SPI

1. Overview

The client registration endpoint is an API for setting up OAuth 2.0 clients and OpenID relying parties. In cases when the clients are expected to self-register, a process which is called dynamic client registration, the submitted client metadata can include a software statement, a signed JWT which attests the client's right to register and locks selected metadata parameters, for example the application name and logo to be displayed in the consent screen.

Software statements are used in OpenBanking, which are attested by a central directory responsible for listing the approved client applications. In OpenBanking the top-level client metadata must also be signed with JWS (normally it's plain JSON).

To handle such registration requests, with software statements or other profiles, the Connect2id server has an interface (SPI) to plug in in the necessary logic for the statement validation.

The SPI is available since v10.3.

2. Registration interceptor SPI

The interceptor SPI allows HTTP requests intended for the client registration endpoint to be transparently captured and pre-processed, before being sent on to the actual endpoint.

Some of the actions that can be performed:

  • Rewriting HTTP request headers or the metadata.

  • Validate signatures and other embedded authorisations.

  • Process software statements, by validating the statement JWT with its signature, and merging the signed parameters into the top-level client metadata.

  • Enforce custom policies.

  • Perform monitoring of incoming requests.

An interceptor plugin can also choose to pass the HTTP request unmodified.

To plug in your own custom checks implement the RegistrationInterceptor SPI defined in the Connect2id server toolkit:

Git repo

Features of the interceptor SPI:

  • Separate interception of HTTP POST, GET, PUT and DELETE requests, the default methods simply pass on the HTTP request unmodified.

  • Provides an initialisation method, e.g. for configuration purposes.

If the Connect2id server detects an SPI implementation it will log its loading under OP5203.

INFO main MAIN - [OP5203] Loaded registration interceptor class com.nimbusds.openid.connect.provider.spi.reg.statement.SoftwareStatementVerifier: enabled=false

3. Available plugins

Connect2id provides a ready plugin for verifying registration requests with software statements, which can also handle the Open Banking registration profile where the registration request is encoded into a signed JWT and the client authenticates additionally with mutual TLS.

The plugin code is open (Apache 2.0 license).

Git repo