Authentication

Orbital uses authentication provided by Cisco XDR/Secure Client Cloud Management and Secure Endpoint instead of maintaining another set of logins and users. Developer create an API client and corresponding set of client credentials for their applications to use Orbital.

Note: A given set of credentials will only work in one region. For example, you cannot use North American credentials in Europe.

XDR / Secure Client Cloud Management & Verifying Orbital Integration

Creating API credentials is now done through Cisco XDR / Secure Client Cloud Management:

1. Navigate to the Cisco XDR / Secure Client Cloud Management console that matches your region:

2. Verify Orbital integration is enabled (XDR Only):

   

Registering a XDR / Secure Client Cloud Management API Client

1. In the XDR or Secure Client Cloud Management console, click the Administration tab and choose API Clients in the navigation pane.

2. On the API Clients page, click the Generate API Client button to open the Add New Client form.

3. Enter a Client Name and select the Orbital scope:

   

4. Optionally, enter a Description and click Add New Client.

5. A Client Id and Client Password are generated, and are displayed on the form:

   

   Note: The Client Password cannot be recovered after you close this window. Be sure to securely store it where you can access it later. If the Client Password is lost or compromised, you must delete the existing API client and create a new one to generate a new credential set.

Generating a Cisco XDR / Secure Client Cloud Management API Access Token

In order to make Orbital API requests, an application must generate an access token via an OAuth2 client credentials grant request. This token is then included via an Authorization header Bearer token in all subequent API requests.

The access token generation request is an HTTP POST to one of the region-specific URLs below:

The Client Id and Client Password (referred to as a Client Secret in the OAuth2 specification) generated in the previous step must be provided in the grant request via a base64-encoded Authorization header. The grant_type (always client_credentials) is provided in a Content-Type: application/x-www-form-urlencoded body:

Access Token Request Parameters

Example Access Token Request

POST /iroh/oauth2/token HTTP/1.1
Host: visibility.amp.cisco.com
Authorization: Basic QWRtaW5pc3RyYXRvcjpjaXNjb3BzZHQK
Content-Type: application/x-www-form-urlencoded
Accept: application/json

grant_type=client_credentials

# Read in the client_id and client_secret if they are not already set.
[ -z "$client_id" ] && read -p "client_id: " client_id
[ -z "$client_secret" ] && read -p "client_secret: " client_secret

# Call the XDR token endpoint and store the result in a variable.
result=$(curl -s 'https://visibility.amp.cisco.com/iroh/oauth2/token' \
     --user "${client_id}:${client_secret}" \
     --header 'Content-Type: application/x-www-form-urlencoded' \
     --header 'Accept: application/json' \
     -d 'grant_type=client_credentials')

# Extract the access_token from the result.
export BEARER_TOKEN=$(echo "$result" | jq -r .access_token)

# Print the result.
[ -x "$(command -v jq)" ] && echo "$result" | jq . || echo "$result"

Response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
X-Request-Id: 7007c4b7b32c41118a7a524dbb2d286e

{
  "access_token": "eyJhbGciO...",
  "token_type": "bearer",
  "expires_in": 600
}

The response expires_in value indicates the lifetime of the access token (in seconds). If the access token expires, the application should repeat the access token generation request, as above.

Using an Access Token to Make an API Request

Orbital has a simple API that can be used to confirm that an access token is valid: GET /v0/ok

Below is an example request showing how to use an access token to make a test request:

Example Request

GET https://orbital.amp.cisco.com/v0/ok HTTP/1.1
Authorization: Bearer eyJhbGciOiJSUredactedxJfsKKpWQ
Accept: application/json

curl --request GET \
  --url https://orbital.amp.cisco.com/v0/ok \
  --header 'accept: application/json' \
  --header 'authorization: Bearer eyJhbGciOiJredactednR5cCI6IkpXVCIs' \

Note: The base URL for API requests is region-specific - see Getting Started for more details on API request specifics.

If successful, you will see a 200 OK response, with some details about the user associated with the access token:

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

{
  "login": {
    "user": "e30a31da-1268-471a-8d2b-b7ec90332612",
    "email": "dstaudt@cisco.com",
    "jwt": "eyJhbGredactediIsInR5cCI6Ik"
  }
}  

Authentication Errors

Access token generation request or an API request is missing the required credentials:

HTTP/1.1 401 Unauthorized
Content-Type: application/json
X-Orbital-Request-Id: cd4f7a7c-5b09-c8b7-efec-10c0f7368b10

{
    "error": "authentication required"
}

An access token request has incorrect/invalid credentials, or an API request is made using a token for an API client without the Orbital scope:

HTTP/1.1 403 Unauthorized
Content-Type: application/json
X-Orbital-Request-Id: 7dd1c8b2-87ef-11ee-8e6d-03dbaf753642

{
    "error": "authentication invalid"
}

If you are seeing an unexpected/unexplained error, note the X-Orbital-Request-Id header present in every authentication and API response. This header value can be provided to the Orbital support team, who will be able to use it to identify the specific request in the system logs to help with troubleshooting.