Client credentials grant handler SPI
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
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.
2. Client credentials grant handler SPI
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_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:
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
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
### ### 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. op.grantHandler.clientCredentials.simpleHandler.enable = true ### Access token settings ### # The access token lifetime in seconds. op.grantHandler.clientCredentials.simpleHandler.accessToken.lifetime = 600 # 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.clientCredentials.simpleHandler.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.clientCredentials.simpleHandler.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.clientCredentials.simpleHandler.accessToken.audienceList =
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
The Git repo for the 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:
4. Receiving support
Our Connect2id support team is available if you need help with configuring a client credentials grant handler or implementing your own.