Feature Focus: API/CLI User Token Management

20 January 2021

CAST Highlight’s API is now used extensively across our user base for various scenarios such as building custom reports or integrating our insights into third-party products (e.g., MEGA, Alphabet, Azure DevOps, and Atlassian JIRA to name a few). Hence, there was a need for a more secure and flexible way to manage user access. This article describes how to create, manage, and use OAuth2 tokens to work with the CAST Highlight API or the command line interface (CLI).

What is OAuth2?

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0 focuses on client developer simplicity while providing specific authorization flows for web applications, desktop applications, mobile phones, etc. The OAuth 2.0 authorization framework is a protocol that allows a user to grant a third-party web site or application access to the user’s protected resources, without necessarily revealing their long-term credentials or even their identity.

CAST Highlight users can now authenticate to use the API (or CLI) by providing them with an anonymous token that is sealed by the company tenant identifier and a secret pass phrase that only the user knows and defines.

This article describes how to manage and use these tokens in CAST Highlight.

How to enable, create and revoke user tokens

The User Token Management feature is enabled at the portfolio level. As a Portfolio Manager being active at the root-level of the portfolio, navigate in the CAST Highlight portal to COMPANIES > Token Management:

Switch “on” the feature for the entire portfolio
Define a secret pass phrase (min. 10 characters, max. 255)
Define the duration (in minutes) of the policy for user tokens that have been created within your portfolio
Click “Apply”

This feature must be activated for each client by CAST. Therefore, if the portal does not allow you to activate the token authentication mode, please contact the support team or your preferred CAST consultant.

Once the feature is active, every user from your portfolio can create a personal token. To do so, from the User menu on the right, click on “Generate Access Token”. The next section describes how it is used.

As a Portfolio Manager, you can view other users’ token information on the Token Management page in case they ever need to be revoked. To revoke a token (i.e. the token will be disabled for using the API and/or the CLI), click on the trash icon.

How to use tokens with the API and the CLI

Here is how to use a token with CAST Highlight’s API and CLI:

API user authentication: Switch to the token authentication mode by replacing “Basic {base64(login:password)}” with “Bearer {your_token}” as shown below. Other than this change, the API will work exactly as before

CLI user authentication: User authentication is only needed when you want to automatically upload scan results of an application to the CAST Highlight portal. In this case, replace either the –login –password pair or the –basicAuth option with the new –tokenAuth as shown in the example below. The rest of the upload options (–companyId, –serverUrl, –applicationId) remain unchanged

java -jar HighlightAutomation.jar --sourceDir "c:\temp\src" --workingDir "c:\temp\hlresults" --companyId {companyId} --serverUrl https://rpa.casthighlight.com --applicationId 12345 --tokenAuth {your_token}

/!\ Make sure you’re using a recent version of the command line with this feature enabled.

How to create/renew tokens from the API

User tokens for a given user can be created or renewed programmatically from the API by using the following endpoint and Basic authentication:

POST (or GET) {serverUrl}/auth/oauth/authorize

Note that the maximum validity value you can set for tokens is 1,000,000 minutes (approximately 2 years).

Finally, if you need to renew tokens for all users, de-activating then re-activating the token feature will reset tokens for everyone.

Service tokens and SAML users?

If you need a token that will be used for frequent automated scans or API requests, we recommend to generate these tokens from a classic user as they are generally more stable than SAML user based tokens over time (e.g., changes in your idP or SAML configuration).