OAuth Client Credentials Flow
The OAuth Client Credentials Flow in Detail
Client Credentials Flow Overview¶
The Client Credentials flow is a server to server flow. There is no user authentication involved in the process. In fact there is no user at all, the resulting access tokens will not contain a user, but will instead contain the Client ID as subject (if not configured otherwise).
This flow is useful for systems that need to perform API operations when no user is present. It can be nightly operations, or other that involve contacting OAuth protected APIs.
Since there is no user authorization, the flow only interacts with the Token endpoint.
- The Client makes a POST request to the OAuth Server
- The OAuth Server issues the Access Token immediately and responds to the client
The benefit of using the client credentials flow in contrast to merely basic authentication is two-fold. Firstly your API infrastructure can be made uniform, no matter if the request comes from an authenticated user or from a server with a system user, the authentication in the API can be reused. Secondly using client credentials you limit the parties that you send the credentials to. In OAuth the client calls the token endpoint to retrieve an access token and then use that token to call the API. Using basic authentication only would mean that the client would send the credentials to any API it needs to communicate with, thus more parties share the secret.
The client authenticates in the Token part of the flow. Client authentication can be done in many ways, the most common being client secret. The following authentication mechanisms are supported in Curity:
- No authentication (public client)
- Secret in post body
- Secret using basic Authentication
- Client Assertion JWT
- Mutual TLS (mTLS) client certificate
The Access Token¶
The Access Token is returned by the token endpoint. It is the token that later can be used to call the API and gain access. It is a Bearer token, and must not be sent to untrusted parties. The access token usually have a lifetime of 5-30 minutes.
The Refresh Token¶
No refresh token is issued. The client can make the same call again to obtain a new access token.
The Token Endpoint¶
- Response Type:
|client_id||The Client ID||yes||The ID of the requesting client|
|client_secret||The client secret||yes*||The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication|
|grant_type||yes||Tells the token endpoint to do perform the client credentials flow.|
|scope||Space separated string of scopes||no||List the scopes the client is requesting access to.|
- Response Type:
|access_token||A newly issued access token||yes||The resulting access token for the flow|
|expires_in||Expiration in seconds||yes||The time to live of the access token in seconds|
|scope||Space separated string||no||If not present the requested scopes where issued. If present the issued scopes may differ from the requested scopes.|
|token_type||yes||Describes how the token can be used. Most commonly Bearer token usage.|