Connect2id server 7.14 supports encrypted request objects

2019-07-16

We are delighted to announce support for encrypted request objects (JARs) in Connect2id server 7.14.

1. Encrypted request objects

OAuth 2.0 clients and OpenID relying parties can now submit authorisation requests to the server which parameters are kept confidential from the browser and end-user. The authorisation requests can be directly encrypted with JSON Web Encryption (JWE), or after signing them with JWS.

1.1 JWE algorithms

The following standard JWE algorithms are supported:

  • RSA encryption with RSA-OAEP-256, RSA-OAEP and RSA1_5. Note that use of RSA-PKCS1 v1.5 is no longer recommended and RSA-OAEP-256 should be used instead of RSA-OAEP.

  • ECDH encryption with ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW and ECDH-ES+A256KW.

  • AES 128, 192 and 256 bit encryption (dir) with a symmetric key derived from the client secret.

Two new configuration properties were introduced to set the enabled JWE algorithms and content encryption methods:

If the two configuration properties aren't set the Connect2id server will not accept encrypted request objects.

1.2 Server JWK set

If you intend to support public key encrypted request objects update the server JWK set to include the required RSA and EC encryption keys.

The public encryption keys will be published together with the public signing keys (for JWT validation), so clients that intend to submit RSA or ECDH encrypted authorisation requests can download them.

The server JWK set generator was updated to support creation and rotation of RSA and EC (P-256, P-384 and P-521 curve) encryption keys (v1.9).

Example EC key pair with P-256 curve marked for encryption use:

{
  "kty" : "EC",
  "crv" : "P-256",
  "use" : "enc",
  "kid" : "1yFA",
  "x"   : "_-aKZeuwWDv4v89dPGdKtpOuOepc_0qDZDhcv3omzX0",
  "y"   : "Gc5b7muOqbi4QvYJO24a4IqQoOY1pPM69DcpI605Vmw",
  "d"   : "lFj2hl_0MDs7D3yyTgU6LedcJ7NUZAs6noGzhZszsRA"
}

If only direct (dir) AES encryption based on client secrets is going to be used there is no need to generate and publish public RSA and EC encryption keys.

1.3 Client registration

Clients that intend to use encrypted request objects should declare that in their registration. Clients may also submit encrypted requests without explicitly registering for that, however, the registration gives them the opportunity to have the JWE algorithm parameters checked by the server.

Example client registration for RSA-OAEP-256 public key encryption with A128GCM content encryption:

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_encryption_alg" : "RSA-OAEP-256",
  "request_object_encryption_enc" : "A128GCM"
}

Example client registration for dir AES 128 bit encryption with a key derived from the client secret.

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_encryption_alg" : "dir",
  "request_object_encryption_enc" : "A128GCM"
}

1.4 Making encrypted requests

In order to submit an encrypted request object the OAuth 2.0 client needs to download the server JWK set and extract a public encryption keys from it that matches the desired JWE algorithm.

The request parameters are then encoded as claims into a JWT which is encrypted.

The following example using the open source OAuth 2.0 / OpenID Connect SDK that we maintain for the community shows how to do that, starting from the OpenID provider URL to discover all necessary endpoints and parameters.

import java.net.URI;
import java.util.List;
import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.*;
import com.nimbusds.jose.jwk.*;
import com.nimbusds.jwt.*;
import com.nimbusds.oauth2.sdk.*;
import com.nimbusds.oauth2.sdk.client.*;
import com.nimbusds.oauth2.sdk.http.*;
import com.nimbusds.oauth2.sdk.id.*;
import com.nimbusds.oauth2.sdk.token.*;
import com.nimbusds.openid.connect.sdk.*;
import com.nimbusds.openid.connect.sdk.op.*;

// Need OP issuer URL and access token for the registration as minimum
Issuer opIssuer = new Issuer("https://demo.c2id.com/c2id");
BearerAccessToken regEndpointToken = new BearerAccessToken("ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6");

// Download OpenID provider metadata and JWK set
OIDCProviderMetadata opMetadata = OIDCProviderMetadata.resolve(opIssuer);
JWKSet opJWKSet = JWKSet.load(opMetadata.getJWKSetURI().toURL());

// Will use RSA-OAEP-256 and A128GCM encryption
assert opMetadata.getRequestObjectJWEAlgs().contains(JWEAlgorithm.RSA_OAEP_256);
assert opMetadata.getRequestObjectJWEEncs().contains(EncryptionMethod.A128GCM);

// Register client
ClientMetadata clientMetadata = new ClientMetadata();
clientMetadata.setRedirectionURI(URI.create("https://example.com/cb"));
clientMetadata.setRequestObjectJWEAlg(JWEAlgorithm.RSA_OAEP_256);
clientMetadata.setRequestObjectJWEEnc(EncryptionMethod.A128GCM);
clientMetadata.applyDefaults();

