Client Credentials grant (OAuth 2.0)

Client Credentials

The Client Credentials grant feature of OAuth 2.0 enables server-to-server authentication, without involving actual users. It provides a special ID for the server, allowing it to assign permissions as if it were a real user. For more details, see IEFT RFC 6749.

The Client Credentials grant is particularly useful in Spark systems when performing API operations that don't involve any user interaction. This can include CI/CD operations or any other tasks that require communication with OAuth 2.0 protected APIs.

Create client

1. Login to the target Spark tenant. Access the Keycloak console from the User menu.

2. Login to the Keycloak Admin Console using your admin credentials.

3. On the left pane click Clients.

4. In the Clients list tab, click on Create client.

5. Fill in the required details and click Next.

   Key	Value
   Client ID	Your Client ID name
   Client type	openid-connect

6. Apply the following settings and click Next. Service account roles should be checked automatically and greyed out.

   Key	Value
   Standard flow enabled	Off
   Direct access grants	Off
   Client authentication	On
   Authorization	On

7. Leave Login Settings unfilled and click Save.

Create client mappers

1. Click on the Client scopes tab.

2. In the Assigned client scope column, click on {clientname}-dedicated, e.g. ccdemo-dedicated.

3. Click Add mapper and select By configuration from the dropdown list.

4. Click on Audience and enter the following:

   Key	Value
   Name	aud
   Included Client Audience	product-factory
   Add to access token	On

5. Click Save.

6. Click Add mapper and select By configuration from the dropdown list.

7. Click on Hardcoded claim and enter the following:

   Key	Value
   Name	realm
   Token Claim Name	realm
   Claim value	{your-tenant-name}
   Claim JSON Type	String
   Add to access token	On

8. Click Save.

9. Click Add mapper and select By configuration from the dropdown list.

10. Click on Group Membership and enter the following:

    Key	Value
    Name	groups
    Token Claim Name	groups
    Add to access token	On
    Full Group Path	Off

11. Click Save.

Add client credentials to groups

1. Go to the Service Account Roles tab.

2. Just below the tab, click the link labeled: “To manage detail and group mappings, click on the username {your service account name}.”

3. On the User Details page, navigate to the Groups tab.

4. Click Join Group, select the desired group (for example supervisor:pf) and click Join.

Create the credential

1. On the left panel, click Clients under Manage.

2. Select and click into your newly created Client.

3. Click on the Credentials tab at the top.

4. Copy the Client secret using the clipboard icon. Securely store this value.

5. Copy the Client ID from the top left corner of the page. Securely store this value.

6. Open an application that can be used to test APIs and import cURL statements. Import the following cURL statement:

   curl --location 'https://keycloak.{environment}.coherent.global/auth/realms/{tenant}/protocol/openid-connect/token' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'grant_type=client_credentials' \
   --data-urlencode 'client_id={client_id}' \
   --data-urlencode 'client_secret={client_secret}'

7. Replace the the {environment}, {tenant}, {client_id}, {client_secret} with the appropriate values.

8. Send the request.

9. From the response, retrieve the value of the access_token key.

Assign Client Credentials to a Spark folder

If you would like to assign the Client Credential to a specific folder to limit the permissible access, you can follow the instructions in Set permissions on folders via API and define the service-account member.

Test the Client Credentials

With a Keycloak token, you can make an API request against your Spark tenant to ensure the token is working properly. In this example we will use the GET Categories API.

1. Follow the steps in Create the credential to get the access token.

2. Create a GET API request:

   • URI: https://excel.{environment}/api/v1/lookup/getcategories.

   • Header: Authorization: Bearer {token}.

3. Send the API request.

4. You should receive a 200 OK response.