Blog »

OAuth 2.0 token exchange (RFC 8693) support in Connect2id server 12.14

2022-07-01

This Connect2id server release introduces support for OAuth 2.0 token exchange (RFC 8693). Deployments can use it to let clients obtain an access token from the token endpoint by presenting a grant (credential) that is also a token.

The ability to utilise tokens as grants can be useful in cases such as:

  • Letting a client obtain tokens for backend services based on a initial access token from a user authorisation in a browser based OAuth flow. The client needs the additional token(s) in order to fulfil a complex operation that involves calls to multiple services / APIs.

  • A client obtaining a local access token using a credential from another domain. This external credential can be another access token, a JWT, a SAML assertion, or something else.

  • Obtaining tokens in a delegation (on-behalf-of) scenario.

  • Obtaining tokens in a impersonation (act-as) scenario.

  • Obtaining tokens for special purposes.

Following the established Connect2id server tradition for handling OAuth 2.0 grants where deployments are given a plugin interface to freely implement their own grant-specific logic and policy, the server receives a new token exchange handler SPI.

The SPI is designed to support arbitrary ingress tokens, in terms of their type, purpose, encoding and cryptographic protection. If the token that the client submits as OAuth grant is a locally issued access token, the Connect2id server will automatically inspect it and make its authorisation details available to the plugin. If the token is issued by another server and the deployment has a policy to accept such tokens the plugin must handle its verification. A future Connect2id server release may add a facility to simplify the task of validating JWTs and OAuth access tokens from other issuers.

If the plugin logic determines that the token exchange is allowed to proceed, it creates a simple object specifying the scope and other properties of the access token to return. The Connect2id server will then use this spec to mint the actual token and return it to the requesting client. In a next release the Connect2id server will receive the capability to support the issue of a refresh token on a token exchange.

You can find more information in the token exchange handler SPI documentation.

This Connect2id server release also took the opportunity to revise the other existing OAuth 2.0 grant handler SPIs. They received a new default method for processing grants that exposes additional token request parameters besides the requested scope; a context object is also added to facilitate the creation of plugins in the multi-tenant edition of the Connect2id server. The client credentials grant handler SPI was additionally updated so that plugins can now support access tokens that give access or include OpenID claims from the provisioned claims source.

Download 12.14

For the signature validation: Public GPG key

Standard Connect2id server edition

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

GPG signature: Connect2id-server.zip.asc

SHA-256: 2ab142228d456e2ff9efec3c9e7ad196062a7d39f0116923c5f1e9d489f46f28

Connect2id server 12.14 WAR package: c2id.war

GPG signature: c2id.war.asc

SHA-256: 1b6a273ff7625bf62d4dc1ae4c6dba06c34a44ff0b91a4c8d317fae8a7c2c223

Multi-tenant edition

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

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

SHA-256: 0fdf5a6fe700f2861d7c74d9a9f0c08e3fae8897c69e36f8046c02e28dbc4007

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

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

SHA-256: f32676fd296eb3ea00da3daa684bbe1b1027a361892b05af0be9f427da9db278

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.14 (2022-06-30)

Summary

  • Support for OAuth 2.0 Token Exchange (RFC 8693). This is an OAuth 2.0 extension that specifies a generic mechanism for clients to obtain an access token in exchange for another token, which type and encoding can be arbitrary and which issuer can be the same OAuth 2.0 authorisation server or another trusted 3rd party token service. This grant also supports impersonation (act-as) and delegation (on-behalf-of) scenarios. See https://datatracker. ietf.org/doc/html/rfc8693

