Security

Many times, a secure, authorised communication channel between different parts of an autonomous system is required. Think of two backend services from different companies communicating through the internet. For these cases, OAuth 2.0 provides the client credentials grant flow. In this case, OAuth 2.0 can be used for machine to machine (M2M) communications.

What does this mean? In contrast to usual systems where an authorisation process attempts to establish trust by authorising a user, in this case what must be authorised and trusted is the client. In other words, there is no need for a user to interact with the system to authenticate, rather the system must authenticate and authorise the client. To be clear, in this case, the client is simply an application, process or even an autonomous system. For these scenarios, typical authentication schemes like username + password, social logins, etc. don't make sense.

The client credentials grant from OAuth 2.0 attempts to fulfil the need for these scenarios. In the client credentials grant, the client holds two pieces of information: the client ID and the client secret. With this information, the client can request an access token for a protected resource.

The client makes a request to the authorisation server sending the 'client ID', the 'client secret', along with the audience and other claims.
The authorisation server validates the request, and, if successful, sends a response with an access token.
The client can now use the access token to request the protected resource from the resource server.

Since the client must always hold the client secret, this grant is only meant to be used in trusted clients. In other words, clients that hold the client secret must always be used in places where there is no risk of that secret being misused. For example, while it may be a good idea to use the client credentials grant in an internal daemon that sends reports across the web to a different part of your system, it cannot be used for a public tool that any external user can download from GitHub.

Client Credentials Grant

The client credentials grant is very simple to use. The following are the relevant HTTP requests:

POST https://<YOUR_OAUTH_DOMAIN>/oauth/token
Content-Type: application/json
{
  "audience": "<API_IDENTIFIER>",
  "grant_type": "client_credentials",
  "client_id": "<YOUR_CLIENT_ID>",
  "client_secret": "<YOUR_CLIENT_SECRET>"
}

A successful authorisation request results in a response like the following:

HTTP/1.1 200 OK
Content-Type: application/json
{
  "access_token": "eyJz93a...k4laUWw",
  "token_type": "Bearer",
  "expires_in": 86400
}

Please note: Once you obtain a token, please use until it expires. Currently a token will expire after 86400 seconds i.e. 1 day.