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.
- Add Credentials to the Scan Configuration
- Configure the API Authentication Helper Plugin Configuration
- Enter the Values Appropriate for Your API's Authentication Mechanism
- Save your Scan Configuration
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
- API Authentication Helper
- API Scanning
- Plugins
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
Comments
0 comments
Article is closed for comments.