Custom token encodings and introspection

The Connect2id server issues access tokens which can be self-contained (JSON Web Token) or identifier-based. Resource servers can validate a JWT locally by checking its digital signature, while for an identifier-based token a call to the introspection endpoint is needed.

Deployments are in most cases fine with the provided access token encodings and introspection output provided by the Connect2id server. If some customisation is necessary the server exposes three helpful Java Service Provider Interfaces (SPI) for that:

• SelfContainedAccessTokenClaimsCodec – for setting the claims structure of the issued JWT-encoded access tokens, omitting or adding claims;
• IdentifierAccessTokenCodec – for generating and encoding / decoding identifier-based access tokens;
• TokenIntrospectionResponseComposer – for shaping token introspection responses.

A context parameter is passed with each call so that the cryptographic facilities (e.g. JWS signer) and the OpenID claims source of the Connect2id server can be accessed if needed.

Self-contained access token claims codec

This SPI determines how a token authorisation is converted to a JWT claims set and vice versa. You can use it to set an alternative claims encoding to the one provided by the Connect2id server.

The SPI is most likely to be needed when the resource servers expect a different name or format for some non-standard JWT claim, such as the claim to represent the token scope or the client to which the token was issued. In that case extend the provided BaseSelfContainedAccessTokenClaimsCodec class.

@Override
public JWTClaimsSet encode(final AccessTokenAuthorization tokenAuthz, final TokenEncoderContext context) {

	// Encode the claims for which we have standard (registered) names
	JWTClaimsSet.Builder builder = new JWTClaimsSet.Builder(super.encode(tokenAuthz, context));

    // client_id
	if (tokenAuthz.getClientID() != null)
		builder.claim("client_id", tokenAuthz.getClientID().getValue());

    // scope
	if (tokenAuthz.getScope() != null)
		builder.claim("scope", tokenAuthz.getScope().toString());

    return builder.build();
}


@Override
public AccessTokenAuthorization decode(final JWTClaimsSet claimsSet, final TokenCodecContext context)
	throws TokenDecodeException {

	// Decode the claims for which we have standard (registered) claims
	MutableAccessTokenAuthorization authz = new MutableAccessTokenAuthorization(super.decode(claimsSet, context));

    String clientID = claimsSet.getStringClaim("client_id");

	if (clientID != null)
		authz.withClientID(new ClientID(clientID));

	String scope = claimsSet.getStringClaim("scope");

	if (scope != null && ! scope.trim().isEmpty())
		authz.withScope(Scope.parse(scope));

	return authz;
}

Note that the default JWT claims codec allows arbitrary custom parameters to be put in the top-level “dat” parameter; i.e. you don’t need to create your own custom SPI implementation to include additional data in the JWT (unless the custom parameters must be top-level members of the JSON object).

Identifier-access token codec

This SPI generates secure random identifiers for access tokens.

The default implementation provided by the Connect2id server produces an 128-bit identifier for each token. The identifier has an extra SHA-256 HMAC protection (truncated to 128 bits) appended to it. During introspection the HMAC enables the codec to detect tokens that aren’t issued by the Connect2id server, causing a suitable warning to get logged and preventing an unneeded database lookup.

The SPI enables plug in of a custom codec. For example, a codec where the identifier is encapsulated 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 happen before the introspection call.

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

Check out this example for an alternative “hybrid” codec.

Token introspection response composer

Resource servers check identifier-based access tokens at the standard token introspection endpoint.

The TokenIntrospectionResponseComposer SPI allows the default response format to be overridden.

One use of that is to respond differently to different resource servers making the same introspection request. For instance, an authorisation server may limit which scopes from a given token are returned for each resource server, to prevent it from learning more about the larger network than is necessary for its operation.

A sample implementation of that can be found in the Connect2id server SDK test suite. Requires the resource server to be registered as a client to the Connect2id server (which is already a prerequisite to inspect tokens), where in the possible scope values that it may see are listed in the “scope” registration field.

Support

The access token SPIs were introduced in Connect2id server v6.17.

If you need assistance, please contact Connect2id support.