The API Authentication Helper Plugin is used to retrieve 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

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 Credentials to the Scan Configuration
3. Configure the API Authentication Helper Plugin Configuration
4. Enter the Values Appropriate for Your API's Authentication Mechanism
5. Save your Scan Configuration

Add your API's root URL to the scan targets

• Web Application Scanner Settings
  • Targets

Add Credentials to the Scan Configuration

• Web Application Scanner Settings
  • Authenticated Scanning

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 hard-coding the secret in the plugin configuration since it avoids potential for secrets being exposed in logs.

Configure the API Authentication Helper Plugin Configuration

• Web Application Scanner Settings
  • Plugins
    • API Scanning
      • API Authentication Helper
        • Configuration

When populating these settings you can refer to the credentials entered in the previous step using the placeholders {username} and {password}.

Enter the Values Appropriate for Your API's Authentication Mechanism

The "JSON Request Property To Apply Token" field 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.  

Save your Scan Configuration

Give you scan a name, save it, and do a test run.  Authenticated API scanning is one of the most complex uses of the AppCheck scanner; if you find yourself running in to problems our support team will be happy to help.

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