Connect2id server 7.12.1

2019-06-05

This is a maintenance release of the Connect2id server. Fixes a bug in request object error reporting and a bug in the session store which affected the correct keeping of max idle time. Also updates the session store and the DynamoDB connector for better memory efficiency when purging large numbers of expired sessions.

Check the release notes for more information.

Download

To download a ZIP package of Connect2id server 7.12.1:

https://connect2id.com/assets/products/server/download/7.12.1/Connect2id-server.zip

SHA-256: 8a2743ae1e67249a689306ef2b660fb8f0adb902f31e502757a77243732bc346

As WAR package only:

https://connect2id.com/assets/products/server/download/7.12.1/c2id.war

SHA-256: f97a7a2cbc196e09d06f2351371b4af92191ac3a0ad9b12d4d3b0048a601c4ae

Questions?

Contact Connect2id support.

Release notes

7.12.1 (2019-06-05)

Configuration

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

    • Upgrades the DynamoDB store configuration schema to v1.6 which introduces a new optional "purge-limit" attribute. It limits the number of expired entries to purge during a run of the expired entry reaper task. The default value is -1 (no limit).

    • Adds new dymamodb.purgeLimit.sessionStore.sessionMap Java system property to set the purge limit for subject sessions persisted to DynamoDB. The default value is -1 (no limit).

Resolved issues

  • A JAR request for a client not registered for JAR should produce an invalid_request_object error with "The client isn't registered for request objects" message (issue server/461).

  • Fixes a session store bug which caused the last access timestamp for subject sessions to not update and the session to expire prematurely if max idle is set. The bug affected Connect2id server deployments in stateless cluster mode (DynamoDB and Redis) (issue session store/78).

  • Updates the session store task for purging orphaned subject keys (subject index entries) to conserve memory (issue session store/79).

  • Updates the expired entry purge task of the DynamoDB store to conserve memory (issue dynamodb/13).

Dependency changes

  • Updates to com.nimbusds:oidc-session-store:11.2

  • Updates to Infinispan 9.4.14.Final.

  • Upgrades to com.nimbusds:infinispan-cachestore-dynamodb:3.5

  • Updates to com.unboundid:unboundid-ldapsdk:4.0.11

Connect2id server 7.12 supports request objects in general OAuth 2.0

2019-05-16

The new Connect2id server 7.12 release focuses on request objects. Unsure what they are and when to use them? Check out our freshly published guide.

Request objects with general OAuth 2.0

The concept of JWT-secured authorisation parameters originally appeared as a feature in OpenID Connect called request objects. The extra security guarantees they provide found use in the FAPI profile for OpenBanking and other financial-grade applications.

Request objects can also be useful in the underlying OAuth 2.0 framework and the OAuth working group caught up with its own compatible and more general spec that bears the acronym JAR, for JWT Secured Authorization Request.

The Connect2id server has supported request objects in OpenID authentication requests since version 6.0. This new release makes it possible to use them with plain OAuth 2.0 authorisation requests as well.

New request object configs

These were necessitated by the most recent FAPI spec:

  • op.authz.requireRequestJWTExpiration -- Specifies if received request object JWTs must include an expiration (exp) claim. The default value is false.

  • op.authz.requireAllParamsInRequestJWT -- Specifies if received request JWTs must include all OAuth 2.0 authorisation request parameters. If enabled authorisation requests with unsecured parameters will be rejected with an invalid_request error. The default value is false.

New OpenID Connect error code

OpenID Connect has been missing an error code for indicating the condition when the end-user couldn't be authenticated at a required strength (Authentication Context Class Reference, or ACR). The omission was fixed earlier this month with a new unmet_authentication_requirements error code, which is now understood by the Connect2id server.

The error code spec is not officially published yet, but you can read its XML source in the OpenID Connect repo.

Other updates and fixes

The token endpoint features a new security measure for the OAuth 2.0 authorisation code grant. The Connect2id server will automatically revoke the received code if the client authentication, with a client secret or some other method, is found invalid.

