OAuth Authz Code Browser 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 or when maximum security is needed.

Security: This flow is the most secure OAuth 2.0 grant type as it never exposes user credentials to the client application and includes PKCE protection against authorization code interception attacks.

Use Cases: Ideal for web applications, mobile apps, and any scenario where you need to authenticate users through third-party OAuth providers (Google, GitHub, Auth0, etc.) while maintaining the highest security standards.

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
    login_timeout: 30
    redirect_uri: https://your-app.com/callback
    use_pkce: true
    scopes:
    - read
    - write
    users:
    -   username: user1
        main_user: false
        password: pass1
    -   username: user2
        main_user: false
        password: pass2
    -   username: user3
        main_user: false
        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
`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¶

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
`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
`timeout`	`integer`	`30`	Timeout in seconds for executing the click action

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
`timeout`	`integer`	`30`	Timeout in seconds for executing the input filling action
`value` *	`string`		The value to fill in the field

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
`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 authentified 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 authentified requests.
`main_user`	`boolean`	`false`	When running a frontend DAST 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`,`FillAction`,`FillTOTPAction`,`FocusPageAction`,`GotoAction`,`SelectAction`,`SleepAction`,`SolveCaptchaAction`,`WaitElementAction`,`WaitTextAction`]`		A list of actions to perform on the browser after the login.
`query_parameters`	`Dict[string, string]`	`null`	Optional query parameters injected during the authentication process and in authentified requests.
`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
`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