The JSON Canonicalisation Scheme (RFC 8785) in action and how to secure JSON objects with HMAC

2020-09-07

We recently had the task to add HMAC security to DynamoDB items stored by the Connect2id server in the AWS cloud. DynamoDB is a key-value database which works well with JSON objects. Hash-based Message Authentication Codes (HMAC) is a common cryptographic method for ensuring the integrity and authenticity of data, which employs a secret key and a hashing algorithm, such as SHA-2.

The principle of HMAC

The code in the HMAC algorithms is computed over the binary representation of the data and typically stored alongside the data, for easy inspection. To check that the data has not changed the computation must be repeated by inputting the same key and the data in the exact same order of its binary representation. The stored and the recomputed codes are then compared. If the two codes don't match this is a sign that the data integrity was affected, i.e. it was modified in some way. The secret key ensures that only its holder can compute and verify the code. The code thus also serve to authenticate the data.

Example HMAC with SHA-256 of the "Hello, world!" string, which is converted to its UTF-8 / ASCII bytes representation to be input into the computation:

Input text (UTF-8): Hello, world!
Secret key (BASE64 encoded): lHG3evumVZLuM2nluoxI8hVxnSL3V8r7U+8mqUp2NR4=
Code (BASE64 encoded): UtTLGRell8x8up6b8sF44o18telWQITfOHQSxUGSNPA=

Let's see the resulting code if the comma is removed from the "Hello, world!" string:

Input text (UTF-8): Hello world!
Secret key (BASE64 encoded): lHG3evumVZLuM2nluoxI8hVxnSL3V8r7U+8mqUp2NR4=
Code (BASE64 encoded): wATR9kyMBXiog8ENqMqsP68ZDQSuvUtxh4ArvL+sgx4=

Notice how the computed code changed entirely!

The issue with JSON serialisation

JSON can represent identical data in different ways and this is part of what makes it so useful.

Consider the following identical JSON data, formatted in three different ways:

JSON formatting for compactness:

{"key":"9cea8d2d","name":"Alice Adams","age":21}

As above, but with a different member ordering:

{"key":"9cea8d2d","age":21,"name":"Alice Adams"}

"Pretty" JSON formatting for better human readability:

{
  "key" : "9cea8d2d",
  "name" : "Alice Adams",
  "age" : 21
}

If we take the above JSON strings (as ASCII or UTF-8 bytes) this will produce three different binary representations. And if we input them into a HMAC SHA-256 computation we will get three different codes. This means that for HMAC to work reliably and prevent false errors (code mismatches) the JSON data must always be presented in some deterministic, also called normalised or canonical, order.

The JSON Canonicalisation Scheme (JCS) comes to rescue

The JSON Canonicalization Scheme (JCS) is a standard algorithm for putting arbitrary JSON data in a deterministic format. It was originally motivated by the need to perform reliable cryptographic operations on JSON data, such as applying digital signatures and HMACs.

The JCS employs methods such as stripping redundant whitespace and sorting the members in JSON objects.

When JCS is applied to the sample JSON object we get:

{"age":21,"key":"9cea8d2d","name":"Alice Adams"}

Now that we got our JSON data in a canonical format we can safely take the string bytes to be input into the HMAC computation.

Input text (UTF-8): {"age":21,"key":"9cea8d2d","name":"Alice Adams"}
Secret key (BASE64 encoded): lHG3evumVZLuM2nluoxI8hVxnSL3V8r7U+8mqUp2NR4=
Code (BASE64 encoded): MLE+O33O8Rv2fdSajlaK6h3wT8yKQkbNuPCoWDRWcz4=

Storing the HMAC as part of the JSON data

The computed message authentication code can be naturally included in the JSON object that it is meant to secure:

{
  "key" : "9cea8d2d",
  "name" : "Alice Adams",
  "age" : 21,
  "_hmac#s256" : "MLE+O33O8Rv2fdSajlaK6h3wT8yKQkbNuPCoWDRWcz4="
}

To recompute the code simply remove the _hmac#s256 member and input the bytes of the JSON string (in JCS form!) to the HMAC SHA-256 algorithm.

JCS in Java

Samuel Erdtman, co-author of the JCS standard, has provided a Java open source implementation. It is only 28 KBytes of Java bytecode!

https://github.com/erdtman/java-json-canonicalization

Example Java code to turn a JSON string into canonical form and gets its bytes for HMAC or digital signature computation:

import java.nio.charset.StandardCharsets;
import org.erdtman.jcs.JsonCanonicalizer;

String json = "{ /* some JSON */ }";
JsonCanonicalizer jc = new JsonCanonicalizer(json);
byte[] hmacInput = jc.getEncodedString().getBytes(StandardCharsets.UTF_8);

How to secure DynamoDB items with HMAC

Let's now apply our JSON canonicalisation strategy to secure DynamoDB items with HMAC SHA-256:

import java.nio.charset.StandardCharsets;
import javax.crypto.Mac;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
import com.amazonaws.services.dynamodbv2.document.Item;
import org.erdtman.jcs.JsonCanonicalizer;

// Generate the secret key, must have the same size as the hash
// The key must be stored securely!
byte[] secretKeyBytes = new byte[256/8];
new SecureRandom().nextBytes(secretKeyBytes);
SecretKey secretKey = new SecretKeySpec(secretKeyBytes, "HmacSHA256")

// Some DynamoDB item to secure with HMAC
Item item;

// Get the item JSON in canonical format
JsonCanonicalizer jc = new JsonCanonicalizer(item.toJSON());
byte[] hmacInput = jc.getEncodedString().getBytes(StandardCharsets.UTF_8);

// Compute the HMAC
Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
hmacSHA256.init(secretKey);
byte[] hmac = hmacSHA256.doFinal(hmacInput);