To support migration from deployments with weak 1024 bit RSA keys a new JOSE configuration was added.

A significant bug in the session store was also fixed.

For more information check out the release notes below.

Download

To download a ZIP package of Connect2id server 7.12:

https://connect2id.com/assets/products/server/download/7.12/Connect2id-server.zip

SHA-256: 02976e88e38ff7310be703a48c0669bbd8ab0d9dd9b179d4cc724e0a153446c7

As WAR package only:

https://connect2id.com/assets/products/server/download/7.12/c2id.war

SHA-256: b71d43e9afc5bba8c26d1d10dd25b92049610f06cfaf130fe5572f2fabdb9372

Questions?

Contact Connect2id support.

Release notes

7.12 (2019-05-16)

General

  • Adds support for JWT-secured OAuth 2.0 authorisation requests (draft-ietf-oauth-jwsreq-17). Previously, request objects were only supported in OpenID authentication requests, passed inline via the "request" parameter or by reference via the "request_uri" parameter.

    JWT-secured OAuth 2.0 authorisation requests (including OpenID authentication requests) with the an inlined request object may include only the "request" parameter, with all required and optional parameters present in the JWT.

    Request with a request object passed by URL may include only the "request_uri" and "client_id" parameters, with all required and optional parameters present in the JWT.

    See https://tools.ietf.org/html/draft-ietf-oauth-jwsreq-17

Configuration

  • /WEB-INF/jose.properties

    • Adds new jose.allowWeakKeys configuration property to allow the Connect2id server to be configured with a JWK set that contains weak RSA keys shorter than 2048 bits. May be used to facilitate migration and key roll-over from OpenID providers that use weak RSA keys. If weak RSA keys are allowed and detected in the JWK set, the Connect2id server will log a warning with ID SE1030 at startup. The default value is false.

  • /WEB-INF/oidcProvider.properties

    • Adds new op.authz.requireRequestJWTExpiration configuration property to specify whether received request object JWTs must include an expiration (exp) claim. The default value is false.

      See Financial-grade API - Part 2: Read and Write API Security Profile.

    • Adds new op.authz.requireAllParamsInRequestJWT configuration property to specify whether request JWTs must include all OAuth 2.0 authorisation request parameters. If enabled authorisation requests with unsecured parameters will be rejected with an invalid_request error. The default value is false.

      See Financial-grade API - Part 2: Read and Write API Security Profile.

Web API

  • /token

    • Implements a security measure to revoke the received authorisation code (if valid and not expired) when client authentication at the token endpoint for an authorisation code grant fails.

  • /authz-sessions/rest/v3/

    • Adds support for handling JWT-secured OAuth 2.0 authorisation requests (draft-ietf-oauth-jwsreq-17).

    • Adds support for the new unmet_authentication_requirements OpenID Connect error code, intended to inform the Relying Party that the OpenID provider is unable to authenticate the end-user at the required Authentication Context Class Reference value when requested with an essential "acr" claim. The error code may also be used in other appropriate cases.

      See OpenID Connect Core Unmet Authentication Requirements 1.0.

Resolved issues

  • Fixes a bug in the session store which resulted in closing an active subject (end-user) session when a new session is created and the index for the subject is filled with stale (pending purge) entries up to the configured session quota (sessionStore.quotaPerSubject) (issue session store/77).

  • Trims duplicate text in the error_description of non-redirecting authorisation errors (issue server/449).

Dependency changes

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

  • Updates to com.nimbusds:oauth2-authz-store:11.6

  • Updates to com.nimbusds:oidc-session-store:11.0

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

Request objects in OAuth 2.0 and OpenID Connect

2019-05-15

The request object originally appeared as an OpenID Connect feature to secure parameters in the authentication request from tainting or inspection when the browser of the end-user is sent to the OpenID provider server. OAuth 2.0 recently caught up with its own specification for general use of request objects in authorisation requests. This is a guide when and how to employ them.

Why secure auth requests?

When the end-user browser is sent to the OpenID provider with a regular authentication request its parameters simply get URL-encoded in the query string.

