OAuth Authz Code Authentication with Escape¶

Description¶

The 'OAuth Authorization Code Browser' preset implements the OAuth 2.0 Authorization Code grant type (RFC 6749, Section 4.1):

Authorization Endpoint: Users are automatically redirected to the OAuth provider's authorization server where they authenticate.
Browser Automation: The system automatically fills in user credentials and handles the authorization flow without user interaction.
Code Exchange: Authorization codes are automatically extracted from the redirect URI and exchanged for access tokens.
PKCE Support: Implements Proof Key for Code Exchange (RFC 7636) for enhanced security by default.
Token Management: Automatically handles access tokens and refresh tokens, injecting Bearer tokens into authenticated requests.

Performance Note: This authentication method requires browser automation to handle the interactive authorization flow, making it less efficient than API-only methods like OAuth Client Credentials or Resource Owner Password Credentials that use only programmatic HTTP requests. Use this method when the OAuth provider requires user interaction.

Use Cases: Use this preset to authenticate users through third-party OAuth providers, such as Google, GitHub, or Auth0.

Examples¶

presets:
-   type: oauth_authz_code_browser
    authorization_url: https://auth.example.com/oauth/authorize
    token_url: https://auth.example.com/oauth/token
    client_id: your_client_id
    client_secret: your_client_secret
    redirect_uri: https://your-app.com/callback
    scopes:
    - read
    - write
    users:
    -   username: user1
        password: pass1
    -   username: user2
        password: pass2
    -   username: user3
        password: pass3
        scopes:
        - admin

Extensive Configuration¶

Property	Type	Default	Description
`authorization_url` *	`string`		The URL of the OAuth 2.0 authorization endpoint where users will be redirected to login
`client_id` *	`string`		The client ID to use for the OAuth requests
`client_secret` *	`string`		The client secret to use for the OAuth requests
`login_timeout`	`integer`	`30`	Timeout in seconds to wait for the login process to complete
`logout_detection`	BrowserLogoutDetectionConfig		Configuration for automatic post-login logout detection during browser authentication.
`redirect_uri` *	`string`		The redirect URI registered with the OAuth provider. The authorization code will be extracted from this callback.
`scopes`	`List[string]`	`null`	Default scopes to request. Can be overridden per user.
`token_url` *	`string`		The URL of the OAuth 2.0 token endpoint to exchange authorization codes for tokens
`type`	`Const[oauth_authz_code_browser]`	`oauth_authz_code_browser`
`use_pkce`	`boolean`	`true`	Whether to use PKCE (Proof Key for Code Exchange) for enhanced security. Recommended for public clients.
`users` *	`List[`OAuthAuthorizationCodeBrowserUserPreset`]`		A list of users to authenticate

Objects¶

BrowserLogoutDetectionConfig¶

Configuration for verifying that a browser login really resulted in an authenticated session.

Property	Type	Default	Description
`enabled`	`boolean`	`true`	If true, browser-based authentication will review the post-login page to detect logout or login failure.
`instructions`	`string`		Optional natural-language guidance for the post-login logout detection step. Use it to describe what a healthy logged-in state looks like, which redirects or dialogs are expected, and what signals should be treated as logout or login failure.

CheckAction¶

Property	Type	Default	Description
`action`	`Const[check]`	`check`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`locator` *	`string`		The Playwright Locator to select the checkbox to check
`select_first_if_multiple`	`boolean`	`false`	Whether to select the first element if multiple elements are found. If false, an error will be raised.
`timeout`	`integer`	`30`	Timeout in seconds for executing the check action

ClickAction¶

Property	Type	Default	Description
`action`	`Const[click]`	`click`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`locator` *	`string`		The Playwright Locator to select the element to click on
`select_first_if_multiple`	`boolean`	`false`	Whether to select the first element if multiple elements are found. If false, an error will be raised.
`timeout`	`integer`	`30`	Timeout in seconds for executing the click action

ClickMailMagicLinkAction¶

Property	Type	Default	Description
`action`	`Const[click_mail_magic_link]`	`click_mail_magic_link`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`email_address` *	`string`		The email address where the magic link will be sent.\nMust be a valid scan inbox address matching {alias}.{mailboxId}@scan.escape.tech. The full organization UUID suffix is still accepted for existing configurations. Alias: 1-27 ASCII letters, digits, and hyphens; dots allowed only between characters.
`new_page`	`boolean`	`false`	Whether to create a new page for the navigation or remain on the current page
`timeout`	`integer`	`60`	The timeout (seconds) to wait for the page to load

FillAction¶

Property	Type	Default	Description
`action`	`Const[fill]`	`fill`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`auto_submit`	`boolean`	`false`	Whether the form should be automatically submitted after the fill action
`locator` *	`string`		The Playwright Locator to select the field to fill
`one_by_one`	`boolean`	`false`	Whether the field should be typed one character by one character, like a TOTP code
`select_first_if_multiple`	`boolean`	`false`	Whether to select the first element if multiple elements are found. If false, an error will be raised.
`timeout`	`integer`	`30`	Timeout in seconds for executing the input filling action
`value` *	`string`		The value to fill in the field

FillMailTOTPAction¶

