Skip to content
Connect2id

Client credentials grant handler

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.

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.

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

-Dop.grantHandler.clientCredentials.simpleHandler.enable=false

### ### 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/api/client-credentials-grant-handler

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


### Access token settings ###

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

# The default access token encoding. Can be overridden by the individual
# authorisations. Defaults to IDENTIFIER.
#
#     * 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.clientCredentials.simpleHandler.accessToken.encoding = SELF_CONTAINED

# The audience list for self-contained access tokens, omitted if not specified
# or if the access token is identifier based.
#
op.grantHandler.clientCredentials.simpleHandler.accessToken.audienceList =

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. Receiving support

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