# 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

```yaml
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](<#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](<#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](<https://playwright.dev/docs/api/class-page#page-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](<https://playwright.dev/docs/api/class-page#page-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](<https://github.com/scan> "GitHub User: 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](<https://playwright.dev/docs/api/class-page#page-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](<https://github.com/scan> "GitHub User: 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](<https://playwright.dev/docs/api/class-page#page-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](<https://playwright.dev/docs/api/class-page#page-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](<#CheckAction>)`,`[ClickAction](<#ClickAction>)`,`[ClickMailMagicLinkAction](<#ClickMailMagicLinkAction>)`,`[FillAction](<#FillAction>)`,`[FillMailTOTPAction](<#FillMailTOTPAction>)`,`[FillTOTPAction](<#FillTOTPAction>)`,`[FocusPageAction](<#FocusPageAction>)`,`[GotoAction](<#GotoAction>)`,`[SelectAction](<#SelectAction>)`,`[SleepAction](<#SleepAction>)`,`[SolveCaptchaAction](<#SolveCaptchaAction>)`,`[WaitElementAction](<#WaitElementAction>)`,`[WaitTextAction](<#WaitTextAction>)`]` |  | A list of actions to perform on the browser after the login. |
| `pre_login_actions` | `List[`[CheckAction](<#CheckAction>)`,`[ClickAction](<#ClickAction>)`,`[ClickMailMagicLinkAction](<#ClickMailMagicLinkAction>)`,`[FillAction](<#FillAction>)`,`[FillMailTOTPAction](<#FillMailTOTPAction>)`,`[FillTOTPAction](<#FillTOTPAction>)`,`[FocusPageAction](<#FocusPageAction>)`,`[GotoAction](<#GotoAction>)`,`[SelectAction](<#SelectAction>)`,`[SleepAction](<#SleepAction>)`,`[SolveCaptchaAction](<#SolveCaptchaAction>)`,`[WaitElementAction](<#WaitElementAction>)`,`[WaitTextAction](<#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](<https://playwright.dev/docs/api/class-page#page-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](<https://playwright.dev/docs/api/class-page#page-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 |