Web API

  • /clients

    • Supports registration of clients for the OAuth 2.0 token exchange grant ("urn:ietf:params:oauth:grant-type:token-exchange"). The clients can be confidential (with authentication credentials) or public.

  • /token

    • Supports the OAuth 2.0 token exchange grant (RFC 8693), identified by the grant_type "urn:ietf:params:oauth:grant-type:token-exchange". Requires a TokenExchangeGrantHandler SPI plugin.

  • /monitor/v1/metrics

    • Adds new tokenEndpoint.tokenExchange.successfulRequests, tokenEndpoint.tokenExchange.invalidClientErrors, tokenEndpoint.tokenExchange.unauthorizedClientErrors, tokenEndpoint.tokenExchange.invalidGrantErrors and tokenEndpoint.tokenExchange.invalidScopeErrors meters for the OAuth 2.0 token exchange grant.

SPI

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

    • TokenExchangeGrantHandler -- New SPI for implementing OAuth 2.0 token exchange (RFC 8693) scenarios. Accepts subject_token and actor_token instances of any token type and issuer. The requested_token_type must be an access token (locally issued). The access token can be of type Bearer, with a client X.509 certificate binding (RFC 8705), or DPoP bound (draft-ietf-oauth-dpop-09). Issue of other types of tokens as well as refresh tokens currently isn't supported.

    • ClientCredentialsGrantHandler -- Adds new processGrant method to the SPI to enable handling of token parameters other than scope and provide access to the configured OP / AS issuer URI (necessary for grant handler plugins in multi-tenant Connect2id server deployments). The old processGrant method is deprecated. The new processGrant method has a default implementation that passed the call to the old deprecated method so existing plugins can continue functioning as they are.

    • ResourceOwnerPasswordCredentialsGrant -- Adds new processGrant method to the SPI to enable handling of token parameters other than scope and provide access to the configured OP / AS issuer URI (necessary for grant handler plugins in multi-tenant Connect2id server deployments). The old processGrant method is deprecated. The new processGrant method has a default implementation that passed the call to the old deprecated method so existing plugins can continue functioning as they are.

    • SelfIssuedJWTGrantHandler -- Adds new processGrant method to the SPI to enable handling of token parameters other than scope and provide access to the configured OP / AS issuer URI (necessary for grant handler plugins in multi-tenant Connect2id server deployments). The old processGrant method is deprecated. The new processGrant method has a default implementation that passed the call to the old deprecated method so existing plugins can continue functioning as they are.

    • ThirdPartyJWTGrantHandler -- Adds new processGrant method to the SPI to enable handling of token parameters other than scope and provide access to the configured OP / AS issuer URI (necessary for grant handler plugins in multi-tenant Connect2id server deployments). The old processGrant method is deprecated. The new processGrant method has a default implementation that passed the call to the old deprecated method so existing plugins can continue functioning as they are.

    • SelfIssuedSAML2GrantHandler -- Adds new processGrant method to the SPI to enable handling of token parameters other than scope and provide access to the configured OP / AS issuer URI (necessary for grant handler plugins in multi-tenant Connect2id server deployments). The old processGrant method is deprecated. The new processGrant method has a default implementation that passed the call to the old deprecated method so existing plugins can continue functioning as they are.

    • ThirdPartySAML2GrantHandler -- Adds new processGrant method to the SPI to enable handling of token parameters other than scope and provide access to the configured OP / AS issuer URI (necessary for grant handler plugins in multi-tenant Connect2id server deployments). The old processGrant method is deprecated. The new processGrant method has a default implementation that passed the call to the old deprecated method so existing plugins can continue functioning as they are.

    • Adds a ClaimsSpec field to the GrantAuthorization class. This enables plugins implementing the ClientCredentialsGrantHandler SPI to authorise OAuth 2.0 clients registered for the client_credentials grant to receive an access token for OpenID claims at the UserInfo endpoint. This also enables the existing Connect2id server feature where authorised OpenID claims specified with the access_token: prefix will be fed into the access token.

Resolved issues

  • Increases the entity size limit of HTTP requests to the client registration endpoint from 20K chars to 250K chars to cater for client registrations with exceptionally large metadata. The entity size limit has been present to prevent DoS attacks in client registration that is open or managed in a way that doesn't enforce a limit on the submitted client metadata (issue server/765).

Dependency changes

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