The API Authentication Helper Plugin is used to retrieve and refresh tokens in order to authenticate API calls. It is a useful tool in situations where you wish to scan an API without scanning a corresponding web application, necessitating direct calls to the API to authenticate.

How to Configure the Plugin

API Authentication Helper plugin is built into API Workspace. To use it, please follow the steps in How to Configure API Workspaces guide. When you reach the Credentials phase in the Workspace Wizard, you can choose API Auth Helper from the drop-down menu as so:

You will see the plugin configuration options after selecting it.

Populate required fields with valid data as per example below.

Example

As an example, take the hypothetical endpoint https://example.com/api/token which is called to obtain a bearer token.

This curl command shows hows to call the endpoint:

curl -X POST 'https://example.com/api/token' \
-H 'Content-Type: application/json' \
-d '{"client_id":"username","secret":"password",”grant_type”:”client_credentials”}'

This returns the following, including the access token:

{"access_token":"eyJhbG...5RQXUg", "refresh_token":"cc6874...790640", "expires_in":900, "expires":"Sat, 23 Oct 2077 10:10:56 GMT"}

Authentication Options

In order to automate the above in the scanner using API Authentication Helper, fill in the fields as follows:

Authentication Scope

https://example.com/api/

Authentication URL

https://example.com/api/token

Content Type

application/json

Custom Headers

No customer header parameters are used in this example, but can be used to add such parameters as X-API-KEY

Forced Token Expiry Seconds

This is a default value. It’s recommended not to set this value lower than 500

3600

Header To Apply Token

Authorization

JSON Key to Extract

access_token

If there is no JSON key to extract and the response body is the token, then add body::text into this box.

JSON Request Property To Apply Token

Can be used to embed the authentication token within a JSON payload property, which can then be called/used in a subsequent field whilst configuring the API Authentication Helper, for example in the "Confirm Request Body" field.  

Request Body

This example uses the application/json content type:

{"client_id":"{username}","secret":"{password}",”grant_type”:”client_credentials”}

If it used the x-www-form-urlencoded content type the body might look like this:

client_id={username}&secret={password}&grant_type=client_credentials

NOTE: When the scan runs, {username} json and {password} will be replaced by the values for username and password entered in the API Authentication Helper in the API Workspace Wizard.

Request Method

POST

Security Token Prefix

Bearer

Confirming Authentication

These settings tell the scanner how to confirm if authentication was successful.  This is required so the scanner can identify when an access token stops being accepted, and so that a finding can be shown in the scan results to indicate whether authentication succeeded.

Confirm Request Content Type

application/json

Confirm Request Method

GET

Confirm URL

https://example.com/api/users

Expected Confirm String

A string that should appear in the response if the authorization was successful.