HTTPResponse httpResponse = new ClientRegistrationRequest(
    opMetadata.getRegistrationEndpointURI(),
    clientMetadata,
    regEndpointToken)
    .toHTTPRequest()
    .send();

ClientRegistrationResponse regResponse = ClientRegistrationResponse.parse(httpResponse);

if (! regResponse.indicatesSuccess()) {
    System.err.println(regResponse.toErrorResponse().getErrorObject());
    return;
}

ClientInformation clientInfo = regResponse.toSuccessResponse().getClientInformation();

assert clientInfo.getMetadata().getRequestObjectJWEAlg().equals(JWEAlgorithm.RSA_OAEP_256);
assert clientInfo.getMetadata().getRequestObjectJWEEnc().equals(EncryptionMethod.A128GCM);

// Select public RSA encryption key from OP JWK set
List<JWK> rsaJWKs = new JWKSelector(new JWKMatcher.Builder()
    .keyType(KeyType.RSA)
    .keyUse(KeyUse.ENCRYPTION)
    .build())
    .select(opJWKSet);

if (rsaJWKs.isEmpty()) {
    System.err.println("No RSA encryption key(s) found in OP JWK set");
    return;
}

// Create encrypted OpenID auth request
RSAKey rsaJWK = (RSAKey)rsaJWKs.get(0); // use the first encryption key

EncryptedJWT jar = new EncryptedJWT(
    new JWEHeader.Builder(
        clientInfo.getMetadata().getRequestObjectJWEAlg(),
        clientInfo.getMetadata().getRequestObjectJWEEnc())
        .keyID(rsaJWK.getKeyID())
        .build(),
    new AuthenticationRequest.Builder(
        new ResponseType("code"),
        new Scope("openid"),
        clientInfo.getID(),
        clientInfo.getMetadata().getRedirectionURI())
        .state(new State())
        .build()
        .toJWTClaimsSet());
jar.encrypt(new RSAEncrypter(rsaJWK));

AuthenticationRequest authRequest = new AuthenticationRequest.Builder(jar)
    .endpointURI(opMetadata.getAuthorizationEndpointURI())
    .build();

// Output the OpenID auth request
System.out.println(authRequest.toURI());

Learn more about request objects and their use in our excellent article.

2. Other features

The Connect2id server SDK was updated to v4.5 and now exposes an additional method in the ClaimsSourceRequestContext to find out how the sourced OpenID claims are going to be delivered - at the UserInfo endpoint or included in the ID token.

3. Resolved issues

The 7.14 release fixes a number of bugs related to request object processing, also a significant bug that prevented correct loading of JWK sets configured via the "jose.jwkSet" Java system property. Deployments that use this method to configure the server keys (instead of the regular WEB-INF/jwkSet.json) should update to 7.14.

There is more information in the release notes below.

Download

To download a ZIP package of Connect2id server 7.14:

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

SHA-256: b4ce85678ee218e615aba0198d0d7649551887dcaa5a7f82e538f836caf3114a

As WAR package only:

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

SHA-256: c58b40906c6baa8e3369b2a7687fcbd02b20aedb4cabae64807984352db108e0

Questions?

Contact Connect2id support.

Release notes

7.14 (2019-07-15)

General

  • Support for encrypted (JWE) request objects passed with the optional OAuth 2.0 request or request_uri authorisation request parameter. Supported are RSA (RSA-OAEP-256, RSA-OAEP, RSA1_5) and ECDH (ECDH-ES, ECDH-ES+A128KW, ECDH-ES+A192KW, ECDH-ES+A256KW) public key encryption as well as shared key encryption (dir) with an AES key derived from the client's secret.

    Clients can obtain the public encryption keys (with use=enc) from the Connect2id server JWK set endpoint.

    Clients must include their client_id as top-level authorisation request parameter when submitting request objects encrypted with an AES key derived from the client's secret, to enable the Connect2id server to lookup the secret.

    The JWK set generator for the Connect2id server was updated to support public encryption keys, see https://bitbucket.org/connect2id/server-jwkset-gen

    Processing of encrypted request objects conforms with the "OpenID Connect 1.0" and "The OAuth 2.0 Authorization Framework: JWT Secured Authorization Request (JAR)" (draft-ietf-oauth-jwsreq-19) specifications.

