API - Authentication for service accounts

This topic describes the authentication that is required for service accounts to authenticate with the Advanced Browser Security API.

When you use a service account to run the Advanced Browser Security API commands, you can use any programming language or environment to run the API commands. Service accounts use OAuth2 client credentials for authentication (RFC 6749, section 1.3.4).

This topic includes:

• API - Authentication for service accounts
  • Creating a service account
  • Generating an access token
  • Generating an access token using PowerShell [example]
  • Generating an access token using Python [example]

Creating a service account

For details on how to use the Advanced Browser Security Console to create a service account, see Service Accounts.

You can also use the Advanced Browser Security API to create a service account. Go to the Advanced Browser Security API in Swagger at the following location:

Use Swagger's "Try it out" functionality to run the "POST /service-account" API call. You'll need to supply a name for the new service account, and a role. It is recommended that you assign the Reader role to the new service account. The result will contain the client id and the client secret fields. Store these values in a secure manner.

Generating an access token

An access token is required for a service account to access the Advanced Browser Security API. To generate an access token, follow the OAuth2 Client Credentials Grant flow:

• Headers

  • Authorization: The client must pass its client id and client secret in the authorization header through Basic HTTP authorization. The header value is: "Basic " + Base64Encode(client_id:client_secret)

  • Content-Type: Must always be application/x-www-form-urlencoded.

• Body

  • Must always be grant_type=client_credentials.

The response is a JSON object that will contain the access_token field that contains the access token. The access token will be valid for one hour.

Generating an access token using PowerShell [example]

# get client id and client secret, for example from env vars
$ClientId = $env:CLIENT_ID
$ClientSecret = $env:CLIENT_SECRET
# get access token
$auth = Invoke-RestMethod -Method Post -Uri "https://auth.hysolate.com/oauth2/token" -Headers @{
    "Authorization" = ("Basic", [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(($ClientId, $ClientSecret -join ":"))) -join " ")
} -Body @{
    "grant_type" = "client_credentials"
}
# build default Headers for API requests
$Headers = @{
    "Authorization" = ($auth.token_type, $auth.access_token -join " ")
}

# Now you can use $Headers as the -Headers parameter to Invoke-RestMethod

Generating an access token using Python [example]

Using the requests_oauthlib package

import os
from oauthlib.oauth2 import BackendApplicationClient
from requests.auth import HTTPBasicAuth
from requests_oauthlib import OAuth2Session
# get client id and client secret, for example from env vars​
CLIENT_ID = os.getenv('CLIENT_ID')
CLIENT_SECRET = os.getenv('CLIENT_SECRET')
​# get an access token
auth = HTTPBasicAuth(CLIENT_ID, CLIENT_SECRET)
client = BackendApplicationClient(client_id=CLIENT_ID)
session = OAuth2Session(client=client)
session.fetch_token(token_url=f'https://auth.hysolate.com/oauth2/token', auth=auth)
​# now you can use session as a regular requests's Session object for calls to https://xray.abs.perception-point.io

See also: 

• API - Admin Audit Logs