Client credentials grant handler SPI

1. Introduction

The OAuth 2.0 client credentials grant is intended for applications or services that act on their own behalf (instead of on behalf of an end-user, which is the common OAuth 2.0 case), to make requests to a protected resource with an access token.

For a client to make an access token request on its own behalf it must be explicitly registered for the client_credentials grant. The request is authenticated with the client_id and client_secret credentials obtained during registration (hence the name of the grant), and may optionally specify an explicitly requested scope.

Note that the response does not include a refresh token. If the obtained access token has expired, the client should simply repeat the request to get a new one.

You can find more information in the OAuth 2.0 spec and in our article on using the client credentials grant.

2. Client credentials grant handler SPI

The Connect2id server comes with a flexible plugin interface (SPI) for determining the authorisation properties (scope values, etc) for a valid client credentials grant.

Features of the client credentials grant handler SPI:

  • Enables initialisation of the handler from a configuration file.

  • The handler is passed the registered client details, which can then be used to determine the authorisation properties (scope values, etc).

  • Enables implementations to release resources on Connect2id server shutdown.

How does the SPI get invoked?

  1. The Connect2id server receives an access token request with a client credentials grant.

  2. The Connect2id server validates the client_id and its credentials and whether use of the grant is permitted.

  3. On success the SPI gets invoked to determine the authorisation properties, such as scope values, access token lifetime and encoding.

3. Available implementations

Connect2id provides two ready handler implementations, released under an open source (Apache 2.0) licence. You can use them as an example to develop your own handler implementation.

3.1 Simple handler using the registered scope values

This handler comes pre-installed with the Connect2id server. It relies on the registered scope values for the client to bound the access token scope. Any requested scope values not found in the registered list will simply be left out from the authorisation.

The handler comes with a simple configuration which is found in the clientGrantHandler.properties file within the WEB-INF directory of the Connect2id server.

### ### OAuth 2.0 client credentials grant handler configuration ### ###

# This file configures the local handler for client credentials grants.
#
# See:
#
# 1. https://bitbucket.org/connect2id/client-credentials-grant-handler
# 2. https://bitbucket.org/connect2id/server-sdk
# 3. https://connect2id.com/products/server/docs/integration/client-credentials-grant-handler

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


### Access token settings ###

# The access token lifetime, in seconds.
op.grantHandler.clientCredentials.simpleHandler.accessToken.lifetime=600

# 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.clientCredentials.simpleHandler.accessToken.encoding=SELF_CONTAINED

# If true enables additional encryption of self-contained (JWT-encoded) access
# tokens.
op.grantHandler.clientCredentials.simpleHandler.accessToken.encrypt=false

# Optional audience for the access tokens, as comma and / or space separated
# list of values.
op.grantHandler.clientCredentials.simpleHandler.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.clientCredentials.simpleHandler.accessToken.includeClientMetadataFields=

Example minimal configuration for issuing self-contained (JWT) access tokens with a lifetime of 10 minutes (600 seconds):

op.grantHandler.clientCredentials.simpleHandler.enable=true
op.grantHandler.clientCredentials.simpleHandler.accessToken.lifetime=600
op.grantHandler.clientCredentials.simpleHandler.accessToken.encoding=SELF_CONTAINED

Example configuration for issuing identifier-based access tokens which are checked at the Connect2id server token introspection endpoint:

op.grantHandler.clientCredentials.simpleHandler.enable=true
op.grantHandler.clientCredentials.simpleHandler.accessToken.lifetime=600
op.grantHandler.clientCredentials.simpleHandler.accessToken.encoding=IDENTIFIER

Example configuration which puts the registered client metadata fields software_id and data -> org_id into the access token data field:

op.grantHandler.clientCredentials.simpleHandler.enable=true
op.grantHandler.clientCredentials.simpleHandler.accessToken.lifetime=600
op.grantHandler.clientCredentials.simpleHandler.accessToken.encoding=IDENTIFIER
op.grantHandler.clientCredentials.simpleHandler.accessToken.includeClientMetadataFields=software_id,data.org_id

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.clientCredentials.simpleHandler.enable=false

The Git repo for the handler:

https://bitbucket.org/connect2id/client-credentials-grant-handler

3.2 Web-based handler

This handler calls a remote web service to determine the authorisation properties for a verified client credentials grant.

The web interface messages are defined in the source code of the handler.

The Git repo for the handler:

https://bitbucket.org/connect2id/client-credentials-grant-web-api

4. How to develop your own client credentials grant handler

First, read our general guide for developing, annotating and packaging an SPI-based plugin.

The connector must implement the ClientCredentialsGrantHandler SPI defined in the Connect2id server SDK:

Git repohttps://bitbucket.org/connect2id/server-sdk

If the Connect2id server detects an SPI implementation at startup it will log its loading under OP7106:

INFO main MAIN - [OP7106] Loaded and initialized client_credentials grant handler com.nimbusds.openid.connect.provider.spi.grants.client.handler.SimpleClientCredentialsGrantHandler

Note, the Connect2id server can load multiple client credentials grant handlers at startup, but only one may be enabled at any one time.

5. Support

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