https://c2id.com/login?response_type=code
 &client_id=123
 &scope=openid
 &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb
 &state=obiange2

This means the end-user as well as any malicious XSS injected into the relying party (RP) website can potentially view and modify the request parameters. But for the protocol itself this doesn't represent a security issue. Why?

  • The request parameters are not secret and in the case of scope, claims and state shouldn't convey sensitive information in plain text.

  • If a critical request parameter gets tampered with, the validation and processing that follow, by the OpenID provider or the RP, will detect that and produce an error.

For instance, the OpenID provider checks that the redirect_uri matches a redirection URI registered for the particular client_id, and later, at the token endpoint the client (if confidential) gets authenticated. The state parameter is validated by the RP when it gets passed back with the authorisation response.

Still, there are applications which need OpenID authentication requests with additional security:

  • Authenticity, integrity and non-repudiation of the requested scope and claims, typically for legal purposes.

  • Approval of the request by a third party for compliance with a privacy / personal data collection policy.

  • Keeping the requested scope, claims or a custom parameter confidential from the end-user.

  • In deployments with multiple OpenID providers and dynamic client registration to guard against IdP mix-up attacks.

Moving sensitive request parameters into a JWT

The natural candidate solution for securing the request parameters was the JSON Web Token (JWT). The JWT that carries the parameters is called request object in OpenID Connect.

The request object may include only those parameters deemed sensitive by the application, for example scope and claims, while keeping the rest unprotected, as regular URL-encoded query parameters. Security profiles, such as FAPI for OpenBanking and other financial-grade applications, may require all parameters to be present in the JWT.

Example JWT claims set for an OpenID authentication request:

{
  "response_type" : "code",
  "client_id"     : "123",
  "scope"         : "openid email profile",
  "redirect_uri"  : "https://client.example.com/cb",
  "state"         : "obiange2"
}

By signing the JWT the parameters receive integrity protection and the OpenID provider can assume they originate from the relying party (RP). By applying encryption to the JWT the parameters are made confidential between the RP and OpenID provider.

Passing the request object: by value vs URL

The request object itself can be passed by value in a request parameter, or by reference, in a request_uri parameter.

Passing the request object by URL instead of by value frees it from potential URL size restrictions in browsers.

Example OpenID authentication request where the request object is passed by value:

https://c2id.com/login?response_type=code
 &client_id=123
 &scope=openid
 &request=eyJhbGciOiJSUzI1NiIsImtpZCI6ImsyYmRjIn0.ew0KICJpc3MiOiAiczZCaGRSa...

And by URL:

https://c2id.com/login?response_type=code
 &client_id=123
 &scope=openid
 &request_uri=https%3A%2F%2Fclient.example.com%2Frequest.jwt

Note the presence of the response_type, client_id and scope as query parameters. They are there because of a requirement for the URL query parameters to still parse into a valid OAuth 2.0 authorisation request, with scope=openid to indicate an OpenID authentication request. The scope in the request object supersedes, always, and can include additional scope values.

Support for request objects in OpenID authentication requests has been present in the Connect2id server since version 6.0.

OAuth 2.0 also adopts request objects

Request objects can also be useful in general OAuth 2.0 and the OAuth working group is finalising a specification for that, called JWT Secured Authorization Request (JAR).

The JAR spec relaxes the requirement for the URL query parameters to parse into a valid OAuth 2.0 authorisation request, so clients can send authorisation requests that consist of only the request or request_uri parameter at the top level, with all other parameters going into the JWT:

https://c2id.com/login?request_uri=https%3A%2F%2Fclient.example.com%2Frequest.jwt

General OAuth 2.0 support for request objects was introduced in Connect2id server version 7.12.

How to find out if an AS / OP supports request objects

