Imagine a storage API, such as Google Storage or Amazon S3. You’re building an application that has resources (data files, images, etc.) stored externally to your app using one of these APIs. The application needs to read and update these resources, but acting on behalf of the app itself rather than on behalf of any individual user. This is a perfect use case for the Client Credentials flow. The application can ask the OAuth authorization server for an access token directly, without the involvement of any end user.

There is another representative case for the Client Credentials flow—when a resource owner has granted an application access to their resources out of band, without using a typical OAuth flow. Google provides a concrete use case in the Google Apps Marketplace. When an application is listed on the Marketplace, vendors get credentials that represent their application and also register the scopes of data they need access to. When the application is later installed by an organization’s IT administrator, Google asks the administrator whether it’s OK to grant the application access to his organization’s data. When access is approved, Google stores that organization “Acme Corp” has granted access to “Google Calendar and Google Contacts” for application “Task Manager Pro.” Google does not issue any tokens to the application. When the application tries to access data in the future, Google simply looks up whether the application is allowed access to data for the particular organization.

While the preceding paragraphs describe some potential use cases for this flow, these providers (Google and Amazon) have not yet implemented the Client Credentials flow in OAuth 2.0. However, Facebook has implemented this flow for its applications, to be able to perform App Login. App Login is required for certain Facebook API calls, including the ability to get app statistics and user demographics from the App Insights service.

This flow is reliant upon the client being able to properly authenticate with the authorization server and the client’s authentication credentials remaining confidential. In order to authenticate, the client can pass the client_id and client_secret to the authorization server as POST parameters in the access token request or can use a HTTP Basic Authentication header. The authorization server can also authenticate the client using other mechanisms, such as a public/private key pair, SSL/TLS client authentication, and the like.

Depending on the precise use case the Client Credentials flow is used for, a single set of credentials for a client could provide access to a large amount of data. The more data a single set of credentials has access to, the greater the risk if the credentials become compromised. It is extremely critical that the credentials used to authenticate the client be kept highly confidential. Ideally, these credentials would also be regularly rotated.

To demonstrate this flow, we’ll use Facebook’s implementation of App Login with the App Insights service.

https://graph.facebook.com/oauth/access_token

curl -d "grant_type=client_credentials
&client_id=2016271111111117128396
&client_secret=904b98aaaaaaac1c92381d2" 
https://graph.facebook.com/oauth/access_token

access_token=2016271111111117128396|8VG0riNauEzttXkUXBtUbw

{
  "access_token":"2016271111111117128396|8VG0riNauEzttXkUXBtUbw"
}

curl "https://graph.facebook.com/202627763128396/insights?
access_token=2016271111111117128396|8VG0riNauEzttXkUXBtUbw"

The Client Credentials flow typically provides a long-lived access token. The authorization server may indicate an expires_in time; however, the protocol does not support issuing a refresh token in response to the Client Credentials flow. Instead, the application simply asks for a new access token if the current one expires.