The API Authentication Helper Plugin is used to retrieve tokens in order to authorise API calls. It is a useful tool in situations 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

To use the API Authentication Helper plugin to add authentication to your API scan, follow these steps.

1. Add your API's root URL to the scan targets
2. Add a username and password to the scan configuration under
   Web Application Scanner Setting
   -> Authenticated Scanning
   

   NOTE: You can use the password field for any sort of secret value even if it is not referred to as a password.  This is preferable to hardcoding the secret in the plugin configuration since it avoid potential for secrets being exposed in logs.

3. Open the API Authentication Helper plugin configuration under
   Web Application Scanner Settings
   -> Plugins
   -> API Scanning
   -> API Authentication Helper
   -> Configuration.
4. Enter the values appropriate for your API's authentication mechanism.
5. Save your scan configuration

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, open the plugin's Configuration tab and fill in the fields as follows:

Security Token Prefix

Bearer

Request Method

POST

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 the the values for username and password entered in the scan configuration.

JSON Key to Extract

access_token

Header To Apply Token

Authorization

Forced Token Expiry Seconds

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

3600

Custom Headers

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

Content Type

application/json

Authentication URL

https://example.com/api/token

Authentication Scope

https://example.com/api/

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.

Expected Confirm String

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

Confirm URL

https://example.com/api/users

Confirm Request Method

GET

Confirm Request Content Type

application/json