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?
-
The Connect2id server receives an access token request with a client credentials grant.
-
The Connect2id server verifies the client credentials (
client_id
andclient_secret
) and whether use of the grant is permitted. -
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.