OpenID Connect Federation 1.0 becomes available in Connect2id server 10.0

2020-08-24

The focus of this major release of the Connect2id server was implementing the necessary protocols to support identity provision under a federation operator. Pushed authorisation requests (PAR), mTLS and refresh tokens also received new features.

OpenID Connect Federation 1.0

The concept of identity federation, letting users sign-in with one or more trusted IdPs, is at least 20 years old. Running federations at scale, however, can become prohibitively expensive due to the IT administration burden to add and configure approved IdPs and client applications, and then maintain the list of the approved entities and their configurations up to date. If we look around carefully we'll discover that very few identity federations at scale actually exist, save for a couple in education, where nightly batch jobs help to collect and redistribute the entity configurations in a single huge file. The vast majority of federations rarely exceed several IdPs and a dozen or so relying parties.

OpenID Connect Federation 1.0 is a new protocol for operating large federations, spanning potentially thousands of IdPs and applications, in manner that is robust and efficient to manage. It originated in the research and education community, with the goal to supercede the existing SAML 2.0 based federations relying on the mentioned nightly batch job. Users can seamlessly sign into applications which are local or belong to some other trusted participating organisation. The sign-in can occur with a trusted IdP at departmental, organisational or some higher level.

The federation is established by a single registry or by multiple registries, which can be hierarchical (similar to the DNS) or lateral (peers). This enables tree or mesh like trust relationships to be defined in a federation. Organisations can be given the authority to operate their own registries for the IdP(s) and client applications in their domain, simplifying the overall management of the federation by means of delegation.

The federation protocol crucially automates the following tasks:

• The check if a federation entity, such as an OpenID provider or an application, can be trusted. This process is called trust chain resolution and is secured by means of publicly verifiable JSON Web Signatures (JWS).

• Obtaining a federation entity's metadata and keys.

• Performing other necessary steps, such as client registration for an OpenID relying party to obtain a client_id from the chosen OpenID provider.

• Periodic checks that an entity can still be trusted and updating its metadata and registrations if necessary.

The protocol can also federate entities which are plain OAuth 2.0 servers, plain OAuth 2.0 clients and resource servers (web APIs).

Connect2id server 10.0 implements OpenID Connect Federation 1.0 with a variant of client registration called explicit, which does not require the application to provide a new special endpoint for its federation metadata (otherwise required for the other variant - the automatic federated client registration). Note that both variants are fully automated, despite what the name might suggest.

Federation with explicit client registration was successfully tested in an OpenID Foundation interop which was concluded in July. Support for automatic registration will appear in a future release.

To enable a Connect2id server deployment for OpenID Connect Federation 1.0 set the op.federation.enable configuration parameter to true and also configure the other necessary federation parameters. A JWK for signing the federation entity statements issued by the OpenID provider must also be provided.

The open source OpenID Connect SDK maintained by Connect2id already has support for building federated relying parties. Check the examples.

Self-contained refresh tokens for transient authorisations

The Connect2id server can now issue refresh tokens for transient (non-persisted) authorisations, where the authorisation data is contained entirely in the refresh token, secured with JWE.

For example, to issue a refresh token for a transient authorisation when handling an OAuth 2.0 code grant in the authorisation session API simply set the refresh token issue flag in the consent object parameters:

{
  "scope"         : [ "https://rs.example.com/account/read" ],
  "long_lived"    : false,
  "refresh_token" : { "issue" : true }
}

Previously refresh tokens could be issued only for long-lived (persisted) authorisations (long_lived=true), where the tokens is an encrypted random identifier pointing to an authorisation record in the Connect2id server database.

The Connect2id server can issue an unlimited number of self-contained refresh tokens for a given client and subject (end-user). This can be useful in cases where an end-user has instances of a public client on several devices, but the granted authorisations must not be shared between the client instances. Revocation applies to all client instances.

The new refresh tokens necessitated a modification of the revocation call, which is part of the authorisation store web API. In particular, the HTTP status codes were updated to reflect the new capability. The authorisation store API was thus given a new version - v3. The previous v2 of the API remains available (documented in the archive for Connect2id server versions 7.x through 9.x).

We recommend integrations to use the new v3 API and update the revocation POST requests if necessary.

Global and per-client PAR policy

The Pushed Authorisation Requests (PAR) were updated to the latest draft 02 which defines new client and server metadata parameters to indicate PAR usage is required.

