Configuring API Call Authentication
Deprecation notice
The API call authentication type is deprecated. Your existing authentication objects of this type are currently working, and later will be converted in to the Custom API authentication objects automatically.
The API call authentication method is designed to enable Bright to reach an authenticated resource by sending API requests with customized request queries, headers and bodies, requiring the use of dynamic information between steps (such as CSRF tokens).
Note
This topic describes only how to fill in fields specific for API call authentication (the Setup tab). For general steps, see Creating Authentication.
Note
Before following the instructions below, ensure that your application and authenticated resources are accessible to the Bright engine, either directly from the Internet or via the Repeater.
From the Authentication type dropdown list, select API call and then proceed to the authentication setup.
Authentication setup
In this section, set up a valid authentication request to be sent to the end-point API by completing the provided fields.
| Field | Guidelines |
|---|---|
| Method | Enter the HTTP method of the relevant API end-point. |
| URL | Enter the URL of the relevant API end-point. |
| Body | Enter the HTTP request body to use with the request sent to the API end-point, for example:{“user”: “foo”, “pass”: “bar”}’. |
| Extract from | Select where in the responses the correct authentication token should be extracted from. |
|
Select if you need the authentication token to be extracted from the response header. |
|
Enter the name of the header to extract the authentication token from. |
|
Select if you need the authentication token to be extracted from the response body. |
| Authenticated token extraction regex |
Enter the Regex pattern that extracts the authentication token from the specified location. Pro Tip: Make sure the specified Regex captures ONLY the token itself, and not any additional parts of the string such as prefix, suffix, delimiter, padding, etc. |
| Token encoder | Select any encoder that you need to use on the token itself, for example Base64. |
| Embed in | Select where in the subsequent authenticated requests the authentication token should be embedded in to. |
|
Select if you need the authentication token to be embedded in to the request header. |
|
Enter the name of the header to embed the authentication token in to. |
|
Select if you need the authentication token to be embedded in to the request body. |
|
Select the content type of the request body. Note: Currently only `application/json` is supported. |
|
Enter the exact path to the object to be used in the requests sent to the API end-point. |
| Token template string |
Enter the expected token and final pattern to be embedded in to the end-point request header or body. Pro Tip: The required syntax is to have the `{{token}}` string in the field, along with any needed prefixes/suffixes. The `{{token}}` part will be replaced with the extracted token from the authentication response. |
Maximum number of redirects to follow | Enter the maximum number of redirections that the NeiraLegion should follow during the authentication process. |
| Additional headers |
(Optional) Select an additional header that you need to use for each request and enter its value. For example, additional cookies that might be needed for the authentication, such as host-related metadata. To replace or append the selected header before sending each request, select the corresponding option from the Merge strategy dropdown list. Pro Tips:
|
- You can add as many header as you need by clicking + Add header at the bottom of the Authentication Setup section.
- To delete a header, click
next to the corresponding header field.
Valid authentication response
In this section, select the options you want to use during the application scanning to determine that the authenticated resource has been reached. The options define how the application responds in case a full authentication flow passes successfully.
| Field | Guidelines |
|---|---|
| Detect using Response STATUS | Enter the HTTP response status that will tell you about the authentication success. |
| Detect using Response HEADER pattern | Enter the header name and Regex pattern that will help you identify the authentication success. |
| Detect using Response BODY pattern | Enter the body pattern that will help you identify the authentication success. |
Authentication triggers
In this section, select the options you want to use during the application scanning to determine if the authentication flow is no longer valid and the authenticated resources cannot be reached. The options define how the application responds in case the authentication flow fails.
| Field | Guidelines |
|---|---|
| Detect using Response patterns | Select if your application explicitly indicates the authentication session expiration in the body or headers, or using status codes. |
|
Enter the HTTP response status that will tell you about the authentication failure. |
|
Enter the header name and Regex pattern that will help you identify the authentication failure. |
|
Enter the body pattern that will help you identify the authentication failure. |
| Detect using Request patterns | Select if your application does not provide any explicit indication in the body or headers when the session expires, but the client-side code redirects you to the login page, for example, based on absence of cookies or cookies expiration. In this case the only way to detect the re-login requirement is by detecting the redirect to the login URL. |
|
Enter the URL pattern that will help you identify the authentication failure. |
Note
Bright allows testing a scan before saving it. For details, see the Testing Authentication.
Updated over 1 year ago