Using the API through JSON Web Tokens (JWT)

This article describes the steps needed to fully automate management of the product’s licenses and public API through the use of JSON Web Tokens.

JSON Web Tokens are an open industry standard formalized through RFC 7519 that can be used with Secureworks® Taegis™ VDR’s APIs in order to automate license management (Management API) and regular product activity through its OpenAPI (Impersonation API).

In order to obtain access to the API JWT infrastructure, you will need to:

• Let us know that you require JWT token enablement for your instance.
• Generate two secure sets of keys on your own, one for each API.
• Send us the public portion of both keys and store and manage the private portions securely.
• Obtain the issuer and cid strings from us (set up after we receive your public key and JWT setup request).
• Use both these in conjunction with the corresponding private keys to sign JWTs needed to use the APIs.

Overview of the JWT Setup Flow ⫘

JWT Flow Diagram

Generating a Secure Set of Keys ⫘

The key format that we require for your JWT is ECDSA keys using curve secp521r1.

As an example, you can generate these using the following openssl commands, but make sure to adapt this to your own key management policy so that they are handled in a secure way (in this example the private key will be generated on disk, in the directory that you are in).

openssl ecparam -genkey -name secp521r1 -noout -out mgt-api-private.pem

openssl ec -in mgt-api-private.pem -pubout -out mgt-api-public.pem

These commands will need to be repeated for the impersonation API to obtain a secondary set of public/private keys.

Send the Public Key File to Secureworks ⫘

Once you’ve managed to generate the set of keys, send us the public part only. In the above example that would be the license-api-public.pem file.

You can send this keypart directly by email to vdr@secureworks.com.

Obtain an Issuer and CID from Secureworks ⫘

Once obtained, we will set up your public key file on our end, and generate two specific base64-encoded data elements that you will need to use in your code as part of your token signature mechanism. These two elements are the issuer (very long) and the CID (relatively short).

Use the Issuer and CID to Sign API Messages ⫘

Using JWT is well documented with many language-specific examples out there.

The following very basic example is provided in Python as a starting mechanism for you to validate your use case before implementing it in your production system.

Note that there are two examples, one for each API (impersonation API and management API), with distinct parameters and keys.

Example Using the Impersonation API ⫘

import jwt

# Configuration
with open("/path/to/impersonation-api-private.pem", "r") as fp:
    sign_key = fp.read()
issuer = "<Base 64 string provided by Secureworks>"
client_id = "<Base 64 string provided by Secureworks>"
instance_name = "<your instance name>" # Instance name is the subdomain in your URL
impersonation_user_id = 123 # Specific user id we will perform the request as (impersonate)

token = jwt.encode({
    "iss": issuer,
    "iat": time(),
    "exp": time() + 60,
    "aud": instance_name,
    "sub": "user:" + impersonation_user_id,
    "cid": client_id,
    "scp": ["read_only", "full_access"],
}, sign_key, algorithm="ES512").decode("utf-8")

# ...

headers = {"Authorization": f"Bearer {token}"}

# Do the request

The API Endpoints that can be targeted are exactly the same as provided in the Swagger documentation file of your own instance, accessible at

https://<YOUR INSTANCE>.vdr.secureworks.com/api/v2/spec#/