To set a global OAuth 2.0 server policy requiring all clients to push their authorisation requests use the new op.par.require configuration setting. Client developers can find out if PAR is required globally by checking the new require_pushed_authorization_requests server metadata parameter.

The PAR requirement can also be set on a individual client basis, by setting a require_pushed_authorization_requests client metadata parameter. Here is an example how to require PAR for a given client when it's being registered:

POST /c2id/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris"                         : [ "https://client.example.org/cb" ],
  "require_pushed_authorization_requests" : true
}

When PAR is required, globally or for a specific client, authorisation requests which have not been pushed will be rejected with an invalid_request error and a simple explanatory message.

HTTP/1.1 302 Found
Location: https://client.example.com/cb?
 error=invalid_request
 &error_description=PAR+required
 &state=cai8li0Lae0Eifae

Enforcing issue of client certificate bound tokens

The Connect2id server has now complete support for the tls_client_certificate_bound_access_tokens client metadata parameter from the mTLS OAuth 2.0 profile (RFC 8705, section 3). It is intended for enforcing issue of X.509 client certificate bound access tokens to an OAuth 2.0 client.

Registering a client with the parameter enabled will require it to present a client certificate (self-signed or CA-issued) at the token endpoint. If no certificate is presented the client will receive an invalid_client token error response with HTTP status code 401 Unauthorized.

POST /c2id/clients HTTP/1.1
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris"                              : [ "https://client.example.org/cb" ],
  "tls_client_certificate_bound_access_tokens" : true
}

Note that this policy will apply independently of how the client is registered to authenticate at the token endpoint, and will apply to public clients also. Previously, to enforce issue of client certificate bound tokens the client had to be registered for mTLS authentication (self_signed_tls_client_auth), and thus making the client X.509 certificate required.

Check out the guide for how to set up a TLS termination proxy, such as Nginx or Apache httpd, for client certificates.

Unlimited integration API tokens

Connect2id server deployments can now be configured with multiple access tokens for each integration web API. This can help to facilitate roll-over or provide separate access for each integration.

Example for the session store API token:

// Primary token
sessionStore.apiAccessTokenSHA256=5d2783bbdd0a5a41fffc934b8f0386df01ff26338dfa7131b65da924a4591dcf

// Additional tokens
sessionStore.apiAccessTokenSHA256.1=3cd6140df106ae84fbd9e99af256d2ca9ee54829ba52ca3f821f7f057ef5cf92
sessionStore.apiAccessTokenSHA256.2=94a4a5f4b19682e3153983c36833e8646976b9ac790f415997ca5aa0182efd43
sessionStore.apiAccessTokenSHA256.3=3996f543eea4bf3ac801dd46ca140e6951c2c89943430b17ecac44e170f07487

Note that the SHA-256 hashes of the token are configured, not the actual token values.

Upgrading to Connect2id server 10.0

• Database schema

  The database schema was updated in v10.0. For a SQL RDBMS backend the Connect2id server will automatically create the new federation client tracking table and other required columns when the new server version starts up. With DynamoDB, which is essentially a schema-less database, no special procedure is required. LDAPv3-based stores will require a manual schema update, consult the release notes below for instructions.

• New authorisation store web API v3

  The new self-contained refresh token required a change in the revocation resource, which now returns slightly different HTTP status codes on success. The new API was given a new version - v3, with all other API resources and calls remaining unaffected. The old v2 of the API remains available. Consult the release notes below for details.

• Breaking change in the OAuth 2.0 / OpenID Connect SDK

  The underlying OAuth 2.0 / OpenID Connect SDK was upgraded to the latest major 8.x release. In it the deprecated javax.mail dependency and all deprecated API methods relying its classes are finally removed. If you have implemented a native Java claims source connector which relies on the javax.mail.Address class for the "email" claim switch to the java.lang.String based getter / setter method of the UserInfo class.

Download

Standard Connect2id server edition

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

SHA-256: 278822d8909df438b050497a6a861902e42ae10bae138910791452338fd1a6f8

Connect2id server 10.0 WAR package: c2id.war

SHA-256: 216f9b3f0c00bcfc90e58f7122a1974c16718e3c5cf18f45eb67fa3c1b09cb81

Multi-tenant edition

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

