Authentication

For DAST profiles, configure authentication under Settings > Scan configuration > Authentication. For AI Pentesting, see Authentication Setup.

Understanding Authentication¶

Authentication, a cornerstone in programming, involves verifying the identity of a user or process. This process is fundamental for secure and authorized access.

Authentication Framework¶

Escape's authentication framework uses these principles:

1. Workflows: Every authentication process, from HTTP requests to RPC procedures or web form submissions, consists of a series of server interactions.
2. Credential Extraction: Authentication data (most of the time, a token) is generated from server responses during these interactions.
3. Credential Injection: Credentials are essentially a set of extra parameters to be included in subsequent requests.
4. Logging: Logs show each step of the authentication process to help you troubleshoot your configuration.
5. Session management: Escape Authentication is able to manage sessions, and to store the authentication data extracted from the responses of the operations of a procedure. This data can then be reused in the requests of the procedure, or in the requests of other procedures.
6. Refresh: When storing the authentication data, Escape Authentication can automatically identify the time to live of the data, and automatically refresh it when it expires or rotates. It's also possible to manually declare the generated token's TTL in the configuration file for each user.

Authentication Options in Escape¶

Escape offers multiple methods for managing authentication:

Public Authentication¶

Use public authentication to test access as an unauthenticated user.

It's defined as follows:

users:
  - name: public

If no authentication is defined, the public authentication will be used by default.

Standard Workflows¶

For common authentication methods, Escape provides Standard Authentication Workflow Presets, including Basic, HTTP, Headers, Digest, GraphQL, cURL, cURL Sequence, OAuth (Client Credentials, ROPC, and Authorization Code), AWS Cognito, Browser Agent, and Browser Actions. Detailed instructions for these presets are available in the "Preset" Section.

Advanced Workflows¶

For more complex needs, users can combine multiple workflows, like Playwright and HTTP Requests, to create advanced authentication procedures. See Advanced Workflows for examples.

Validating Your Authentication¶

By default, Escape will validate the authentication process by injecting the credentials generated into a request and checking the response. If you want to skip this step, you can add the validation: false parameter to the authentication configuration.

Here's an example of a configuration without validation:

presets:
  - type: headers
    users:
      - username: user1
        headers:
          Authorization: Bearer user1Token
validation: false

Token Lifetime and Refresh¶

Escape reuses generated credentials during a scan. For APIs that issue short-lived tokens with an expiration date, set lifetime to control when Escape obtains fresh credentials.

Use lifetime to set the token max duration (in seconds): how long Escape reuses generated credentials before it re-executes the authentication procedure.

Example: Setting a 30-Minute Credential Lifetime¶

presets:
  - type: http
    request:
      url: https://api.example.com/auth/login
      method: POST
      headers:
        Content-Type: application/json
      body: '{"username": "{{ username }}", "password": "{{ password }}"}'
    injections:
      - location: header
        key: Authorization
        prefix: "Bearer "
        variable: token
    extractions:
      - location: body
        key: access_token
        name: token
    users:
      - username: user@example.com
        password: SecurePassword123!
lifetime: 1800

In this example, lifetime is set to 1800 seconds (30 minutes). After that duration, Escape re-executes the authentication procedure when credentials are next requested.

Overall Structure of an Authentication Configuration¶

See the Authentication Reference for each section and per-user fields, including allow_failure, main_user, role, variables, and user_instructions.

procedures:
  description: The list of authentication procedures to rely on when authenticating users

presets:
  description: A list of presets used to easily generate procedures and users automatically following common authentication standards

users:
  description: List of users that multiauth will generate authentications for.

lifetime:
  description: The duration (in seconds) for which Escape reuses generated credentials before refreshing them

proxy:
  description: An optional global proxy used for all HTTP requests

validation:
  description: A flag to enable or disable the generated tokens validations. Set this to false to skip the validation. Set to true by default

multi_user_is_fallback:
  description: Treat configured users as fallback options. Defaults to false

is_parallel_auth_validation:
  description: Authenticate users in parallel during configuration validation. Defaults to true

Authentication Users Fallback¶

Configure multiple users as fallback options to authenticate with the first available account.

Enable fallback mode by setting multi_user_is_fallback: true in your authentication configuration. When enabled, Escape will attempt authentication with each user in the order they are listed, stopping at the first successful authentication.

Example configuration:

presets:
  - type: browser_agent
    users:
      - password: user1
        username: user1@test.com
      - password: user2
        username: user2@test.com
      - password: user3
        username: user3@test.com
      - password: user4
        username: user4@test.com
    login_url: https://example.com/login
    logged_in_detector_text: Login successful
multi_user_is_fallback: true

How it works:

• Authentication attempts start with the first user (user1@test.com) and proceed sequentially through the list
• The process stops immediately when a successful authentication is achieved
• If all users fail, the authentication process fails and the scan won't proceed with authenticated requests

Example scenario:

If only user3@test.com is active and valid, Escape will attempt authentication with user1@test.com (fails), then user2@test.com (fails), and finally user3@test.com (succeeds). The scan will then proceed using user3@test.com credentials.