OAuth2 Client Credentials (Scripts)

OAuth2 supports multiple methods to securely access the API. One specific access method is called Client Credential Grants, which is suited for scripts.

A client credential grant workflow follows these steps:

  1. Each user goes to Cisco XDR and creates a client (you should provide the correct information to your users so they can create a suitable client for you).
  2. Each user then enters the credentials into your application
  3. The application uses those credentials to access IROH API on behalf of the user.

Create a Client

There are two ways to create a client:

  1. Using the Cisco XDR UI
  2. Using the API (via the Swagger UI interface)

Using the Cisco XDR UI

For details on how to create an API client through the Cisco XDR UI, see the API Clients Help topic in the Cisco XDR documentation.

Using the API (via the Swagger UI Interface)

The Swagger UI provides raw access to the API to create a client. However, the only way to work with this API is by using a JWT with the oauth scope.

Retrieve the list of your scopes. You will not be able to create a client with more scopes than you are allowed to access.

To get the list of scopes, use the whoami profile API:

https://visibility.amp.cisco.com/iroh/profile/#!/Profile/get_iroh_profile_whoami

If you are already logged in to https://visibility.amp.cisco.com/, you will not need to enter any information in the Authorization header inputs in Swagger. If not, click Authorize and provide authorization with a IROH login, apiKey, or OAuth2 credentials.

To use the /iroh/profile/whoami API:

  1. Log in to the whoami profile API: https://visibility.amp.cisco.com/iroh/profile/#!/Profile/get_iroh_profile_whoami.

  2. Expand the /iroh/profile/whoami profile and click Try it out.

  3. Click Execute.

Under Server response, assuming you received a HTTP status code of 200, you will find the response from the API request. It is a JSON containing your user and org information including the list of your scopes.

Here is example response from the /iroh/profile/whoami API:

{
    "user": {
        "scopes": [
            "admin",
            "casebook",
            "cisco",
            "collect",
            "enrich",
            "global-intel:read",
            "inspect",
            "integration",
            "oauth",
            "private-intel",
            "profile",
            "response",
            "ui-settings"
            "users"
        ],
        "updated-at": "2019-04-30T13:54:21.641Z",
        "user-email": "dev.null@cisco.com",
        "org-id": "13375cf9-561c-4958-0000-6d84b7ef09d4",
        "user-id": "idb-amp:13375ee9-2e3a-4e1b-977d-961facb5fd84",
        "idp-mappings": [{
            "idp": "idb-amp",
            "user-identity-id": "13375ee9-2e3a-4e1b-977d-961facb5fd84",
            "organization-id": "13375cf9-561c-4958-0000-6d84b7ef09d4"
        }],
        "enabled?": true,
        "last-logged-at": [
            "2019-04-30T13:54:21.843Z"
        ],
        "created-at": "2019-04-30T13:54:21.622Z"
    },
    "org": {
        "scim-status": "activated",
        "name": "IROH Testing",
        "enabled?": true,
        "id": "13375cf9-561c-4958-0000-6d84b7ef09d4",
        "created-at": "2019-04-30T13:54:21.634Z"
    }
}

For a description of each field, refer to the section User Model under the Data Model page.

Now that you know which scopes you have access to, you can now create the client.

To create the OAuth2 client, use the clients API:

https://visibility.amp.cisco.com/iroh/oauth2-clients/index.html#/OAuth2Client/post_iroh_oauth2_clients_clients

To use the /iroh/oauth2-clients/clients API:

  1. Log in to the clients API: https://visibility.amp.cisco.com/iroh/oauth2-clients/index.html#/OAuth2Client/post_iroh_oauth2_clients_clients.

  2. Expand the /iroh/oauth2-clients/clients profile and click Try it out.

  3. Edit the JSON next to CreateClientParams with the configuration for the client. For a description of each field, refer to the OAuth2 Client Model.

  4. Click Execute.

    Under Server response, assuming you received a HTTP status code of 200, you will find the response from the API request. For a description of each field in the response, refer to the OAuth2 Client Model.

Use the Client

Note: If you have not yet created a client that can be used for client credentials, you must create a client. For details, refer to Create a Client.

If you have successfully created the client, you should have the following information:

  • client_id
  • client_password

You cannot access the IROH APIs directly with these credentials because OAuth2 requires the use of an intermediate request in order to make all the necessary security checks. This request will provide you with an access token. An access token is a token you can use to access the APIs for a limited period of time.

The IROH access tokens: JSON Web Token (JWT). Once you have a JWT, you can use it until it expires.

When the access token gets close to expiring, you will need to request another one.

Get the Access Token

In order to retrieve the access token, you need to use the /iroh/oauth2/token API and provide the client_id and client_password.

The following is an example API request to /iroh/oauth2/token using a cURL command:

client_id="client-38bbc74d-f7d1-452b-8777-fb8c7d985477"
client_password="FIz1FDf40ms0mNpc9oS8AJQJ2Vyw0aUtE17XWZWEQ71IMs13J8AQFQ"
curl -X POST \
    -u "$client_id:$client_password" \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/x-www-form-urlencoded' \
    -d 'grant_type=client_credentials' \
    'https://visibility.amp.cisco.com/iroh/oauth2/token'

The -u is to use Basic Auth, with client-id as user and client-password as password. In order to manually supply the correct header, remember to base64 encode the client_id:client_password string. The following two code examples are interchangeable:

curl -u "client_id:client_password" https://example.com

and

creds=$(echo -n client_id:client_password | base64)
curl -H "Authorization: Basic $creds" https://example.com

It is also important to set the content type to application/x-www-form-urlencoded.

Note: The route does not support parameters sent via a JSON Content-Type (cf. RFC6749 section 4.1.3).

The server should then return a successful response (cf. RFC6749 section 4.1.4):

{
    "access_token":"eyJhbGciO...",
    "token_type":"bearer",
    "expires_in":600,
    "scope":"enrich:read casebook inspect:read"
}

Per the scope field of this example response, the particular access token will allow the user to access:

  • enrich read only routes
  • all casebook routes
  • inspect read only routes

Per the expires_in field, the access token will expire in 600 seconds.

Make an API Request Using the Access Token

Now that you have retrieved the access token (which is a JWT), you can make an API request with it. However, you will be restricted to the scopes you granted to your client.

Here is an example request using the access token:

ACCESS_TOKEN="eyJhbGciO..."
curl -X POST \
    -H 'Accept: application/json' \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    -d '{"content":"cisco.com"}' \
    'https://visibility.amp.cisco.com}/iroh/iroh-inspect/inspect'

To see an exhaustive list of APIs with links to their swagger UI interfaces and a list of scopes, see Authorization Access or Scopes.

Checklist

Verify your integration satisfies the Client Checklist.