Products » Connect2id server » Documentation » Integration »

JWT bearer assertion grant handler SPI

1. Introduction

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

Typical use cases:

  • Enable a client that has an existing trust relationship with the Connect2id server to obtain an access token without having to go through the usual user-approval step. The client submits a self-issued JWT, which is secured with an HMAC using the client_secret as a key, or signed with a client RSA or EC keys registered with the Connect2id server.

  • Bridge identities and OAuth authorisations from one security domain to another. For example, to access protected resources in the IT system of another department or of a partner / customer / application provider. The JWT grants would typically be issued by an Identity Provider or Secure Token Service (STS) that is recognised across the participating domains. The JWT itself would typically be signed with an RSA or EC key that belongs to the issuer.

2. JWT bearer grant handler SPIs

The Connect2id server allows enterprises to apply arbitrary authorisation and business logic to JWT assertion grants, in order to determine the properties of the issued tokens (scope, audience, expiration, etc).

This is achieved by means of two flexible 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);

  • The clients can act on the behalf of another subject (an end-user) or on their 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;

  • Permit issue of an OpenID Connect ID token (not covered by the JWT grant spec).

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 OP 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 protected with the client_secret or signed with a registered RSA or EC key; unsecured (plain) or JWE assertions will be 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 token scope 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/self-issued-jwt-bearer-grant-handler

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).

### ### OAuth 2.0 JWT bearer (self-issued) grant handler configuration ### ###

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


### Access token settings ###

# The access token lifetime in seconds.
op.grantHandler.selfIssuedJWTBearer.accessToken.lifetime=300

# The access token encoding:
#
#     * 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.
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 licence.

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 (IdP) or Secure Token Service (STS), in order 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 will be rejected.
  4. The handler is free to determine how the JWT security (HMAC or signature) is to be verified; for this purpose it should keep a copy of the issuer's public keys 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.