These docs are for v1.1. Click to read the latest docs for v1.2.

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.

1564
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.
  • Header
Select if you need the authentication token to be extracted from the response header.
    Header name
Enter the name of the header to extract the authentication token from.
  • Body
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.
  • Header
Select if you need the authentication token to be embedded in to the request header.
    Target header name
Enter the name of the header to embed the authentication token in to.
  • Body
Select if you need the authentication token to be embedded in to the request body.
    Content type
Select the content type of the request body.

Note: Currently only `application/json` is supported.
    XPAth
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:
  • If your application uses cookies that are set via the Set-Cookie header in the response, then you do not need to extract and reuse the cookies. Any Set-Cookie header will be automatically used during authentication.
  • MFA required on initial IP login may be handled using a cookie value. For that, you need to identify which cookie holds the completed MFA/2FA and include a valid cookie as a part of your authentication object.
  • 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.

1556
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.

1410
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.
  • Detect using Response STATUS
Enter the HTTP response status that will tell you about the authentication failure.
  • Detect using Response HEADER pattern
Enter the header name and Regex pattern that will help you identify the authentication failure.
  • Detect using Response BODY pattern
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.
  • Detect using Request URL pattern
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.