How can a developer or dynamic client find out if a particular Authorisation server (AS) or OpenID provider (OP) supports requests objects? By checking the following parameters in the published AS / OP metadata:

  • request_parameter_supported -- If true indicates support for passing request objects by value.
  • request_uri_parameter_supported -- If true indicates supports for passing request objects by URL.
  • require_request_uri_registration -- If passing request objects by URL is supported, whether the URLs need to mentioned in the client registration.
  • request_object_signing_alg_values_supported -- If signed request objects are supported, list of the supported JWS algorithms.
  • request_object_encryption_alg_values_supported -- If encrypted request objects are supported, list of the supported JWE algorithms.
  • request_object_encryption_enc_values_supported -- If encrypted request objects are supported, list of the supported JWE methods.

Example server metadata showing support for HMAC-SHA256-protected (JWS algorithm HS256) as well as RSA signed (JWS algorithm RS256) request objects, which the client can pass by value or URI:

{
  "request_parameter_supported"                 : true,
  "request_uri_parameter_supported"             : true,
  "request_object_signing_alg_values_supported" : [ "HS256", "RS256" ]
}

Registering a client for request objects

The JWS and / or JWE algorithms for securing the request object JWTs need to be set in the client's metadata when it's registered with the AS / OP.

Algorithm choice

Choose cryptographic algorithm that's supported by the AS / OP and also minimally appropriate for the required security.

Integrity protection

If nothing else but protection against tampering of the authorisation parameters is required, choose an HMAC based JWS algorithm, such as HS256, HS384 or HS512. The client must then secure the request object JWT with an HMAC computed from the client_secret as key.

Example minimal registration for the code grant with HS256 secured request objects:

POST /c2id/clients HTTP/1.1
Host: demo.c2id.com
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris"              : [ "https://client.example.org/callback" ],
  "request_object_signing_alg" : "HS256"
}

Authenticity, integrity and non-repudiation

If the requirement is to make the request object digitally signed, choose a JWS algorithm from the RSxxx / PSxxx family for RSA-based public key cryptography or from the ESxxx family for EC-based cryptography.

To sign the request objects the client needs to generate a public / private key pair. The client must store the private key securely and will use it to sign the request object JWTs. The AS / OP server needs to have access to the matching public key, in order to check the JWT signatures.

The client has a choice of two methods to make its public key(s) available to the AS / OP:

  • By putting its public keys in JSON Web Key (JWK) set format in the jwks client metadata parameter.

  • By publishing its keys, also in JWK set format, at a URL reachable by the AS / OP, and registering that URL in the jwks_uri client metadata parameter.

Example minimal registration for the code grant with RS256 secured request objects; the AS / OP can get the public client JWK set to validate the RS256 signatures from the given client URL:

POST /c2id/clients HTTP/1.1
Host: demo.c2id.com
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris"              : [ "https://client.example.org/callback" ],
  "jwks_uri"                   : "https://client.example.org/jwks.json",
  "request_object_signing_alg" : "RS256"
}

Confidentiality

To make request parameters confidential, the client needs to encrypt the request object, and register an appropriate JWE algorithm and method for that.

Note that encryption can be applied after JWS signing, to create a nested JWT that ensures the properties of authenticity, integrity and non-repudiation as well as the confidentiality. If the combination or integrity and confidentiality is required, just register the client for JWE encryption, as all standard JWE encryption methods have the cryptographic property of authenticated encryption.

The actual encryption is of two types:

  • Symmetric -- Using the client_secret to derive an AES key that is shared between the client and the AS / OP.

  • Public key -- Encryption to a public RSA or EC key which the AS / OP has made available in its own published JWK set. The URL of the server JWK set can be found out by checking the AS / OP metadata.

Example minimal registration for the code grant with nested (signed and RSA public-key encrypted) request objects:

POST /c2id/clients HTTP/1.1
Host: demo.c2id.com
Content-Type: application/json
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6

{
  "redirect_uris"                 : [ "https://client.example.org/callback" ],
  "jwks_uri"                      : "https://client.example.org/jwks.json",
  "request_object_signing_alg"    : "RS256",
  "request_object_encryption_alg" : "RSA-OAEP-256",
  "request_object_encryption_enc" : "A128GCM"
}

Further reading