Blog »

Connect2id server 6.17 adds support for custom access token codecs, shaping of token introspection

2018-02-26

The latest release of the Connect2id server for OpenID Connect identity provision opens new avenues for customisation. Three new SPIs were added, to enable plug in of alternative token codecs and for shaping of token introspection responses.

Self-contained access token claims codec

An SPI is provided for controlling what claims get included into JWT-encoded access tokens and how they get formatted. Resource servers which expect a particular structure or naming of the claims, such as for the non-standard JWT claims to represent scope or the client to which the token was issued, can benefit from this SPI.

The clear cut codec interface and the helpful base implementation make the job easy.

Identifier-based access token codec

When identifier-based access tokens are needed the Connect2id server generates secure random 128-bit numbers, with extra HMAC protection to detect and log fake tokens upon introspection.

Here also an SPI is provided for plugging in an alternative codec. For instance, to encapsulate the identifier in a signed JWT, along with the issuer URL, expiration time and client certificate confirmation, to provide resource servers in multi-tenant deployments with a hint where to introspect the token, and also allow part of the token validation to be done locally by the resource server, before the introspection call.

{
  "iss" : "https://t1.c2id.com",
  "jti" : "Hoofao7Ve1ohg4chahBee9Xee1ahvaed",
  "exp" : 1519660677,
  "cnf" : { "x5t#S256" : "Shoohie2Pee1ubi9aehai3leg0woidet" }
}

Token introspection

Shaping of token introspection responses is supported to control what token details a resource can see. For example, to limit the introspected scope only to those scope values which the resource server supports. This is can be important for data minimisation in authorisation server deployments with different service providers, or where access tokens can have multiple audiences.

Example introspection response for a token for two resource servers:

{
  "active"     : true,
  "iss"        : "https://c2id.com",
  "scope"      : "https://accounts.xyz/balance https://accounts.xyz/transfer https://ratings.xyz/submit",
  "token_type" : "Bearer",
  "sub"        : "alice"
}

Shaping the response for the https://accounts.xyz service:

{
  "active"     : true,
  "iss"        : "https://c2id.com",
  "scope"      : "https://accounts.xyz/balance https://accounts.xyz/transfer",
  "token_type" : "Bearer",
  "sub"        : "alice"
}

Shaping the response for the https://ratings.xyz service:

{
  "active"     : true,
  "iss"        : "https://c2id.com",
  "scope"      : "https://ratings.xyz/submit",
  "token_type" : "Bearer",
  "sub"        : "alice"
}

Download

To download a ZIP package of Connect2id server 6.17:

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

SHA-256: af37f5b29191178bbda93290b806f95ee495a4cc8a9dad4ce097d87d0918664d

As WAR package only:

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

SHA-256: fd9d057b99580d158c7ef247acda7452f0da319a25871d0ca29ef131305748d1

Questions?

Get in touch with Connect2id support.

Release notes

6.17 (2018-02-26)

Configuration

  • /WEB-INF/authzStore.properties

    • accessToken.allowDirectInspection -- The default setting becomes false (always require the master API token for inspecting access tokens at the /authz-store/rest/v2/inspection endpoint). The change is made to encourage resource servers to use the standard /token/introspect endpoint which requires the introspection request to be authenticated or authorised with an access token.

    • accessToken.selfContainedClaims -- The setting for specifying the JWT claims to include in self-contained access tokens is no longer supported. If such customisation is required this can now be implemented via the SelfContainedAccessTokenClaimsCodec SPI (see below).

Web API

  • No changes

SPI

  • IdentifierAccessTokenCodec -- Adds new optional SPI for customis generation and decoding of identifier-based access tokens. The SPI invocation context provides access to a secure random generator, an HMAC computer, a JWT signer and the OpenID claims source of the Connect2id server.

  • SelfContainedAccessTokenClaimsCodec -- Adds new optional SPI for custom encoding and decoding of JWT claims in self-contained access tokens. The SPI invocation context provides access to a secure random generator, an HMAC computer, a JWT signer and the OpenID claims source of the Connect2id server.

  • TokenIntrospectionResponseComposer -- Adds new optional SPI for custom composition of token introspection (RFC 7662) responses. The SPI invocation context provides access to the OpenID claims source of the Connect2id server and the registered information of the requesting client (for introspection requests with client authentication).

  • IDTokenIssueEventListener -- Updates the SPI method to include EventContext (breaking change from v6.16).

  • AccessTokenIssueEventListener -- Updates the SPI method to include EventContext (breaking change from v6.16).

Resolved Issues

  • Always encrypts issued self-contained (JWT) access tokens when the OpenID relying party is registered for pairwise subject identifiers. This is done to prevent leakage of the underlying subject identifier. Previously the consent logic driving the authorisation session had to explicitly take care of that by setting access_token.encrypt in the consent object to true (issue server/349).

  • Updates logging of client IP in HTTP requests to take into account Forwarded (RFC 7239) and X-Forwarded-For headers set by reverse proxies (issue common/57).

  • Fixes NoSuchMethodError on Dropwizard HealthCheckRegistry shutdown (issue server/341).

  • Logs cause of self-contained (JWT) access token failing inspection.

Dependency Changes

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

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

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

  • Upgrades to com.nimbusds:common:2.22

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

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

  • Upgrades to com.nimbusds:infinispan-cachestore-sql:2.7

  • Upgrades to BouncyCastle 1.59

  • Upgrades to Dropwizard Metrics 3.2.6.

  • Upgrades to com.unboundid:unboundid-ldapsdk:4.0.4

  • Upgrades to Apache Commons Lang 3.7

  • Upgrades to Log4j 2.10.0