Authentication

Advanced Authentication for security scans can be configured in the Settings > Authentication section of your Application.

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.

A Versatile Framework for Universal API Authentication¶

Escape's authentication feature is underpinned by key principles, forming a robust and adaptable authentication engine:

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. Comprehensive logging: These logs provide detailed insights into each step of the authentication process, aiding users in fine-tuning their authentication workflows. The logs are designed to be clear and informative, ensuring that both security engineers and developers can easily understand and utilize them for optimal 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 is 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¶

If you want to create a user that is not authenticated, you can use the public authentication.

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, REST, Digest, GraphQL, OAuth, AWS Cognito, Playwright, etc. 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. This offers unmatched flexibility and is detailed in the "Advanced" section.

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 is an simple example of a configuration without validation:

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

Token Lifetime and Refresh¶

By default, Escape keeps the generated authentication token valid for the entire duration of the scan. However, some APIs issue short-lived tokens with an expiration date, and you need Escape to refresh the token periodically to keep your scan authenticated.

The lifetime parameter lets you control the token max duration (in seconds) before Escape re-executes the authentication procedure to obtain a fresh token. This is the token frequency refresh: how often Escape will discard the current token and generate a new one.

Example: refreshing the token every 30 minutes¶

presets:
  - type: http
    url: https://api.example.com/auth/login
    method: POST
    headers:
      - name: Content-Type
        values:
          - 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, the lifetime is set to 1800 seconds (30 minutes). Every 30 minutes, Escape will re-execute the authentication procedure to get a new token, ensuring the scan never operates with an expired credential.

Overall structure of an authentication configuration¶

For detailed information on each section, please refer to the respective sections in the reference documentation.

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 a generated token remains valid before Escape triggers a refresh

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

Authentication Users Fallback¶

When you have multiple users that may be unstable or intermittently unavailable, you can configure authentication to use them as fallback options. This ensures your scans can proceed even if some users fail authentication.

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
    auto_extraction_urls: []
    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 will not 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.

Index¶