Docs

Add an Authentication Object

This page describes adding a new Authentication Object to a scan in the Bright web app.

Suggest Edits

Creating authentication

  1. From the menu in the left pane of the Bright app, select Authentications.
  2. In the Authentications pane, click + Create Authentication.
  1. In the Create authentication dialog, fill in the fields as described below in the following chapters.
  2. After filling in all the necessary fields, click "Create" in the bottom right corner of the Create Authentication dialog.

📘

Note:

  • All mandatory fields are marked with an asterisk (*).
  • Bright allows testing a scan before saving it. For details, see the Testing Authentication section below.

The Details tab

This chapter contains the basic settings of the authentication object, which will help you quickly find the related project and distinguish it from other authentication objects.

Specify the details of the authentication object you want to create.

FieldGuidelines
DescriptionEnter the authentication object description. For example, you can specify the application type or other information that helps you distinguish your created object.
ProjectSelect the project to attach an Authentication Object

Protected resource details

This chapter covers HTTP methods and validation URLs, explaining their role in verifying that regular calls work correctly and detecting re-authentication scenarios.

Provide the details of the authentication-protected resource.

FieldGuidelines
MethodSelect the HTTP method of an active tester end-point (authenticated resource)
Validation URLEnter the URL of the authenticated (protected) resource to test if the authentication scenario is configured correctly. The validation URL should be different from the authentication URL.
HeadersSelect an additional header to be replaced or appended before sending each request, for example, Authorization
BodyEnter the HTTP request body to be sent in the request sent, for example: {“user”: “foo”, “pass”: “bar”}
Maximum number of redirects to followEnter the maximum number of redirections that Bright should follow during the authentication process

Pro Tips: Select the checkbox Change redirected method to GET for the redirects with code 302, where the server expects the following methods to always be GET during redirects and not the original method that triggered the redirect
RepeaterIf you use a local Repeater to reach the scan target, select it from the dropdown list to connect it to the scan.

The Auth flow setup tab

This tab allows setting authentication details.

Select the required type from the Authentication type dropdown, and then configure the authentication details.

To learn how to configure a specific Authentication Object, follow the relevant links below.

Valid authentication types

The Re-auth triggers tab

This section provides options for application scanning to detect when the authentication flow is no longer valid, preventing access to authenticated resources. It defines how the application should respond if the authentication fails.

FieldGuidelines
Response statusResponse trigger. Select the checkbox and then enter the HTTP response status to tell you about the authentication failure.
Header patternResponse trigger. Select the checkbox and then enter the header name and Regex pattern, which will help you identify the authentication failure. For example, you can use a simple Regex pattern, such as index.
Body patternResponse trigger. Select the checkbox and then enter the body pattern that will help you identify the authentication failure. For example, this Regex pattern detects a body looking for a UUID in a sessionId parameter: sessionId: \"\\b(uuid:){0,1}\\s_([a-f0-9\\-]_){1}\\s\*\".
Page patternBrowser-based trigger. Select the checkbox and then specify CSS selector(s) or inner text selector(s) that match page element(s) to be used as logout indicator(s).
Request URL patternMixed trigger. Select the checkbox and then enter the URL pattern that will help you identify the authentication failure.

📘

Re-auth triggers logic

Response triggers are combined using AND, meaning all specified conditions (e.g., status 302 and header Location: login) must be true. The overall result is then combined with other triggers using OR.
For example, if you define Response Status 401 and Request URL pattern /login - the re-auth trigger will be a match if the Response Status equals to 401 OR the Request URL pattern is /login.

The Advanced tab

This page explains how to configure different types of One-Time Passwords (OTP) and set up authorized requests by adding custom headers, such as authentication cookies.

OTP-generation settings

OTP is a reliable way to increase an application's security by adding one-time passwords. It is often used in combination with a regular password as an additional tool for user authorization. Bright provides the following possibilities for use: Time-Based One-Time Password (TOTP), Hash-Based One-Time Password (HOTP), Google Authenticator (TOTP), and Email OTP.

📘

Note:

This tab is only available for Browser-Based Form Authentication , Custom API authentication flow and Manual Recorded Browser-Based Form Authentication.

  • Users are allowed to create up to 5 OTPs
  • There are no restrictions on types: for example, they can all be only one type
  • Users can rename each OTP if needed

