For DAST profiles, configure authentication under **Settings \> Scan configuration \> Authentication**. For AI Pentesting, see [Authentication Setup](). Credentials and other string fields in a profile can use plain-text and secret organization [Variables]() as `${KEY}` instead of a literal value. ## 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. > [!NOTE] > > **The Mechanics of HTTP Authentication** > > Authentication is generally server-based, using client-provided data, that can be injected into various parts of an HTTP request: > > - Headers > - Cookies > - Body > - Query parameters ## 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: ```yaml 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: ```yaml 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. > [!TIP] > > **When to Use `lifetime`** > > Use `lifetime` when your API issues tokens that expire after a fixed duration (for example 1800 seconds / 30 minutes). Set it shorter than the token's validity period to refresh credentials for later requests. ### Example: Setting a 30-Minute Credential Lifetime ```yaml 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. > [!NOTE] > > **Default Behavior** > > When `lifetime` isn't set, API DAST can still repeat authentication if the application repeatedly rejects a user's credentials. Set `lifetime` when you need to control how often Escape refreshes credentials. ## 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`. ```text 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. > [!WARNING] > > **Compatibility With Multi-User Testing** > > The `multi_user_is_fallback` option is **incompatible with multi-user testing**.\\ By default, `multi_user_is_fallback` is set to `false`. **Example configuration:** ```yaml 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.