External Client App with OAuth 2.0 Client Credentials Flow

This guide explains how to configure an External Client App in Cloudaware to allow an external system (service, script, CI job, integration platform) to authenticate to the Cloudaware CMDB API using OAuth 2.0 Client Credentials Flow.

Audience

• Integration engineers

• Platform/DevOps engineers

• Administrators managing Cloudaware access for external tools

Prerequisites

1. Contact your Technical Account Manager (TAM) or tam@cloudaware.com to enable these Cloudaware User Profile permissions:

   • View all External Client Apps

   • View External Client Apps and edit their policies

   • Create, edit, and delete External Client Apps

2. Ensure you have access to the integration mailbox used as the Contact Email (for identity verification when viewing secrets).

Overview

Cloudaware runs on the Force.com (Salesforce) platform and uses its identity and authorization services. To enable server-to-server (headless) API access via OAuth 2.0 Client Credentials, you must register an OAuth client in Cloudaware as an External Client App, where you define scopes/policies and the running user.

Step 1. Create the External Client App

1. Log in to Cloudaware → Setup.

2. In Quick Find, search for External Client Apps.

3. Select External Client App Manager under Apps.

4. Click New External Client App.

5. In Basic Information:

   • Name: enter a descriptive name

   • Contact Email: enter a monitored email address

   • API Name: auto-populated

   • Distribution State: leave Local

6. Collapse Basic Information when complete.

Step 2. Configure OAuth settings

1. Expand API (Enable OAuth Settings) and select Enable OAuth.

2. Under App Settings, configure:

   • Callback URL: http://localhost:1717/OauthRedirect
     This is the default callback URL commonly used for local testing. You can specify any valid callback URL that matches your application’s redirect endpoint.

   • OAuth scopes: select the following:

     • Manage user data via APIs (api)

     • Perform requests at any time (refresh_token, offline_access)

     If your integration needs to interact with Analytics Studio assets (datasets, dashboards, lenses, etc.), also select:

     • Access Analytics REST API resources (wave_api)

3. Under Flow Enablement, select Enable Client Credentials Flow, then click OK in the confirmation dialog.

4. Under Security, uncheck Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows unless your organization requires PKCE for other enabled flows.

PKCE is designed for public clients (mobile/browser) using Authorization Code flow. For Client Credentials, PKCE is generally not applicable. Read more

5. Click Create.

Step 3. Enable policies and assign the running user

1. Confirm the app status is Enabled.

2. Open the Policies tab and click Edit.

3. Expand OAuth Policies.

4. Check Enable Client Credentials Flow.

5. In Run As (Username), enter the username of the Cloudaware user^* that should run the app).

^*Requests authorized via OAuth 2.0 Client Credentials Flow require a “running user” – an existing Cloudaware user account on whose behalf the API executes actions. Use a dedicated integration user with least-privileged access, and avoid using personal user accounts. The CMDB API enforces the permissions assigned to the running user when processing requests.

6. Click Save. Allow some time for the app to update or manually refresh the page.

Step 4. Retrieve Client ID and Client Secret

1. Go to Settings tab.

2. Expand OAuth Settings.

3. Click Consumer Key and Secret.

4. Enter the verification code sent to the app’s Contact Email.

5. Copy and store:

   • Client ID (Consumer Key)

   • Client Secret (Consumer Secret)

Next steps

Obtain an OAuth access token to authorize your API requests.

Example request (cURL)

curl -X POST https://<YOUR_CLOUDAWARE_DOMAIN>/services/oauth2/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=<YOUR_CLIENT_ID>" \
  -d "client_secret=<YOUR_CLIENT_SECRET>"

Replace <YOUR_CLOUDAWARE_DOMAIN>^*, <YOUR_CLIENT_ID>, and <YOUR_CLIENT_SECRET> with appropriate values.

^*To find the Cloudaware Domain value, navigate to Setup → in Quick Find, search for My Domain. Copy the Current My Domain URL value (format: cloudaware-0000.my.salesforce.com).

Example response

{
    "access_token": "<token>",
    "signature": "<base64_encoded_signature>",
    "scope": "api",
    "instance_url": "https://<YOUR_CLOUDAWARE_DOMAIN>",
    "id": "https://login.salesforce.com/id/<id>/<id>",
    "token_type": "Bearer",
    "issued_at": "<unix_timestamp>"
}