Qualified X.509 certificates for private_key_jwt client authentication in Connect2id server 12.12

2022-06-06

Connect2id server 12.12 focuses on shipping new client authentication capabilities. It also packs an additional plugin for web-hook based handling of OAuth 2.0 client credential grants.

Qualified certificates for private_key_jwt

To process token and other requests with private_key_jwt client authentication the Connect2id server needs a copy of the public key for the JWT assertions in order to verify their signature. The public key has been traditionally set in the client registration, in JWK format, using the standard jwks or jwks_uri parameter.

Starting with this release the public key can now also be passed in a X.509 certificate included in the private_key_jwt itself.

Use cases and benefits of this method:

Enables straightforward use of qualified certificates to establish the client credential. The certificate can be issued by a national, industry or some other authority recognised by the identity provider. For internal applications and services the issuer can be a local CA.
The need for explicit registration of a client JWK set is obviated.
Since no client JWKs are registered with the Connect2id server the need for the client to manage key roll-over also falls away.

Clients include the certificate BASE64 encoded in the x5c (X.509 certificate chain) header of the JWT assertion.

Example JWT header and claims for a private_key_jwt with certificate:

{
  "alg" : "RS256",
  "x5c" : [ "MIIE3jCCA8agAwIBAgICAwEwDQYJKoZIhvcNAQEFBQAwYzELMAkGA1UEBhMC..." ]
}

{
  "iss" : "oe7aiz60",
  "sub" : "oe7aiz60",
  "aud" : "https://demo.c2id.com/token",
  "exp" : 1453021544,
  "jti" : "Eefaevo0"
}

Deployments that wish to support certificates for establishing the public key for private_key_jwt authentication are provided with a new plugin interface (SPI) where they can define the policy and verification logic for the certificates.

Note that the existing tls_client_auth also supports certificate-based authentication, but over mutual TLS, and with the extra benefit of sender constraining any issued access tokens to the client. This enhanced token security is missing in private_key_jwt authentication, even when it makes use of a X.509 certificate to establish the public key.

Plugin interface for client authentication events

Another new plugin interface (SPI) that arrives in this release is for intercepting client authentication success and error events. Identity providers and authorisation servers can now create plugins for custom logging, auditing and reporting of client authentications, in real time.

public class MyPlugin implements ClientAuthenticationInterceptor {

        @Override
        public void interceptSuccess(
            final ClientAuthentication clientAuth,
            final ClientAuthenticationContext ctx)
                throws InvalidClientException {

            // do something on client auth success...
        }

        @Override
        public void interceptError(
            final ClientAuthentication clientAuth,
            final InvalidClientException exception,
            final ClientAuthenticationContext ctx) {

            // do something on client auth error...
        }
}

Client authentications accepted by the Connect2id server can be subjected to additional checks and potentially rejected with an invalid_client error if they shouldn't proceed due to some custom rule or policy.

client_auth_id

Every incoming client authentication, at the token endpoint or elsewhere, is now tagged with a unique client_auth_id. This identifier will appear in the Connect2id server log messages, in the plugin invocation contexts related to client authentication, and in the HTTP 401 error responses if the client authentication failed.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error"             : "invalid_client",
  "error_description" : "Invalid client: Possible causes may be missing /
                         invalid client_id, missing client authentication,
                         invalid or expired client secret, invalid or expired
                         JWT authentication, invalid or expired client X.509
                         certificate, or an unexpected client authentication
                         method",
  "client_auth_id"    : "cgXB4EyYViWPt6g2"
}

The client_auth_id and how to use it to debug or report client authentications is explained here.

Web-based handler plugin for the OAuth 2.0 client credentials grant

The c2id.war now packs a plugin (disabled by default) for delegating the authorisation logic for OAuth 2.0 client credentials grant handling to a web-hook.

The web API resembles the one for the existing web-based handler of OAuth 2.0 password grant.

Download 12.12

For the signature validation: Public GPG key

Standard Connect2id server edition

Apache Tomcat package with Connect2id server 12.12: Connect2id-server.zip

GPG signature: Connect2id-server.zip.asc

SHA-256: 343efc3e1c4214ca93b854a5beb3935a29397d5cf9b3d86484c0ebd4b6e21703

Connect2id server 12.12 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: feadd400abe9c9516de2490af39d5070c81d26c32fbd64e15f2f706415e909af

Multi-tenant edition

Apache Tomcat package with Connect2id server 12.12: Connect2id-server-mt.zip

GPG signature: Connect2id-server-mt.zip.asc