// Include the HMAC in the DynamoDB item, the item can be saved now
item = item.withBinary("_hmac#s256", hmac);

To verify the HMAC of a DynamoDB item:

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import javax.crypto.Mac;
import com.amazonaws.services.dynamodbv2.document.Item;
import org.erdtman.jcs.JsonCanonicalizer;

// Make sure the HMAC attribute isn't missing
if (! item.hasAttribute("_hmac#s256")) {
    throw new Exception("Missing item HMAC attribute");
}

// Extract the HMAC
byte[] storedHMAC = item.getBinary("_hmac#s256");

Item baseItem = item.removeAttribute("_hmac#s256");

// Get the item JSON in canonical format
JsonCanonicalizer jc = new JsonCanonicalizer(item.toJSON());
byte[] hmacInput = jc.getEncodedString().getBytes(StandardCharsets.UTF_8);

// Recompute the HMAC
Mac hmacSHA256 = Mac.getInstance("HmacSHA256");
hmacSHA256.init(secretKey);
byte[] recomputedHMAC = hmacSHA256.doFinal(hmacInput);

// Compare the two HMACs
if (! MessageDigest.isEqual(storedHMAC, recomputedHMAC)) {
    throw new Exception("Invalid item HMAC");
}

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

Connect2id server 9.5.2

2020-08-08

This is a maintenance update of the Connect2id server. It fixes a bug in logic related to the custom token response SPI. Deployments which have a plugin for this SPI should upgrade.

For details check the release notes below.

Download

Standard Connect2id server edition

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

SHA-256: 278822d8909df438b050497a6a861902e42ae10bae138910791452338fd1a6f8

Connect2id server 9.5.2 WAR package: c2id.war

SHA-256: 216f9b3f0c00bcfc90e58f7122a1974c16718e3c5cf18f45eb67fa3c1b09cb81

Multi-tenant edition

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

SHA-256: f6c21cbb359e304820a4e2f750419015a499e870c610d0cdff4009d9e47a0fe7

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

SHA-256: 87ac06cabcdf498febefc6b30982fcc398efd15558ed89ae74494a5fcbc8772d

Questions?

Contact Connect2id support.

Release notes

9.5.2 (2020-08-08)

Resolved issues

Fixes a bug which produced an internal server error (HTTP 500) at the token endpoint when a CustomTokenResponseComposer SPI implementation is installed and the server produces a token error response for a particular setting of the authorisation (issue server/581).

Connect2id server 9.5.1

2020-06-22

This is a maintenance release of the Connect2id server.

Fixes a bug which will produce an HTTP 500 at the token endpoint if illegal characters appear in a submitted authorisation code.
Fixes a bug which affects publishing of EdDSA signing keys in the server JWK set. Deployments which intend to make use of EdDSA-signed access tokens introduced in 9.4 should be updated.
Rolls back support for JWT authentication (client_secret_jwt and private_key_jwt) at the token revocation endpoint accepting the token endpoint URI as JWT "aud" (audience), removed unannounced in 8.0. Note that client applications should use an "aud" value set to the exact endpoint URI and acceptance of alternative audience values may be removed in a future release as a security measure.
Logs the exact cause when client authentication at the token revocation endpoint fails.

For details check the release notes below.

Download

Standard Connect2id server edition

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

SHA-256: 6bd8409448f8f34e73c9147f54b44c84524009e2aab51c4995f82f29125f3bed

Connect2id server 9.5.1 WAR package: c2id.war

SHA-256: d416d1043d18ef1ecb4920cb58b63114759bdeca91e0870106f52cda014bc10c

Multi-tenant edition

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

SHA-256: a016730031deda10d1c7007695ab7b2ea82ea8c877878d1beb1d872c34975d09

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

SHA-256: b9a605be18ca82eb037e306b5d2c7c737550e6db9c149ad7497991602591e331

Questions?

Contact Connect2id support.

Release notes

9.5.1 (2020-06-22)

Resolved issues

Replaces the BASE64 Apache Commons Codec with the BASE64 codec from the Nimbus JOSE+JWT library to prevent an unchecked IllegalArgumentException exception due to illegal chars in a submitted authorisation code (issue server/574, common/61).
Restores accepting client_secret_jwt and private_key_jwt client authentication JWTs for the token revocation endpoint where the audience is set to the token endpoint URI, removed in Connect2id server v8.0. This rollback is done to preserve backward compatibility with existing clients. New clients should set the authentication JWT "aud" (audience) to the exact endpoint URI as future Connect2id server releases may stop accepting the issuer URI or the token endpoint URI for security reasons (issue server/573).
Logs the exception message for OP6412 when client authentication at the token revocation endpoint fails (issue server/570).
Exports public EdDSA keys from the server JWK set to /jwks.json (issue server/568).

Dependency changes

Updates to com.nimbusds:common:2.38.1
Updates to com.nimbusds:oidc-session-store:13.4.2
Updates to com.nimbusds:jgroups-dynamodb-ping:1.2.4

FAPI certification of Connect2id server 9.5

2020-05-27

The current Connect2id server release was tested in a online deployment against the FAPI certification suite (v4.0.1) and the results are now published on the OpenID Foundation certifications page, in the FAPI section.

The test suite has two modes - one for clients authenticating with private_key_jwt and another for clients authenticating with self_signed_tls_client_auth (mTLS). You you are developing a client application we suggest using the mTLS method because it's typically easier to setup.

If you're developing a deployment that needs to conform to the FAPI security standard we recommend you run the FAPI certification tests against it to make sure something is not accidentally missed out. The tests can be run for free. A fee is required only if you need to publish them and obtain a certificate from the OpenID Foundation.

The FAPI checklist has instructions how to setup a Connect2id server deployment for FAPI.

Next Previous