SHA-256: f6c21cbb359e304820a4e2f750419015a499e870c610d0cdff4009d9e47a0fe7

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

SHA-256: 87ac06cabcdf498febefc6b30982fcc398efd15558ed89ae74494a5fcbc8772d

Questions?

Contact Connect2id support.

---

Release notes

10.0 (2020-08-18)

Summary

• Supports OpenID Connect Federation 1.0 (draft 12) with explicit client registration. The extension to OpenID Connect enables seamless single sign-on and identity provisioning in a federation of OpenID providers and relying parties approved by one or more operators (trust anchors), potentially involving intermediate authorities. See https://openid.net/specs/openid-connect-federation-1_0-12.html

• Enables issue of refresh tokens for transient (non-persisted) authorisations, where the authorisation data is contained in the refresh token (as encrypted JWT). Previously refresh tokens could be issued only for long-lived (persisted) authorisations, where the refresh token is an encrypted key pointing to the authorisation record. The Connect2id server can issue an unlimited number of self-contained refresh tokens for a given client and subject (end-user). This can be useful in cases where an end-user has instances of a public client on several devices, but the granted authorisations must not be shared between the client instances. Revocation applies to all client instances.

• Supports setting of global or client-specific policy for enforcing use of pushed authorisation requests (PAR) only, and rejecting regular requests at the authorisation endpoint (including JAR). The new op.par.require configuration sets the global PAR policy. The new require_pushed_authorization_requests client metadata parameter sets the PAR policy for an individual OAuth 2.0 client. Clients which must use PAR will receive an invalid_request error with message "PAR required" from the authorisation endpoint if they attempt a regular request. See OAuth 2.0 Pushed Authorization Requests (draft-ietf-oauth-par-02).

• The authorisation store web API receives a new version with endpoint /authz-store/rest/v3 with an updated "revocation" resource, to handle revocation of non-persisted authorisations tied to self-contained refresh tokens. The previous web API version at endpoint /authz-store/rest/v3 remains available.

• Supports the tls_client_certificate_bound_access_tokens client metadata parameter from OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens (RFC 8705). Intended for enforcing issue of X.509 client certificate bound access tokens to a public (non-authenticating) client. The client must present a client certificate (self-signed or CA issued) at the token endpoint; if no certificate is presented the client will receive an invalid_client token error response with HTTP status code 401 Unauthorized.

• Supports configuration of unlimited additional access tokens for the Connect2id server integration web APIs, to facilitate token roll-over and for other purposes.

• Upgrades the OAuth 2.0 / OpenID Connect SDK to major release 8.0 which removes the deprecated javax.mail dependency and all deprecated API methods relying on its classes. ClaimsSource and AdvancedClaimsSource SPI implementations which rely on the javax.mail.Address class for the "email" claim need to switch to an alternative java.lang.String based getter / setter method of the UserInfo class.

Configuration

• /WEB-INF/federationJWKSet.json -- New JSON Web Key (JWK) set file for configuring one or more RSA keys for signing the issued federation entity statements. The RSA keys must have a size of 2048 bits, a unique key identifier (kid), a key use (use) set to signature (sig) and an algorithm (alg) set to RS256. The first RSA JWK in the list will be used for signing. Previously used keys to facilitate roll-over can follow. The federation JWK set can be alternatively passed via a op.federationJWKSet Java system property, optionally with additional BASE64URL encoding to avoid shell escaping of special JSON characters. For more information regarding key generation and configuration see https://connect2id.com/products/server/docs/config/jwk-set#config

