Skip to content
Connect2id

JWT grant handler

1. Introduction

Clients may 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 a signature using the client RSA or EC keys registered with the Connect2id server.

  • Carry over identities and OAuth authorisations from one security domain into 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 Java Service Provider 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 (client_secret_basic, client_secret_post, client_secret_jwt or 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).

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.

https://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 ### ###

# This file configures the local handler for self-issued (client-issued) JWT
# bearer grants.
#
# See:
#
# 1. https://bitbucket.org/connect2id/self-issued-jwt-bearer-grant-handler
# 2. https://bitbucket.org/connect2id/server-sdk
# 3. http://connect2id.com/products/server/docs/integration/jwt-bearer-grant-handler

# Enables / disables the client credentials grant handler.
op.grantHandler.selfIssuedJWTBearer.enable = true


### Access token settings ###

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

# The default access token encoding. Can be overridden by the individual
# authorisations.
#
#     * IDENTIFIER -- The access token is a secure identifier. The associated
#       authorisation is looked up by a web API call to the authorisation
#       store.
#     * SELF_CONTAINED -- Self-contained access token. The associated
#       authorisation is encoded in the access token itself, as a signed JSON
#       Web Token (JWT). Can also be looked up the a web API call to the
#       authorisation store.
#
op.grantHandler.selfIssuedJWTBearer.accessToken.encoding = SELF_CONTAINED

# Enables / disables encryption of the self-contained (JWT-encoded) access
# tokens. This setting is ignored if the access tokens are identifier based.
op.grantHandler.selfIssuedJWTBearer.accessToken.encrypt = false

# The audience list for self-contained (JWT-encoded) access tokens, omitted if
# not specified or if the access token is identifier based.
op.grantHandler.selfIssuedJWTBearer.accessToken.audienceList =

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.

Developers can also implement their own handlers from scratch, using the SelfIssuedJWTGrantHandler SPI.

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.

Imporant: 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.

3. Receiving support

Our Connect2id support team is available if you need help with configuring a JWT bearer grant handler or implementing your own.