Blog »

Connect2id server 13.1 ships an OpenID Connect Federation 1.0 upgrade

2022-12-29

In August 2020 Connect2id 10.0 became capable of serving client applications adhering to a new trust establishment protocol called OpenID Connect Federation 1.0. A client and a server determine whether they can trust one another by relying on a common authority, called a trust anchor. Once mutual trust is established, the client can proceed with requesting ID and access tokens from the Connect2id server using standard OAuth 2.0 and OpenID Connect.

This protocol for establishing trust comes with a clever built-in mechanism that lets participating entities publish metadata particular to their role. An OpenID relying party can thus make its metadata discoverable by potential OpenID providers it may interact with in future, eliminating the need for explicit client registration with potentially costly human involvement.

This enables client applications to sign-in users by simply proceeding with an OpenID authentication request where the client_id is an https URL uniquely identifying the client and typically based in its web domain. The request is authenticated by signing it (as JWT) with a key which the Connect2id server can check for belonging to the client by following a chain of assertions reaching the trust anchor.

Example OpenID authentication request with a client_id set to an https://rp.example.com URL and a signed request object (JWT):

https://demo.c2id.com/login?
response_type=code
&client_id=https%3A%2F%rp.example.com
&scope=openid+profile+email
&request=eyJraWQiOiJLLVFLM0JTY0NWYTZXY2wzRHFDZXg3amQ0VFBMV1dhRkFXbnNiQnNU...

OpenID Connect Federation 1.0 is the only current practical standards based solution to run an identity scheme that can scale to many identity providers and client applications. Once an entity is enrolled with a trust anchor or a recognised intermediary all communication as well as metadata policing, discovery and updating can occur automatically, feed from manual human administration tasks. That's the reason Italy chose the protocol for its national eID in 2021, enabling the federation of about a dozen IdPs used by thousands of applications.

This release of the Connect2id server upgrades its support for OpenID Federation 1.0 to the latest draft 25. The spec received numerous refinements after the start of its adoption in Italy. It also became central to the GAIN initiative of the OpenID Foundation, where experts from the community have gathered to define an OpenID Connect profile for establishing trust and interoperability between relying parties and providers of verified identities, spanning various identity ecosystems around the world. The spec is expected to reach completion and become an official OpenID standard in 2023.

One significant feature of this Connect2id server release is the ability of the pushed authorisation request (PAR) endpoint to also handle requests from OpenID Connect Federation 1.0 relying parties without a prior client registration step. The client application only needs to authenticate its PAR by means of a public key that can be verified by means of the trust establishment protocol.

Example PAR with a client_id set to an https://rp.example.com URL and using mTLS authentication:

POST /par HTTP/1.1
Host: demo.c2id.com
Content-Type: application/x-www-form-urlencoded

response_type=code
&client_id=https%3A%2F%rp.example.com
&scope=openid%20profile%20email
&state=af0ifjsldkj
&redirect_uri=https%3A%2F%2Frp.example.org%2Fcb
&code_challenge_method=S256
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

Enabling the Connect2id server to operate in a OpenID federation is relatively simple - all its takes is to configure a federation RSA JWK for the server and at least one URL that identifies its federation trust anchor / authority.

Example federation configuration:

op.federation.enable=true
op.federation.clientRegistrationTypes=explicit,automatic
op.federation.autoClientAuthMethods.ar=request_object
op.federation.autoClientAuthMethods.par=private_key_jwt,self_signed_tls_client_auth
op.federation.organizationName=Trusted IdP
op.federation.trustAnchors.1=https://federation.example.com
op.federation.authorityHints.1=https://federation.example.com

A client application that has been enrolled with a federation authority only needs to generate a signed JWT, called entity configuration, and place it at a well-known URL in its web domain. It will then be able to work the magic of the automatic client registration, requesting ID and access tokens from participating OpenID providers as if it was already registered. The OpenID Connect / OAuth 2.0 requests remain standard form and can use existing client code.

