Client Credentials Flow

Overview

The Client Credentials Flow is an OAuth 2.0 authentication flow that enables a client application to obtain an access token directly from an authorization server by using its own client credentials (typically a client ID and client secret). This flow is suitable for machine-to-machine communication where the client application needs to access resources without user involvement.

Flow Description

1. Client Registration: The client application must be registered with the authorization server. During registration, the client is provided with a unique client ID and a client secret.
2. Requesting an Access Token:
   1. The client application sends an HTTP POST request to the authorization server's token endpoint.
   2. The request includes the following parameters in the request body:
      1. grant_type: Set to "client_credentials" to indicate the usage of the Client Credentials Flow.
      2. client_id: The client's unique identifier.
      3. client_secret: The client's secret key.
   3. The authorization server validates the client's credentials and responds with an access token if authentication is successful.
3. Access Token Issuance:
   1. If the client credentials are valid, the authorization server generates an access token and includes additional information such as the token type, expiration time, and scopes.
   2. The access token can be used to access protected resources on behalf of the client application.

Request Example

POST /oauth/token HTTP/1.1
Host: sample.tenant.userclouds.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=your_client_id&client_secret=your_client_secret

Response Example

HTTP/1.1 200 OK
Content-Type: application/json

{
   "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
   "token_type": "bearer",
   "expires_in": 3600
}

Security Considerations

1. Client Secret Protection: The client secret must be kept confidential and not exposed to users or public clients.
2. Scope Restriction: The scope of the access token determines the level of access the client application has. Limit the scope to only what is necessary.
3. HTTPS Usage: Always use HTTPS when communicating with the authorization server to protect client credentials and tokens from eavesdropping.
4. Token Expiry: Access tokens have a limited lifespan. The client should be prepared to handle token expiration and request a new token when needed.

Use Cases

• Backend services accessing UserClouds APIs: This flow is suitable for backend services that need to access APIs or resources without user interaction.
• Server-to-Server Communication: It's useful for communication between different services or servers within a system.

Summary

The Client Credentials Flow provides a straightforward method for client applications to obtain access tokens directly from the authorization server without user interaction. As such, this flow is particularly suitable for machine-to-machine scenarios where user authentication is not required. Careful attention to security considerations is crucial to ensure the integrity and confidentiality of client credentials and tokens.