OAuth Client Credentials Flow
On this page
What is a Client Credentials Flow in OAuth 2.0?
One of the flows specified in the OAuth 2.0 protocol is the Client Credentials flow. The Client Credentials flow is a server to server flow, where no user authentication is 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).
When to Use the Client Credentials Flow
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.
Client Credentials Flow vs Authorization Code Flow
The main difference between the Client Credentials flow and the Authorization Code flow is that the Client Credentials flow relies on application authorization rather than involving the user. Since there is no user authorization, the flow only interacts with the token endpoint.
Steps in the Client Credentials Flow
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
Benefit of Using the Client Credentials Flow
The benefit of using the OAuth 2.0 Client Credentials flow in contrast to merely basic authentication using API keys 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 when 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 uses that token to call the API. Using basic authentication such as API keys only, would mean that the client would send the credentials to any API it needs to communicate with, thus more parties share the secret.
Client Authentication
The client authenticates as part of the token request. There are many ways for a client to authenticate, the most common being client secret. The Curity Identity Server supports the following authentication mechanisms for clients:
- No authentication (public client)
- Secret in POST body
- Secret using Basic Authentication
- Client Assertion JWT
- Mutual TLS (mTLS) client certificate
- Asymmetric Key
- Symmetric Key
- Credential Manager
- JWKS URI
The Access Token
The access token is returned by the token endpoint. It is the token that clients can use to call the API and gain access. It is often a Bearer token, and as such must not be sent to untrusted parties. The access token usually has 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
Request Parameters
- Method:
POST - Content-Type:
application/x-www-form-urlencoded - Response Type:
json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| 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 | client_credentials | yes | Tells the token endpoint to perform the Client Credentials flow. |
| scope | Space separated string of scopes | no | List the scopes the client is requesting access to. |
Response
- Response Type:
application/json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| 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 were issued. If present the issued scopes may differ from the requested scopes. |
| token_type | Bearer or other token type | yes | Describes how the token can be used. Most commonly bearer token usage. |
Conclusion
There are various flows and grant types in OAuth 2.0. For server to server communications, use the Client Credentials flow. When a user is present, you should use the Authorization Code flow instead, so that your APIs always receive the user identity securely, in the access token.
Jacob Ideskog
Identity Specialist and CTO at Curity
Join our Newsletter
Get the latest on identity management, API Security and authentication straight to your inbox.
Start Free Trial
Try the Curity Identity Server for Free. Get up and running in 10 minutes.
Start Free Trial
