Configuring API Authentication

This topic describes the authentication required to make calls to the Stellar Cyber API. In general, you will need a user account with sufficient privileges, an API key, and a JSON Web Token created from the API key. See the following sections for details:

Required Privileges to Make API Calls

To perform API calls, you must have:

  • Root scope

  • Super Admin privileges (must be the default profile template)

We recommend creating a Stellar Cyber user dedicated to API calls. That way you can easily track changes made through API calls under System | Administration | Users | Activity Log.

Necessary Information to Make API Calls

Calls to the Stellar Cyber API typically require a subset of the following information:

Data Description
Email Address Email address of the admin account making the call.
API Key

Generate an API key as follows:

  1. Navigate to the System | Administration | Users page.

  2. Locate the user account to perform the API call and click the Edit () button in its row. Remember that the user performing the call must have Root scope and Super Admin privileges.

  3. Locate the API Access item in the dialog box that appears and click the Generate New Token button.

  4. Copy and paste the token into a text file to store it temporarily.
YourStellarCyberServer The URL or IP address of your Stellar Cyber server.

Authentication for API Calls

Requests to the Stellar Cyber public APIs can be secured using either of the following techniques:

  • Basic Authentication – With basic authentication, you use only the API key retrieved from the System | Administration | Users page to authenticate API calls.

    This is the technique that has been used in previous Stellar Cyber releases and is still available.

  • JSON Web Token Authentication – JWT authentication offers enhanced authentication consistent with industry best practices. With JWT authentication, you use the API key retrieved from the System | Administration | Users page to generate a time-sensitive JWT. See the next section for details on using JSON web tokens.

Generating a JSON Web Token (JWT) from the API Key

Requests to the Stellar Cyber public APIs can be secured using JSON Web Token (JWT) authentication.

JWT authentication offers rapid, scalable, and secure authentication for API calls. They are also time-sensitive, expiring ten minutes after they are generated. Because of this, scripts you write to pull data from the Stellar Cyber API should typically include a section used to refresh the requesting user's JWT.

The sample scripts in this topic include a section that refreshes the JWT using the supplied API Key.

You generate a JWT by sending a request to the public https://<YourStellarCyberServer>/connect/api/v1/access_token API on the DP. The request must include the Email Addressand API Key you retrieved in the table above. The API Key you retrieve from the System | Administration | Users page acts as a refresh key that you use to generate a new JWT.

For example, the sample Python script below retrieves a JWT and prints it to the screen using the following details:

  • DP – myserver.stellarcyber.cloud

    This is specified in the HOST variable at the top of the sample script.

  • Email Address – myuser@stellarcyber.ai

    Note that the email address is case sensitive and must match the case used in the Stellar Cyber user interface.

  • Refresh Token from GUI – 2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH

    These are specified in the userid and refresh_token variables in the sample script.

Copy 
#!/usr/bin/python3

import requests
import base64
import json
from urllib.parse import urlunparse
requests.packages.urllib3.disable_warnings()

# Step 1
# Add DP IP/hostname, userid, and refresh token from GUI here
HOST = "myserver.stellarcyber.cloud"
userid = "myuser@stellarcyber.ai"
refresh_token = "2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH"

def getAccessToken(userid, refresh_token):
    auth = base64.b64encode(bytes(userid + ":" + refresh_token, "utf-8")).decode("utf-8")
    headers = {
        "Authorization": "Basic " + auth,
        "Content-Type": "application/x-www-form-urlencoded",
    }
    url = urlunparse(("https", HOST, "/connect/api/v1/access_token", "", "", ""))
    res = requests.post(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()["access_token"]

if __name__ == "__main__":

    # Step 2: Use getAccessToken with supplied credentials to generate JWT
    jwt = getAccessToken(userid, refresh_token)
    print("------------ jwt -------------")
    print(jwt)
    print("------------ jwt  end -------------")

Generating a New JWT as Part of a Script

Because JWTs expire ten minutes after they are generated, you may want to include logic in your scripts similar to the previous code sample to generate and use a fresh JWT every time the script is run.

For example, the code sample below uses the same host, userid, and refresh_token as above but includes it as part of a script that pulls the ten most severe incidents for a specific tenant. Note the following:

  • The script sets the host, userid, and refresh_token in the same places as the previous script (Step 1 in the sample).

  • The script runs the getAccessToken procedure to generate the new JWT (Step 2 in the sample).

  • The script uses the generated JWT to make a call to the incidents API in the getIncidents procedure (Step 3 in the sample). This procedure also includes specific arguments that specify the tenant_id and how many incidents to retrieve (10), as well as the order in which to return them (desc).

  • The script also prints the generated JWT to the screen. This, however, is not strictly necessary since the getAccessToken procedure already prints the status code for the call to the access_token API (200 for success; 401 for failure).

Copy 
#!/usr/bin/python3

import requests
import base64
import json
from urllib.parse import urlunparse
requests.packages.urllib3.disable_warnings()

# Step 1
# Add DP IP/hostname, userid, and refresh token from GUI here
HOST = "myserver.stellarcyber.cloud"
userid = "myuser@stellarcyber.ai"
refresh_token = "2iRpBAyQYEfv77R2QtATlJN6Nvq6uzftBdzotSy2pjT-IvJTLw9aiHyh7Y2mo12IDSWc-FfHwUyPpmiHQnJrSH"

def getAccessToken(userid, refresh_token):
    auth = base64.b64encode(bytes(userid + ":" + refresh_token, "utf-8")).decode("utf-8")
    headers = {
        "Authorization": "Basic " + auth,
        "Content-Type": "application/x-www-form-urlencoded",
    }
    url = urlunparse(("https", HOST, "/connect/api/v1/access_token", "", "", ""))
    res = requests.post(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()["access_token"]


def getIncidents(token):
    headers = {"Authorization": "Bearer " + token}
    url = urlunparse(("https", HOST, "/connect/api/v1/incidents?tenant_id=817418af76d44358922636e34be9627c?sort=incident_score&order=desc&limit=10", "", "", ""))
    res = requests.get(url, headers=headers, verify=False)
    print(res.status_code)
    return res.json()

if __name__ == "__main__":

    # Step 2: Use getAccessToken with supplied credentials to generate JWT
    jwt = getAccessToken(userid, refresh_token)
    print("------------ jwt -------------")
    print(jwt)
    print("------------ jwt  end -------------")

    # Step 3: use JWT token to call public API
    incidents = getIncidents(jwt)
    print("------------ call result of /connect/api/v1/incidents -------------")
    print(incidents)
    print("------------ end api results -------------")

All API Calls Stored in User Activity Log

Any API request to the public APIs listed here is logged to the User Activity Log with the corresponding user. The request body is also visible by clicking the JSON Data button for the call in the User Activity Log page.