• /WEB-INF/oidcProvider.properties

  • op.federation.enable -- Enables / disables support for OpenID Connect Federation 1.0. Disabled by default.

  • op.federation.clientRegistrationTypes -- The supported client registration types. Supported client registration types: explicit

  • op.federation.organizationName -- The organisation name in the federation, blank if not specified.

  • op.federation.trustAnchors.* -- The configured trust anchors. Must contain at least one entity ID.

  • op.federation.authorityHints.* -- The intermediate entities or trust anchors that may issue an entity statement about the OpenID Connect provider. Must contain at least one entity ID.

  • op.federation.constraints.maxPathLength -- The maximum path length when resolving trust chains. The default value is 2 (up to two intermediates to the trust anchor).

  • op.federation.constraints.permitted.* -- The explicitly permitted entity IDs when resolving trust chains, blank if not specified.

  • op.federation.constraints.excluded.* -- The excluded entity IDs when resolving trust chains, blank if not specified.

  • op.federation.httpRequestTimeout -- The HTTP read timeout (in milliseconds) when resolving trust chains. Zero implies no timeout. Must not be negative. The default value is 500 ms.

  • op.federation.httpReadTimeout -- The HTTP read timeout (in milliseconds) when resolving trust chains. Zero implies no timeout. Must not be negative. The default value is 500 ms.

  • op.federation.contacts.* -- List of contacts for this federation entity. These may contain names, e-mail addresses, descriptions, phone numbers, etc. Blank if not specified.

  • op.federation.policyURI -- URL of the federation entity policy. The URL can be also be specified relative to the issuer URL (op.issuer). Blank if not specified.

  • op.federation.homepageURI -- URL of the federation entity homepage. The URL can be also be specified relative to the issuer URL (op.issuer). Blank if not specified.

  • op.federation.trustMarks.* -- Trust marks about this federation entity as signed JSON Web Tokens (JWT). Blank if not specified.

  • op.federation.entityStatementLifetime -- The lifetime of issued entity statements, in seconds. The default lifetime is one week (604800 seconds).

  • op.reg.apiAccessTokenSHA256.* -- Supports configuration of additional API access tokens, to facilitate token roll-over or for other needs. Those are configured by appending a dot (.) with a unique label to the property name, e.g. as op.reg.apiAccessTokenSHA256.1=abc...

    The support for op.reg.secondaryAPIAccessTokenSHA256 remains, however deployments are encouraged to switch to the new configuration method.

  • op.authz.apiAccessTokenSHA256.* -- Supports configuration of additional API access tokens, to facilitate token roll-over or for other needs. Those are configured by appending a dot (.) with a unique label to the property name, e.g. as op.authz.apiAccessTokenSHA256.1=abc...

  • op.logout.apiAccessTokenSHA256.* -- Supports configuration of additional API access tokens, to facilitate token roll-over or for other needs. Those are configured by appending a dot (.) with a unique label to the property name, e.g. as op.logout.apiAccessTokenSHA256.1=abc...

  • op.par.require -- Enforces a global pushed authorisation requests (PAR) only policy. If true the Connect2id server will accept authorisation requests initiated via PAR only, regular authorisation requests will be rejected at the authorisation endpoint with an invalid_request error. The default value is false.

• /WEB-INF/sessionStore.properties

  • sessionStore.apiAccessTokenSHA256.* -- Supports configuration of additional API access tokens, to facilitate token roll-over or for other needs. Those are configured by appending a dot (.) with a unique label to the property name, e.g. as sessionStore.apiAccessTokenSHA256.1=abc...

    The support for sessionStore.secondaryAPIAccessTokenSHA256 remains, however deployments are encouraged to switch to the new configuration method.

• /WEB-INF/authzStore.properties

  • authzStore.apiAccessTokenSHA256.* -- Supports configuration of additional API access tokens, to facilitate token roll-over or for other needs. Those are configured by appending a dot (.) with a unique label to the property name, e.g. as authzStore.apiAccessTokenSHA256.1=abc...

    The support for authzStore.secondaryAPIAccessTokenSHA256 remains, however deployments are encouraged to switch to the new configuration method.

• /WEB-INF/monitor.properties

  • authzStore.apiAccessTokenSHA256.* -- Supports configuration of additional API access tokens, to facilitate token roll-over or for a load balancer to monitor the health of the Connect2id server. Those are configured by appending a dot (.) with a unique label to the property name, e.g. as monitor.apiAccessTokenSHA256.1=abc...

    The support for monitor.secondaryAPIAccessTokenSHA256 remains, however deployments are encouraged to switch to the new configuration method.

• /WEB-INF/infinispan-*.xml

  • Adds new "federation.registrationsMap" to Infinispan for tracking the registered federation clients.

    In deployments with an SQL RDBMS (MySQL, PostreSQL, MS SQL Server, H2) the Connect2id server on startup will automatically create a new "federation_clients" table for persisting tracking metadata about the federation clients.

    In deployments with AWS DynamoDB the Connect2id server on startup will automatically create a new "federation_clients" table for persisting the federation clients metadata.

    In deployments with Redis the federation clients metadata will be stored in a separate database with number 15.

    In deployments with LDAP the federation clients metadata will be kept in memory only and will not be persisted. Support for LDAP persistence and an appropriate schema will be added in a future release or upon request.