SHA-256: 4114b573604979badf3c537e00f553a273dfa8abf554a88552003a891d41fc80

Connect2id server 12.12 WAR package: c2id-multi-tenant.war

GPG signature: c2id-multi-tenant.war.asc

SHA-256: ddaf350a3c6087e61a2387db7293d2b5db5d079b0bfc95d8e0394663bacb5f42

Questions?

If you have technical questions about this new release contact Connect2id support. To purchase a production license for the Connect2id server, renew or upgrade your support and updates subscription, email our sales.

Release notes

12.12 (2022-06-03)

Summary

New plugin interface (Service Provider Interface, or SPI) for accepting qualified X.509 certificates to verify the digital signature in private_key_jwt client authentications.
New plugin interface (SPI) for intercepting client authentication success and failure events at all Connect2id server endpoints where client authentication occurs. Can be used for logging, reporting, audit, debugging and other purposes.
Introduces a secure random 12 byte "client_auth_id" to identify each individual client authentication performed by the Connect2id server in log messages, OAuth 2.0 invalid_client errors and calls to SPIs like the new private key JWT certificate verifier and the client authentication interceptor.
Includes a web-based handler plugin for the OAuth 2.0 client credentials grant, implementing the ClientCredentialsGrantHandler SPI from the Connect2id server SDK. This handler is not compatible with the multi-tenant edition of the Connect2id server. Disabled by default. The default client credentials handler remains the existing local one (com. nimbusds:oauth-client-grant-handler:2.0.2).

Web API

/token
- OAuth 2.0 invalid_client error objects include a "client_auth_id" to identify the client authentication event in server log messages and SPI calls.
/token/introspect
- OAuth 2.0 invalid_client error objects include a "client_auth_id" to identify the client authentication event in server log messages and SPI calls.
/token/revoke
- OAuth 2.0 invalid_client error objects include a "client_auth_id" to identify the client authentication event in server log messages and SPI calls.
/par
- OAuth 2.0 invalid_client error objects include a "client_auth_id" to identify the client authentication event in server log messages and SPI calls.

Configuration

/WEB-INF/clientGrantHandlerWebAPI.properties -- New configuration file for the client credentials grant handler plugin that delegates processing of the grant authorisation to a web-service. The configuration properties can be overridden or set with Java system properties.

SPI

Upgrades the Connect2id server SDK to com.nimbusds:c2id-server-sdk:4.44
- com.nimbusds.openid.connect.provider.spi.clientauth. PrivateKeyJWTCertificateVerifier -- New SPI for verifying an X.509 certificate (x5c) in private_key_jwt} client authentications. This can be used to enable private_key_jwt authentication based on qualified certificates and without a prior client JWK set registration (via the "jwks" or "jwks_uri" client metadata parameters).
  
  The SPI enables implementation of policies where only selected clients are allowed or required to include a certificate for the private_key_jwt, based on the client's registered metadata or other criteria.
  
  A client can place the certificate in the private_key_jwt "x5c" header. Alternatively, the certificate can be put in the "x5c" parameter of a matching public JWK and have the key pre-registered via the "jwks" or "jwks_uri" client metadata parameter.
  
  Implementations must be thread-safe.
- com.nimbusds.openid.connect.provider.spi.clientauth. ClientAuthenticationInterceptor -- New SPI for intercepting successful and failed client authentications at all Connect2id server endpoints where client authentication occurs, such as the token, token introspection, token revocation and pushed authorisation request (PAR) endpoints. Successful client authentications can be subjected to additional checks and rejected with an OAuth 2.0 invalid_client error.
  
  Implementations must be thread-safe. Interceptors that create events should use a separate thread for blocking operations.

Resolved issues

Fixes an HTTP 500 Internal Server Error on a token revocation request with client authentication where the client_id resolves to an invalid client registration (issue server/760).
The message OP0131 ("Couldn't determine Connect2id server local host") should be logged at WARN level, not ERROR (issue server/759).

Dependency changes

Upgrades to com.nimbusds:c2id-server-sdk:4.44
Upgrades to com.nimbusds:oauth2-oidc-sdk:9.37.2
Upgrades to com.nimbusds:nimbus-jose-jwt:9.23
Updates to Infinispan 9.4.24
Updates to com.unboundid:unboundid-ldapsdk:6.0.5
Updates to com.nimbusds:oauth-password-grant-web-api:1.5
Updates to com.nimbusds:oauth-client-grant-handler:2.0.2
Adds com.nimbusds:oauth-client-grant-web-api:1.4