Learn about our OAuth 2.0 Client Credentials grant flow including how to generate CC (Client Credentials) hash in Java library, security considerations, and examples of authorization requests, accessing, refreshing, validating, invalidating the OAuth tokens.
Aurora supports OAuth 2.0 Client Credentials grant flow using the client application parameters to generate the access token without user involvement. Client Credentials grant flow enables server-to-server authorization which allows access to necessarily read-any data from the community based on the access provided by the assigned role for the client application without the use of any user credentials.
Client Credentials grant flow can only assist with reading data from the community. POST, PUT, and DELETE actions must not be performed since there is no user involvement. All the requests from the client credentials access token run in an anonymous user context.
You can find complete OAuth documentation on the OAuth website.
Note: The OAuth 2.0 Client Credentials grant flow is disabled by default. To enable it, Contact Support.
Before you begin
Before you get started, be sure you understand the terminology used for OAuth2.0 Client Credentials grant flow.
Terminology
First, let’s define a few terms:
- Khoros Community – A Community app hosted by Khoros. This is the entity in the OAuth flow that is responsible for permission control and enforcement.
- Customer Application – A Customer Application that generates and uses access tokens for API access.
- Client ID – A unique identifier representing the Client App or API App, used to make any API calls to the community.
- Client Secret – A unique string that serves as a secret key for any communications made for any API App as mandated by OAuth2.0 guidelines.
- Shared Secret Key – Used for generating access token for Client Credentials grant type flow. This key can be downloaded only once from the API Apps viewer in the Dev Tools. If a shared key is lost/expired, you can only reset and get a new one.
- CC Hash – CC Hash (Client Credentials hash) generated using the client credentials and the respective client application’s shared secret key. To generate cc hash, see Generate CC Hash and Nonce for OAuth2.0 Client Credentials Grant Flow.
- Nonce – Nonce (number used once) is typically a randomly generated value that is associated with a message and must be unique within some specified scope. It’s typically used to prevent replay attacks (aka playback attacks). To generate a nonce, see Generate CC Hash and Nonce for OAuth2.0 Client Credentials Grant Flow.
Find the parameters for an access token
A client ID, client secret, and shared secret key are used as authorization credentials in the OAuth2.0 Client Credentials grant flow in order to generate the access and refresh tokens that enable to make authenticated REST calls with the Community API without needing any user credentials. See Generating API Credentials for instructions to register your Community web or iOS/Android mobile app.
About the Client Credentials Grant flow
The Client Credentials grant flow is useful for systems that need to perform API operations where there is no user. This flow is used specifically when a client application needs to get access on behalf of itself (using a client ID, client secret key, shared secret key), outside the context of any user.
The Client Credentials grant flow is a server-to-server authorization to generate access tokens on behalf of the client application. The access tokens contain information about the client application and do not contain user information. There is no user authentication involved in this flow. The access token is valid for 24 hours.
In the Client Credentials grant flow, permissions are granted directly based on the role to the client application provided by an administrator in the Community Admin.
Let's take a look at the summary of the flow.
- Create a web application to generate a client ID, client secret key, and shared secret key in Community Admin > System > API Apps based on the assigned role. See Generating API Credentials.
- Generate the cc-hash and nonce for client credentials. See Generate CC Hash and Nonce for OAuth2.0 Client Credentials Grant Flow.
- Make a server-to-server POST call to auth/accessToken to the community using the cc-hash and nonce to get an access token and refresh token mapped to the client application.
- Make subsequent Community GraphQL API calls by adding the access token in the header. The access token inherits permissions of the Community based on the roles/permissions granted in Community Admin.
This diagram provides a high-level overview of the client credentials grant flow.
OAuth Security Considerations
OAuth tokens are scoped to a single client application (also referred to as a client ID) and assigned role. A call with a token specific to one client ID will fail if used with a different client ID and role. Client applications can be deleted in Community Admin > Dev Tools > API Apps if needed.
OAuth API Index
- Request access and request tokens (POST /api/2.1/auth/accessToken)
- Refresh the access token (POST /api/2.1/auth/refreshToken)
- Validate the access token (GET /api/2.1/auth/validateToken)
- Invalidate the access token (POST /api/2.1/auth/invalidateToken)
Request access and refresh tokens
To get an access token, make a POST call to /auth/accessToken.
The /auth/accessToken endpoint returns an access token and a refresh token that can be passed to the /auth/refreshToken.
Header Parameters
| Header Parameter | Description |
|---|---|
| Nonce | Nonce generated using Generate CC Hash and Nonce for OAuth2.0 Client Credentials Grant Flow |
| Content-type | application/json |
Body Parameters
| Body Parameter | Description |
|---|---|
| client_id | The application's ID |
| client_secret | The application’s secret key |
| redirect_uri | The redirect_uri used in the authorization request. This URI must match the callback URL defined for the community. |
| grant_type | Always client_credentials |
| cc_hash |
The cc-hash generated using Generate CC Hash and Nonce for OAuth2.0 Client Credentials Grant Flow
|
| hash_algorithm | This is a mandatory field. You can use the default value SHA512. Supported values are: SHA256, SHA512, RIPEMD160, SCRYPT. Default value: SHA512. |
Example POST /auth/accessToken request
curl -L 'https://[COMMUNITY-DOMAIN]/t5/s/api/2.1/auth/accessToken' \
-H 'nonce: [NONCE NUMBER]' \
-H 'Content-Type: application/json' \
-d '{
"client_id": "[CLIENT ID OF YOUR APPLICATION]",
"client_secret": "[CLIENT SECRET KEY OF YOUR APPLICATION]",
"redirect_uri": "[REDIRECT URL OF YOUR APPLICATION]",
"grant_type": "client_credentials",
"cc_hash": "[GENERATED CC-HASH]",
"hash_algorithm": "sha512"
}'
Example POST /auth/accessToken response
{
"status": "success",
"message": "",
"http_code": 200,
"data": {
"access_token": "1111222233334444455555",
"refresh_token_expires_in": 2592000,
"refresh_token": "666677778888999900000",
"lithiumUserId": "-1",
"token_type": "bearer",
"userId": "-1",
"expires_in": 1800
}
}
Pass the access token with your GraphQL call
When you have your access and refresh token, you are ready to make authorized GET calls to the Community GraphQL API. Include the authorization token in your request header. All requests should be made over HTTPS.
Remember that while the token enables you to make a Community GraphQL API GET call, the role assigned when creating a web app in community admin will determine whether or not the call will be successful.
Before making calls to a third-party application, register the domain from which you will make the calls by filing a Support ticket.
Header Parameters
| Header Parameter | Description |
|---|---|
| Content-type | Always application/json |
| Authorization | Bearer Token The token is the OAuth token retrieved on behalf of the client credentials. |
This example GraphQL call retrieves the first 50 badge sets of your community.
Retrieve Badge Set GraphQL Call
curl -L 'https://[COMMUNITY DOMAIN]/t5/s/api/2.1/graphql' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer 1234565789ABC' \
Query
query {
badgeSets(first: 50) {
edges {
cursor
node {
id
name
featured
position
badges(first: 5) {
totalCount
edges {
cursor
node {
id
title
description
position
ATLAS
Comments