Skip to content
Connect2id

JWT bearer assertion grant handler SPI

1. Overview

Clients can use JSON Web Token (JWT) assertions to request an access token (and optionally an ID token) from the Connect2id server. This use of JWTs as OAuth 2.0 authorisation grants is specified in RFC 7523.

Typical use cases:

  • Enable a client, for example a trusted backend service acting on a user’s behalf, to obtain an access token. The client submits a self-issued JWT, which is secured with an HMAC computed from the client_secret, or signed with a RSA or EC key, with the corresponding public key made available in the jwks or jwks_uri client metadata.

  • Enable a client to use a JWT minted by a third party trusted by the Connect2id server, for example a JWT from an Identity Provider or Security Token Service (STS) in another trusted security domain, to obtain an access token. The client submits a third-party issued JWT, which can be verified with a public RSA or EC key made available by the issuer.

2. JWT bearer grant handler SPIs

The Connect2id server supports customised processing of JWT assertion grants, in order to determine the properties of the issued tokens (scope, audience, expiration, etc).

This is achieved by means of two plugin interfaces (SPI) – one for handling self-issued JWT assertions and another for handling third-party (Security Token Service, or STS) assertions.

Features of the JWT bearer grant handlers:

  • Support JWT assertions that are issued by the client itself (self-issued) or by a third party (Security Token Service);

  • A client can act on the behalf of another subject (an end-user) or on its own behalf;

  • Client authentication is optional. If present, it is independent and orthogonal from the JWT grant. A client can authenticate explicitly with one of the standard methods, such as private_key_jwt, or implicitly, using the JWT assertion itself;

  • Support issue of an OpenID Connect ID token.

If the Connect2id server detects an SPI implementation it will log its loading under OP7106.

INFO main MAIN - [OP7106] Loaded and initialized urn:ietf:params:oauth:grant-type:jwt-bearer grant handler com.nimbusds.openid.connect.provider.spi.grants.jwt.selfissued.handler.SimpleSelfIssuedJWTGrantHandler

2.1 Self-issued JWT bearer grant handler

This grant handler SPI is intended for clients which are registered with the Connect2id server and are themselves the issuers of the JWT assertions.

Prerequisites:

  1. The client must be registered for the JWT bearer grant urn:ietf:params:oauth:grant-type:jwt-bearer.
  2. The JWT issuer must match the client_id.
  3. The JWT audience must match the token endpoint URI or the Connect2id server issuer URI.
  4. The JWT must be within the validity time window, established by the exp claim and the optional nbf claim.
  5. The JWT must be HMAC secured with the client_secret or signed with a registered RSA or EC key; unsecured (plain) or JWE assertions are rejected.
  6. Explicit client authentication with the token request (using client_secret_ basic, etc) is optional, as the JWT assertion itself can authenticate the client.

To implement a grant handler for JWT assertions issued by the client, use the SelfIssuedJWTGrantHandler SPI.

2.1.1 Default handler

The Connect2id server provides a default JWT grant handler for self-issued assertions, where:

  • The subject (sub) of the access token to issue is taken from the sub claim of the JWT grant.

  • The scope of the access token is bounded by the registered scope values for the client. If no scope values are registered for the requesting client an OAuth 2.0 invalid_scope error is returned.

Git repohttps://bitbucket.org/connect2id/grant-handlers

The default handler configuration is found in WEB-INF/selfIssuedJWTBearerHandler.properties and is concerned with setting of access token properties (lifetime, encoding, encryption flag and audience list).

# Enables / disables the grant handler. Disabled (false) by default.
op.grantHandler.selfIssuedJWTBearer.enable=true


### Access token ###

# The access token lifetime, in seconds. If zero, blank or omitted the default
# access token lifetime configured by "authzStore.accessToken.defaultLifetime"
# applies.
op.grantHandler.selfIssuedJWTBearer.accessToken.lifetime=

# The access token encoding. The default value is SELF_CONTAINED.
#
# Supported encodings:
#
#     * IDENTIFIER -- The access token is a secure identifier. The associated
#       authorisation is looked up by a call to the Connect2id server token
#       introspection endpoint.
#     * SELF_CONTAINED -- Self-contained access token. The associated
#       authorisation is encoded in the access token itself, as a signed and
#       optionally encrypted JSON Web Token (JWT). Can also be looked up by a
#       call to the Connect2id server token introspection endpoint.
#
op.grantHandler.selfIssuedJWTBearer.accessToken.encoding=SELF_CONTAINED

# If true enables additional encryption of self-contained (JWT-encoded) access
# tokens. Disabled (false) by default.
op.grantHandler.selfIssuedJWTBearer.accessToken.encrypt=false

# Optional audience for the access tokens, as comma and / or space separated
# list of values.
op.grantHandler.selfIssuedJWTBearer.accessToken.audienceList=

# Names of client metadata fields to include in the optional access token
# "data" field, empty set if none. To specify a member within a field that is a
# JSON object member use dot (.) notation.
op.grantHandler.selfIssuedJWTBearer.accessToken.includeClientMetadataFields=

Any configuration file property can be overridden by setting a system-wide property with the same key, e.g. by using the optional -D argument at JVM startup:

-Dop.grantHandler.selfIssuedJWTBearer.enable=false

The default handler doesn’t support issue of ID tokens (which is outside the scope of RFC 7523), but may be extended to do so. Its source code is freely available under an Apache 2.0 license.

2.2 Third-party issued JWT bearer grant handler

This grant handler SPI is intended for clients which submit JWT assertions issued by a third party Identity Provider or Security Token Service (STS), to obtain access tokens for protected resources (web APIs) managed by the Connect2id server.

Prerequisites:

  1. The JWT audience must match the token endpoint URI or the OP issuer URI.
  2. The JWT must be within the validity time window, established by the exp claim and the optional nbf claim.
  3. The JWT must be JWS-secured (with an HMAC or signature); the Connect2id server will only ensure such protection is present, the handler itself must verify it; unsecured (plain) or JWE assertions are rejected.
  4. The handler is free to determine how the JWT security (HMAC or signature) is to be verified; for this purpose it should be provisioned with the issuer’s public JWK set, as URL or directly, in order be able to validate the received JWT assertions.
  5. The handler is also free to determine how other claims included in the JWT are to be validated and processed.
  6. If the JWT grant is found valid, the handler must resolve the client_id which must be registered with the Connect2id server. If no explicit client authentication is provided (see below), the handler may use a previously agreed upon JWT claim to establish the client_id.

Important: Explicit client authentication with the token request (using client_secret_ basic, etc) is recommended if the JWT assertion by itself is not sufficient to authenticate the client.

To implement a JWT grant handler for assertions issued by a third party, use the ThirdPartyJWTGrantHandler SPI.

The ServiceContext interface provided at SPI initialisation time can be used to verify a resolved client_id and obtain registered client metadata.