Blog »

Connect2id server 12.16 ships with a new plugin for handling token exchange (RFC 8693)

2022-08-15

This Connect2id server release ships a new plugin for the token exchange (RFC 8693) grant handler SPI introduced in v12.15 last month. The plugin follows the web hook pattern of the existing password and client credentials grant handler plugins that delegate the authorisation to a web service.

The new token exchange plugin

The job of a web service handling a token exchange grant is to determine whether the received subject_token is eligible for exchange and if it is return the subject, scope and other optional properties of the new access token which the Connect2id server will mint and return to the client in the token response.

A web service handling a token exchange grant can base its authorisation decisions on the the following inputs:

  • The claims of the verified subject token and optional actor token (if the latter is accepted or required);

  • The requested token scope (if any) and other parameters;

  • The client ID and selected client metadata.

Example request to the grant handler service demonstrating the plugin web API:

POST /token-exchange-grant-handler HTTP/1.1
Authorization: Bearer ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6
Content-Type: application/json
Issuer: https://c2id.com

{
  "subject_token"      : "Eexungahcaetaizoh7ingait3Ur9ya1b",
  "subject_token_type" : "urn:ietf:params:oauth:token-type:access_token",
  "scope"              : [ "https://api.example.com/get-customer-address" ],
  "client"             : { "client_id"        : "123",
                           "confidential"     : true,
                           "application_type" : "web" }
}

Example response to the Connect2id server for an eligible subject token:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "sub"               : "164476e0-5c10-4cf0-bf75-b30fec2ba925",
  "issued_token_type" : "urn:ietf:params:oauth:token-type:access_token",
  "scope"             : [ "https://api.example.com/get-customer-address" ]
}

Example response for an invalid subject token:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error"             : "invalid_request",
  "error_description" : "Invalid subject token"
}

The token exchange plugin has a number of configurations that deployments can use to filter and pre-process the grants prior to invocation of the web service:

  • Specify the accepted subject and actor token types and reject all others with an invalid_request error.

  • Perform local or remote RFC 7662 compliant introspection of the subject token as an access token.

  • Perform signature and expiration validation of the subject token as a signed JWT.

Upgraded web-based password and client credentials grant handler plugins

The token exchange grant handler plugin together with the other web-based plugins for the password and the client credentials grants are now consolidated in a single JAR which project can be found here:

https://bitbucket.org/connect2id/grant-handlers-web/

The source code is licensed under the open source Apache 2.0 license and can be freely modified.

The web-based password and client credentials grant handlers received several upgrades:

  • The ability to handle custom token request parameters.

  • New configuration property to select which client metadata parameters to pass on in requests to the web service.

  • Requests to the web service now include the OpenID provider / OAuth 2.0 authorisation server issuer URL, to enable tenant specific handling of grants in multi-tenant Connect2id server deployments.

You can find detailed information about all changes in Connect2id server 12.16 in the notes below.

Download 12.16

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: 774f2865eff2fded264155778275f9761a36ff1662f1aae6a60a63931178dd45

Connect2id server 12.16 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 54414e5b164b7de0a871c1797e0bc7d2e1f2224cb734bb6bad9526e766f89b78

Multi-tenant edition

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

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

SHA-256: 774f2865eff2fded264155778275f9761a36ff1662f1aae6a60a63931178dd45

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

GPG signature: c2id-multi-tenant.war.asc

SHA-256: 70d525f52bd16030193292e1d742a155c048b592514e87e24548619c7f6210ab

Questions?

If you have technical questions about this new release contact Connect2id support. To purchase a production license for the Connect2id server, renew or upgrade your support and updates subscription, email our sales.

Release notes

12.16 (2022-08-12)