Property	Type	Default	Description
`action`	`Literal[fill_mail_totp, fill_email_totp]`	`fill_email_totp`	Use `fill_email_totp`. `fill_mail_totp` is deprecated and can be removed in the future.
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`auto_submit`	`boolean`	`false`	Whether the form should be automatically submitted after the fill action
`email_address` *	`string`		The email address where the TOTP code will be sent.\nMust be a valid scan inbox address matching {alias}.{mailboxId}@scan.escape.tech. The full organization UUID suffix is still accepted for existing configurations. Alias: 1-27 ASCII letters, digits, and hyphens; dots allowed only between characters.
`locator` *	`string`		The Playwright Locator to select the field to fill
`one_by_one`	`boolean`	`false`	Whether the field should be typed one character by one character, like a TOTP code
`select_first_if_multiple`	`boolean`	`false`	Whether to select the first element if multiple elements are found. If false, an error will be raised.
`timeout`	`integer`	`30`	Timeout in seconds for executing the input filling action

FillTOTPAction¶

Property	Type	Default	Description
`action`	`Const[fill_totp]`	`fill_totp`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`auto_submit`	`boolean`	`false`	Whether the form should be automatically submitted after the TOTP code is filled
`locator` *	`string`		The Playwright Locator to select the field to fill the TOTP code in
`secret` *	`string`		The secret to generate the TOTP code from

FocusPageAction¶

Property	Type	Default	Description
`action`	`Const[focus_page]`	`focus_page`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`url_pattern` *	`string`		The pattern to find in the URL to focus on a page. Should be a regex allowing to match the page using Python `re.findall()`.

GotoAction¶

Property	Type	Default	Description
`action`	`Const[goto]`	`goto`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`new_page`	`boolean`	`false`	Whether to create a new page for the navigation or remain on the current page
`timeout`	`integer`	`60`	The timeout (seconds) to wait for the page to load
`url` *	`string`		The URL to navigate to

OAuthAuthorizationCodeBrowserUserPreset¶

Property	Type	Default	Description
`allow_failure`	`boolean`	`false`	If false, authentication failure for this user will fail the scan. Ignored for the main user: failures for main user are always fatal.
`basic`	`string`	`null`	The basic to attach Reach the Login Page and attack to the HTTP requests sent for this user.
`cookies`	`Dict[string, string]`	`null`	Optional cookies injected during the authentication process and in authenticated requests.
`digest`	`string`	`null`	The digest to attach Reach the Login Page and attack to the HTTP requests sent for this user.
`headers`	`Dict[string, string]`	`null`	Optional headers injected during the authentication process and in authenticated requests.
`main_user`	`boolean`	`false`	When running a WebApp Testing scan, this indicates that the scanner must use this user when crawling. There must be only one main user per scan. If none is provided, a random user will be selected.
`password` *	`string`		The password of the user for the authorization server.
`post_login_actions`	`List[`CheckAction`,`ClickAction`,`ClickMailMagicLinkAction`,`FillAction`,`FillMailTOTPAction`,`FillTOTPAction`,`FocusPageAction`,`GotoAction`,`SelectAction`,`SleepAction`,`SolveCaptchaAction`,`WaitElementAction`,`WaitTextAction`]`		A list of actions to perform on the browser after the login.
`pre_login_actions`	`List[`CheckAction`,`ClickAction`,`ClickMailMagicLinkAction`,`FillAction`,`FillMailTOTPAction`,`FillTOTPAction`,`FocusPageAction`,`GotoAction`,`SelectAction`,`SleepAction`,`SolveCaptchaAction`,`WaitElementAction`,`WaitTextAction`]`	`null`	A list of actions to perform on the browser before the login. Useful for edge cases like accepting cookies.
`query_parameters`	`Dict[string, string]`	`null`	Optional query parameters injected during the authentication process and in authenticated requests.
`role`	`string`	`null`	The role of the user (for example, admin or user).
`scopes`	`List[string]`	`null`	A list of scopes to request for the user. If not specified, no scope will be requested.
`username` *	`string`		The username of the user.

SelectAction¶

Property	Type	Default	Description
`action`	`Const[select]`	`select`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`locator` *	`string`		The Playwright Locator to select the dropdown to select from
`select_first_if_multiple`	`boolean`	`false`	Whether to select the first element if multiple elements are found. If false, an error will be raised.
`timeout`	`integer`	`30`	Timeout in seconds for executing the click action
`value` *	`string`		The value to select

SleepAction¶

Property	Type	Default	Description
`action`	`Const[sleep]`	`sleep`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`seconds` *	`number`		The time to sleep in seconds, between 0 and 40 seconds

SolveCaptchaAction¶

Property	Type	Default	Description
`action`	`Const[solve_captcha]`	`solve_captcha`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`auto_submit`	`boolean`	`false`	Whether the form should be automatically submitted after the captcha is filled
`locator` *	`string`		The Playwright Locator to select the captcha field to fill

WaitElementAction¶

Property	Type	Default	Description
`action`	`Const[wait_element]`	`wait_element`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`locator` *	`string`		The selector to wait for
`timeout`	`number`	`10`	The timeout (seconds) to wait for the element to be visible

WaitTextAction¶

Property	Type	Default	Description
`action`	`Const[wait_text]`	`wait_text`
`allow_failure`	`boolean`	`false`	Allow this action to fail without breaking authentication, defaults to False.
`timeout`	`number`	`10`	The timeout (seconds) to wait for the text to be visible
`value` *	`string`		The text to wait for until visible, case-insensitive