To configure an OTP correctly, follow the steps below:

  1. Create an Authentication Object using Manual Browser-Based Form Authentication , Custom API authentication flow or Recorded Browser-Based Form Authentication.
  2. Open the Auth flow setup tab and insert the {{ auth_object.otps.<OTP_NAME> }} to all places needed. The Bright engine will interpret this placeholder into an existing token.
    1. Bright allows users to add this token to the following fields:
      1. URL
      2. Body
      3. Header Value
    2. For Manual Browser-Based form Authentication it is allowed to put the {{ auth_object.otps.<OTP_NAME }} into the Value field. The Name field should match your example.
    3. For Recorded Browser-Based form Authentication, open the recorded JSON file in a text editor, and change the data in the value line to this: {{ auth_object.otps.<OTP_NAME> }}.
  3. Go to the Advanced tab and select one of the OTP options:

  1. Enter the following parameters to continue:


  1. Name - can be modified to any name consisting of alphanumeric characters and underscore (_) only
  2. OTP type:
    1. Time-based one-time password (TOTP) - a temporary passcode generated by an algorithm that uses the current time of day as one of its authentication factors
    2. Hash-based one-time password (HOTP) - Hash-based message authentication code, based on a counter. See the Troubleshooting page to learn how to adjust the HOTP server.
    3. Google Authenticator (TOTP) - a time-based one-time password is a time-based OTP, the most popular algorithm used by Google Authenticator.
    4. Email OTP - a temporary passcode sent to a generated email and read by Bright web app to authorize test users. See the Email OTP article for more details.
  3. Secret key - a key that is provided by the target website and used to generate the OTP

    📘

    Note:

    When configuring the Google Authenticator OTP, the input key is often separeted by spaces. These spaces must be deleted before inserting the key in the Secret key field.

  4. Number of digits - a number of digits (from 1 to 8) used to generate the OTP's length
  5. Token duration - a time (in seconds) after which an OTP is regenerated (only available when TOTP is selected)
  6. Algorithm - an encryption algorithm, that contains three types of the cryptographic hash function, which produces a 160-bit, 256-bit, and 512-bit hash value accordingly.

Once everything is done, click on Test OTP generation to check everything is set up correctly. Generated code can be used for OTP adjustment on a target site/service.

Authorized requests setup (Custom Headers)

The Bright app now allows users to manually add a custom header to browser-based form authentication and -recorded one. As a result, users can cover complex non-standard headers to make protected resource tests possible.

📘

Note:

All existing templates, except those containing $faker, must have the auth_object context, if they do not already. To learn more about Faker.js data generator, see Generating mock data.

To use a custom header in the authorized requests, follow these steps:

  1. Go to the Advanced tab, the Authorized requests setup, and click Add header.

  1. Fill in the header name: x-auth.
    There are two merge strategies:
    • Replace - replaces the value without duplication
    • Append - adds the value to the end of the page

Select Replace merge strategy to continue.

  1. Fill in header value: {{ auth_object.any_stage.request.headers | get: '/x-auth'}}.

Click Test Authentication to make sure that no errors are produced.

Testing authentication

Preliminary authentication testing helps you verify if the authentication object has been configured correctly. This allows you to reveal the configuration issues timely, before running a scan.

To test your authentication object, at the bottom of the Create authentication dialog, click Test authentication.

The application displays the test results in a separate Test results tab.

  • A valid authentication object returns three success messages indicated in the relevant Test results sections:
    • Test Authentication Triggers provides the test request and response data.
    • Authentication call (fillForm #) provides a screenshot of the form filled by the engine per stage.
    • Authentication call (submitForm #) provides a screenshot of the authenticated page as evidence of the successful login.
    • Authentication call (Page Interaction Result) provides a screenshot, request and response of the post-login URL as evidence of the successful login.
    • Access Protected Resource provides the test request and response data.

In this case, you can save the configured object and add it to your scans.

  • If the test results include a failure message, go back to the object configurations and verify their correctness. Use the test request/response data to find a certain failure and fix it.

📘

Note:

The Bright engine only supports the set-cookie headers that are less than 4097 bytes. If the received header exceeds this limit, the engine will ignore the header and will not include it in the request/response data. Breaking the limit may also cause authentication object failure.


👍

Related Links:

Bright allows testing a scan before saving it. For details, see the Testing Authentication.

Updated 23 days ago