Summary

  • Adds new plugin for handling OAuth 2.0 token exchange (RFC 8693) grants that passes processing of the grant authorisation to an external web service (web hook). The plugin implements the TokenExchangeGrantHandler SPI introduced in Connect2id server 12.14.

    Features:

    • Supports arbitrary "subject_token" and "actor_token" types.

    • The acceptable "subject_token", "actor_token" and requested token types are configurable.

    • Optional automatic introspection of the received "subject_token" of type access token. Calls upon the internal Connect2id server introspection for access tokens that are locally issued, or one or more configured token introspection endpoints compliant with RFC 7662.

    • Optional automatic JWT verification of the received "subject_token" of type JWT, access token or ID token. The JWT signature is verified using a set of JWKs at one or more configured URLs.

    • Received "subject_token" and "actor_token" instances can also be passed in their original form for verification by the web service itself.

    • Supports passing of selected client metadata parameters to the web service, in addition to the client_id and confidential status, to be used as inputs in the authorisation decision. The "scope" and "data" client metadata fields are included by default.

    • Supports setting of HTTP connect and read timeouts, for the underlying web service, the configured token introspection endpoints and JWK set URLs.

  • Replaces the existing plugin for handling OAuth 2.0 client credentials grants at an external web service (web hook) with a new one that enables configuration of the client metadata fields to pass to the handler. Also supports multi-tenant operation.

  • Replaces the existing plugin for handling OAuth 2.0 resource own password credentials grants at an external web service (web hook) with a new one that enables configuration of the client metadata fields to pass to the handler. Also supports multi-tenant operation.

Configuration

  • /WEB-INF/tokenExchangeGrantHandlerWebAPI.properties -- New configuration file for the new web-based token exchange grant handler, containing the default configuration properties. They can be selectively overridden with Java system properties.

  • /WEB-INF/clientGrantHandlerWebAPI.properties

    • op.grantHandler.clientCredentials.webAPI.customParams -- New optional configuration property to list the names of custom token request parameters to include as top-level members in the handler request JSON object.

    • op.grantHandler.clientCredentials.webAPI.clientMetadata -- New optional configuration property to list the names of client metadata fields to include in the "client" JSON object which is part of handler request. If not specified the following client metadata fields are included by default: "scope", "application_type", "sector_identifier_uri", "subject_type", "default_max_age", "require_auth_time", "default_acr_values", "data"

  • /WEB-INF/passwordGrantHandlerWebAPI.properties

    • op.grantHandler.clientCredentials.webAPI.customParams -- New optional configuration property to list the names of custom token request parameters to include as top-level members in the handler request JSON object.

    • op.grantHandler.clientCredentials.webAPI.clientMetadata -- New optional configuration property to list the names of client metadata fields to include in the "client" JSON object which is part of handler request. If not specified the following client metadata fields are included by default: "scope", "application_type", "sector_identifier_uri", "subject_type", "default_max_age", "require_auth_time", "default_acr_values", "data".

Web API

  • /authz-sessions/rest/v3/

    • Designates the "invalid_target" OAuth 2.0 error code, defined in RFC 8707, as a standard acceptable code to indicate an error condition during end-user authentication / consent. Deployments that use this error code are no longer required to list it in the op.authz. customErrorCodes configuration.

SPI

  • Upgrades the Connect2id server SDK to com.nimbusds:c2id-server-sdk:4.51

    • Adds DefaultTokenIntrospectionResponseComposer class.

    • Adds DefaultTokenRequestParameters class.

Resolved issues

  • Updates the systemPropertiesURL configuration property to support AWS S3 URLs in the new style virtual format (issue server/773).

Dependency changes

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

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

  • Adds com.nimbusds:oauth-grant-handlers-web:1.0

  • Removes com.nimbusds:oauth-password-grant-web-api:1.5

  • Updates to com.nimbusds:oauth-client-grant-handler:2.0.3

  • Updates to com.nimbusds:oauth-jwt-self-issued-grant-handler:1.1.1

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

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

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

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

  • Updates to com.nimbusds:c2id-server-jwkset:1.26

  • Updates to com.nimbusds:infinispan-cachestore-common:2.4.1

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

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

  • Updates to com.nimbusds:infinispan-cachestore-dynamodb:4.2.1

  • Updates to org.postgresql:postgresql:42.4.1

  • Updates to com.nimbusds:c2id-server-property-source:1.1

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

  • Updates to com.amazonaws:aws-java-sdk-*:1.12.264

  • Updates to DropWizard Metrics 4.2.10

  • Updates to Log4j 2.18.0