• /WEB-INF/infinispan-*-{mysql|postgres95|sqlserver|h2}.xml

  • Adds new "require_pushed_authorization_requests" and "tls_client_certificate_bound_access_tokens" columns to the "clients" table. In existing Connect2id server deployments with an SQL RDBMS the server will automatically add the new columns (with an appropriate default value) on startup.

• /WEB-INF/infinispan-*-ldap.xml

  • Adds new "oauthRequirePAR" and "oauthClientCertBoundAccessTokens" attributes to the "oauthClientIdentity" object class. Connect2id server deployments with an LDAP v3 backend database (such as OpenLDAP or OpenDJ) need to update the LDAP schema manually to version 1.13 see https://bitbucket.org/connect2id/server-ldap-schemas/src/1.13/ , the OpenLDAP schema diff https://bitbucket.org/connect2id/server-ldap-schemas/diff/ src/main/resources/oidc-client-schema-openldap.ldif?at=1.13 &diff2=135b1b503919b270a2cb4a8e44dfbfc8fd0a4e27 and the OpenDJ schema diff https://bitbucket.org/connect2id/server-ldap-schemas/diff/ src/main/resources/oidc-client-schema-opendj.ldif?at=1.13 &diff2=135b1b503919b270a2cb4a8e44dfbfc8fd0a4e27

Web API

• /.well-known/openid-federation

  • New endpoint for retrieving the OpenID provider's self-signed federation entity statement. See OpenID Connect Federation 1.0 (draft 12), section 5.

• /federation/clients

  • New endpoint for explicit registration of federation entities as OpenID relying parties. See OpenID Connect Federation 1.0 (draft 12), section 9.2.

• /.well-known/openid-configuration, /.well-known/oauth-authorization-server

  • Adds support for the "require_pushed_authorization_requests" metadata parameter from OAuth 2.0 Pushed Authorization Requests (draft-ietf-oauth-par-02), controlled by the new op.par.require configuration setting.

• /clients

  • Adds support for the "require_pushed_authorization_requests" client metadata parameter from OAuth 2.0 Pushed Authorization Requests (draft-ietf-oauth-par-02).

  • Supports setting of the "tls_client_certificate_bound_access_tokens" client metadata parameter from OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens (RFC 8705).

• /authz-store/rest/v3

  • New version 3 of the authorisation store web API. Modifies the HTTP response from the "revocation" resource as follows: Revocations will always succeed with a 2xx HTTP status code. If the revocation matches one or more long-lived (persisted) authorisations those will be returned with a 200 Success status, as previously. Else a 204 No Content status will be returned (previously a 404 Not Found), as the revocation may match a transient authorisation with a self-contained (JWT) access and / or refresh token.

• /authz-store/rest/v2

  • The previous version of the authorisation store web API remains available.

Resolved issues

• Increases the size of the jwks column for H2 from VARCHAR 10000 to VARCHAR 50000 (issue server/578). The H2 command to alter an existing clients table is ALTER TABLE "clients" ALTER COLUMN "jwks" SET DATA TYPE VARCHAR(50000);.

• Changes the data type of the jwks column for MySQL from VARCHAR 10000 to JSON to increase the size while working around the limit of 65535 bytes per row (issue server/578). The MySQL command to alter an existing clients table is ALTER TABLE clients MODIFY jwks JSON;.

• All startup and configuration errors must be logged in c2id-server.log (issue server/569)

Dependency changes

• Upgrades to com.nimbusds:c2id-server-sdk:4.22

• Upgrades to com.nimbusds:c2id-server-ldap-schemas:1.13

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

• Upgrades to com.nimbusds:tenant-registry:5.2

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

• Upgrades to com.nimbusds:oidc-session-store:14.1.3

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

• Upgrades to com.nimbusds:nimbus-jwkset-loader:5.0

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

• Updates to com.nimbusds:content-type:2.1

• Updates to com.nimbusds:oauth-password-grant-web-api:1.4

• Upgrades to com.nimbusds:common:2.43.1

• Upgrades to com.thetransactioncompany:java-property-utils:1.15

• Adds javax.activation:javax.activation-api:1.2.0

• Removes com.sun.mail:javax.mail:1.6.2