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 offers a flexible Java Service Provider Interface (SPI) for determining the authorisation properties (scope values, etc) for a valid client credentials grant.

How does the SPI get invoked?

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

  2. The Connect2id server verifies the client credentials (client_id and client_secret) 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.

The client credentials handler SPI is defined in the Connect2id server toolkit, which is open source (Apache 2.0) and can be freely used to create custom handler implementations:

https://bitbucket.org/connect2id/server-sdk

Features of the client credentials grant handler SPI:

  • Enables initialisation of the handler from a chosen 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.

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

INFO main MAIN - [OP7106] Loaded and initialized password grant handler com.nimbusds.openid.connect.provider.spi.grants.password.webapi.PasswordGrantWebAPI

Important: The Connect2id server can load multiple grant handlers at startup, but only one may be enabled at any one time.

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 build your own handler implementation if required.

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. http://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. Support

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