Configuration

  • /WEB-INF/jwkSet.json

    • Includes public RSA (2048 bit) and EC (P-256, P-384 and P-521) JSON Web Keys (JWK) with key use set to encryption (use=enc) for OAuth 2.0 clients to encrypt request objects to the Connect2id server. The presence of public encryption JWKs in the set is optional. Rotation is supported by prefixing new public encryption keys to the set (clients should use the first encryption key that matches the desired JWE algorithm).

  • /WEB-INF/oidcProvider.properties

    • op.authz.requestJWEAlgs -- New optional configuration property listing the accepted JWE algorithms for encrypted OAuth 2.0 authorisation requests passed with the optional request_uri or request parameter. The default value is none.

      The following standard JWE algorithms are supported:

      • RSA-OAEP-256
      • RSA-OAEP (use no longer recommended)
      • RSA1_5 (use no longer recommended)
      • ECDH-ES
      • ECDH-ES+A128KW
      • ECDH-ES+A192KW
      • ECDH-ES+A256KW
      • dir

    • op.authz.requestJWEEncs -- New optional configuration property listing the accepted JWE content encryption methods for encrypted OAuth 2.0 authorisation requests passed with the optional request_uri or request parameter. The default value is none.

      The following standard JWE methods are supported:

      • A128CBC-HS256
      • A192CBC-HS384
      • A256CBC-HS512
      • A128GCM
      • A192GCM
      • A256GCM

SPI

  • com.nimbusds.openid.connect.provider.spi.claims.AdvancedClaimsSource

    • Adds a new getClaimsTransport() method to the ClaimsSourceRequestContext to indicate how the OpenID claims are retrieved by the relying party. Returns "USERINFO" for the UserInfo endpoint, "ID_TOKEN" for including the claims in the issued ID token, and null if not applicable (the claims source SPI is invoked for another purpose, for example in a TokenEncoderContext).

Resolved issues

  • Fixes a bug which prevented loading of Connect2id server keys overridden or passed via the "jose.jwkSet" Java system property. Deployments that rely on loading the server JWK set via the "jose.jwkSet" Java system property must upgrade. The bug did not affect the multi-tenant Connect2id server edition (issue server/471).

  • OAuth 2.0 clients not explicitly registered for "request_object_signing_alg" must be able to use any supported JWS algorithm for signed request objects (JAR), provided the client has registered the necessary key material (public key or client secret) (issue server/469).

  • Remote JWK set (jwks_uri) sourcing errors when processing signed request objects should result in invalid_request_object error, not HTTP 500 (issue server/474).

  • When processing signed request objects a failed client JWK to Java key conversion should result in invalid_request_object error, not HTTP 500.

  • When serving UserInfo requests the "openid" scope value becomes required for the access tokens. Previously the UserInfo endpoint only checked that the access token permitted release of one or more OpenID claims. The OpenID scope values "profile", "email", "address" and "phone" will continue to be ignored in order to comply with data minimisation principles (issue server/473).

  • Updates the SQL DB connector to output a more detailed stack trace when parsing a corrupt JSON field in a SQL record.

Dependency changes

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

  • Upgrades to com.nimbusds:nimbus-jose-jwt:7.4

  • Updates to com.nimbusds:nimbus-jwkset-loader:4.2

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

  • Updates to com.nimbusds:infinispan-cachestore-sql:3.1.3

Connect2id server 7.13

2019-07-04

This is a mini update to the Connect2id server for OpenID Connect and OAuth 2.0.

Check the release notes for more information.

Download

To download a ZIP package of Connect2id server 7.13:

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

SHA-256: 8c31a2a41cd659b0c83eac89f0d4177eb889f694b118c5edb0936a13c8c7625b

As WAR package only:

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

SHA-256: 7c474253393ae6e66fdae77c3919af6338842892fa68db1c8ddeb5580d1d5510

Questions?

Contact Connect2id support.

Release notes

7.13 (2019-06-25)

Configuration

  • /WEB-INF/infinispan--redis-.xml

    • Upgrades the Redis store configuration XML schema to support two classes of store connectors - a simple connector supporting only load / store operations and an extended connector also supporting bulk operations.

Web API

  • /tenants/rest/v1/{tid}/metadata

    • New resource for storing arbitrary metadata (as JSON object) for a tenant. Supports GET and PUT. Available on the multitenant edition of the Connect2id server.

SPI

  • com.nimbusds.openid.connect.provider.spi.tokens.TokenCodecContext

    • Provides a JWSVerifier in the context of the IdentifierAccessTokenCodec and SelfContainedAccessTokenClaimsCodec SPIs. Can be used to validate the JSON Web Signature (JWS) of custom hybrid access tokens (identifier-based access token encoded in a JWT with metadata) or custom secured fields in a token. Requires version 4.4 of the Connect2id server SDK.

Resolved issues

  • Works around an Infinispan issue which omitted objects in bulk retrieval operations in stateless deployments with a Redis cache and an underlying persisting database (SQL, LDAP). The issue affected listing of client registrations, authorisation records and tenants (in the multitenant edition) via the Connect2id server web APIs (issue server/467).

Dependency changes

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

  • Updates to com.nimbusds:tenant-manager:3.2.1

  • Updates to com.nimbusds:tenant-registry:4.1

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

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

  • Updates to com.nimbusds:common:2.34

  • Upgrades to com.nimbusds:infinispan-cachestore-common:2.4

  • Upgrades to com.nimbusds:infinispan-cachestore-redis:9.2.7

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