To help clients generate a signed federation entity configuration the OAuth 2.0 / OpenID Connect SDK has an extension, which also received an update for the latest draft 25. The extension can also perform trust chain resolution, for client applications that choose to verify that an OpenID provider belongs to the federation, or for clients that use dynamic OpenID provider configuration instead of hardwired.

Download 13.1

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: 428e3c6e4af227bf3341b1bd4ddbd01a0a1887bd7fdd33ce04a2d35715e4f62a

Connect2id server 13.1 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 6dc45717cbc03e5002f88f99d9248fe8e4abd701594ca57ecfd44c06b822b202

Multi-tenant edition

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

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

SHA-256: 5174608ba2914c7a3b25cf240aad23725091b95eeb080353ab55006ca93345a9

Connect2id server 13.1 WAR package: c2id-mt.war

GPG signature: c2id-mt.war.asc

SHA-256: 1fe66e8ce925acd3d1c5d4a32b9d1d3dce347214a3edead86a448a6a965a0a91

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

13.1 (2022-12-23)

Summary

  • OpenID Connect Federation 1.0 upgrade.

    The pushed authorisation request (PAR) endpoint is now able to handle automatic registration clients authenticating with a public key using a JWT assertion (private_key_jwt) or mutual TLS (tls_client_auth or self_signed_tls_client_auth).

    The entity configuration, trust chain resolution and client registration is updated to draft 25 of the OpenID Connect Federation 1.0 specification.

    See https://openid.net/specs/openid-connect-federation-1_0.html

  • The token introspection endpoint receives a new configuration to control the pruning of audience ("aud") values in responses.

Configuration

  • /WEB-INF/oidcProvider.properties

    • op.token.introspection.pruneAudience -- New optional configuration property to override the default Connect2id server filtering (since
      v7.17 (2019-10-12)) of audience ("aud") values in token introspection responses. If true causes the audience to be pruned to the client_id of the introspecting client, intended to prevent revealing information about recipients other than the intended in multi-audience tokens. If false the complete token audience will always be shown. Has no effect on tokens that don't specify an audience. The default value is true.

    • op.federation.autoClientAuthMethods.par -- New optional configuration property listing the enabled methods for authenticating OpenID Connect Federation 1.0 automatic client registration requests at the OAuth 2.0 pushed authorisation request (PAR) endpoint. Supported methods: private_key_jwt, tls_client_auth and self_signed_tls_client_auth.

    • op.federation.logoURI -- New optional configuration property specifying the logo URI of the OpenID provider as an OpenID Connect Federation 1.0 entity. Will appear in the entity configuration published at the /.well-known/openid-federation endpoint, under the metadata.federation_entity.logo_uri claim.

  • jose.federationJWKSet -> jose.federation.jwkSet -- Renames the Java system property name for setting the OpenID Connect Federation 1.0 entity JWK set. The Java system property overrides the /WEB-INF/federationJWKSet.json JWK set file content.

Web API

  • /.well-known/openid-federation

    • Updates the published entity configuration to OpenID Connect Federation 1.0 draft 25.

    • metadata.federation_entity.logo_uri -- New optional federation entity claim, configured by the op.federation.logoURI property.

  • /par

    • Supports OpenID Connect Federation 1.0 compliant automatic registration clients that use the private_key_jwt, tls_client_auth and self_signed_tls_client_auth methods (must be enabled in the op.federation.autoClientAuthMethods.par configuration property).

  • /federation/clients

    • Updates explicit client registration to OpenID Connect Federation 1.0 draft 25.

  • /token/introspect

    • Pruning of the audience ("aud") values in token introspection responses can be now be controlled by the optional op.token.introspection.pruneAudience configuration property.

Resolved issues

  • The PAR endpoint should clear client_secret_post, client_secret_jwt and private_key_jwt form parameter artifacts from the stored authorisation request (issue server/813).

Dependency changes

  • Upgrades to com.nimbusds:oauth2-oidc-sdk:10.4

  • Updates to com.nimbusds:nimbus-jose-jwt:9.25.6

  • Upgrades to com.nimbusds:tenant-manager:7.4

  • Upgrades to com.nimbusds:oauth2-authz-store:19.4