Here’s a cleaned, final version of your Browser-Based Authentication documentation with redundant data removed, grammar polished, and structured for clarity:

Browser-Based Authentication — ZAP Reference Guide

Browser-based authentication in ZAP emulates a user logging into a web application via a browser. This is useful for applications relying on session cookies or JWTs generated by the frontend.

1. YAML Configuration Overview

automation: true  # Must always be true

scope:
  entryUrls:
    # ⚠️ Must point to the frontend SPA page.
    # Browser-based authentication loads the login page from this URL.
    # If you set this to backend API, ZAP cannot detect username/password fields,
    # and authentication will fail in the report.  
    - "https://frontend.example.com"
  includePaths:
    - "https://frontend.example.com.*"
  excludePaths:
    - "https://frontend.example.com/logout.*"
    - ".*\.png"
    - ".*\.css"
    - ".*\.jpg"

headers:
  # Optional business headers. Remove if not needed.
  Customer-Type: "enterprise"
  App-Version: "1.0.0"

authentication:
  type: "browser"
  loginPageUrl: "https://frontend.example.com/login"

  # Optional verification using pollUrl
  # pollUrl: "https://frontend.example.com/api/profile"

  # Regex confirming successful login
  loggedInRegex: "Login Successful"
  loggedOutRegex: "403"

Additional Notes:

Entry URL must be the frontend SPA login page because ZAP will render this page in the headless browser to find login forms or buttons.
If backend API is set as entry URL, ZAP will fail to detect login fields and report “authentication failed” even if API authentication works via poll URL or response regex.
Include/Exclude paths can still contain backend API endpoints; they control what is spidered/scanned, not what URL is used for login detection or report generation.
loginPageUrl: Frontend login page; must be primary host in the context.
pollUrl: Recommended for SPA and multi-page apps; points to a protected endpoint.
loggedInRegex: Regex to confirm login success; only works if response contains a body.

2. Key Fields

Field	Meaning
`automation`	Must be `true` for automation.
`scope.entryUrls`	Starting URLs for crawling/spidering.
`scope.includePaths`	Regex patterns to include in scan.
`scope.excludePaths`	Regex patterns to exclude (e.g., logout URLs, static assets).
`headers`	Optional business headers for login requests.
`authentication.type`	Must be `browser` for browser-based login.
`loginPageUrl`	URL of the login page.
`pollUrl`	URL to verify authenticated session (optional).
`loggedInRegex`	Regex or keyword to validate login success.
`loggedOutRegex`	Regex or keyword to detect logged-out state.

3. Verification Methods

Method	When to Use	Notes
Autodetect	Server-rendered MPA pages	Works only for simple pages; unreliable for SPA
Response Regex	SPA frontend & backend same domain	Checks `loggedInRegex` in login response; fails for 302 redirects
Poll URL	SPA with backend on different domain, MPA, or 302 redirects	Most reliable; queries a protected endpoint and validates `loggedInRegex`

4. Browser Authentication Scenarios

Scenario	Setup	Notes
SPA, frontend & backend same domain	`loggedInRegex` only	Response type works; no `pollUrl` required
SPA, backend on different domain	`pollUrl` + `loggedInRegex`	Must poll protected endpoint; response type fails otherwise
MPA, traditional form login	`autodetect` or `loggedInRegex`	Works reliably for server-rendered pages
SPA with business headers	Add `headers` section	ZAP injects headers; session autodetected automatically
SPA, no additional headers	Remove `headers` section	Default session management works; ensure backend does not require extra headers

5. Special Considerations

302 Redirects:
- If login returns 302, response body is empty.
- loggedInRegex will fail; use pollUrl pointing to a protected endpoint.
SPA Applications:
- Autodetect often fails.
- Response regex works only if frontend and backend share the same domain.
- Poll URL is the most reliable verification method.
Session Handling:
- ZAP detects session tokens from cookies, headers, or JWTs.
- Business headers can be added under headers if needed.
Backend Domain Different from Frontend:
- Browser authentication loads only the frontend domain.
- If backend is different, verification via loggedInRegex or autodetect fails unless pollUrl is used.

6. Best Practices

Always set automation: true.
Frontend URL must be primary host in context; backend cannot be primary host.
Use pollUrl for verification when frontend and backend are separate domains or when login returns 302.
Use loggedInRegex to validate authentication state.
Include business headers only if required; inspect traffic post-login to determine values.
Do not rely on autodetect for SPA applications.
Response type works only if frontend and backend are the same domain.

7. Example Configurations

7.1 SPA, Same Domain (Response Verification)

automation: true

scope:
  entryUrls:
    - "https://app.example.com"
  includePaths:
    - "https://app.example.com.*"
  excludePaths:
    - "https://app.example.com/logout.*"

authentication:
  type: "browser"
  loginPageUrl: "https://app.example.com/login"
  loggedInRegex: "Login Successful"

7.2 SPA, Different Backend Domain (Poll Verification)

automation: true

scope:
  entryUrls:
    - "https://app.example.com"
  includePaths:
    - "https://app.example.com.*"
  excludePaths:
    - "https://app.example.com/logout.*"

authentication:
  type: "browser"
  loginPageUrl: "https://app.example.com/login"
  pollUrl: "https://api.example.com/user/profile"
  loggedInRegex: "Login Successful"

7.3 MPA with Autodetect

Example: DVWA – autodetect works because it is a simple application with predictable login patterns, session cookies (like PHPSESSID), and standard redirects (e.g., /index.php).
Important: In real-world scenarios, autodetect is often unreliable for complex applications, SPAs, or apps with custom login flows.
For production apps, always prefer pollUrl or explicit loggedInRegex verification.

automation: true

scope:
  entryUrls:
    - "http://20.80.162.88:4280/"
  includePaths:
    - "http://20.80.162.88:4280.*"
  excludePaths:
    - "http://20.80.162.88:4280/logout.php"
    - "http://20.80.162.88:4280/login.php"
    - "http://20.80.162.88:4280/setup.php"
    - "http://20.80.162.88:4280/security.php"
    - "http://20.80.162.88:4280/vulnerabilities/csrf.*"

authentication:
  type: "browser"
  loginPageUrl: "http://20.80.162.88:4280/login.php"

Notes:

Autodetect attempts to infer the authentication state automatically from login traffic.
✅ May work for simple server-rendered apps (e.g., DVWA).
❌ Not reliable for SPA or complex applications.
LoggedInRegex is not set; response body may be empty (302 redirects), so verification may fail.
Recommended only for testing or simple lab scenarios; for production apps, use pollUrl or explicit loggedInRegex.

7.4 MPA with Poll URL Verification

Example: DVWA – using pollUrl for verification ensures reliable authentication detection. The pollUrl points to a protected page (e.g., /index.php) that is only accessible after successful login.
Configuration: Set both pollUrl and loggedInRegex to validate the authenticated session.
Benefits:
- Works even if the login page returns a 302 redirect or an empty response, where loggedInRegex on login response would fail.
- Ensures accurate session verification regardless of backend response behavior.
Best Practice: For all server-rendered MPA applications in production, always use pollUrl rather than relying on autodetect or login-page response matching.

automation: true
scope:
  entryUrls:
    - "http://20.80.162.88:4280/"
  includePaths:
    - "http://20.80.162.88:4280.*"
  excludePaths:
    - "http://20.80.162.88:4280/logout.php"
    - "http://20.80.162.88:4280/login.php"
    - "http://20.80.162.88:4280/setup.php"
    - "http://20.80.162.88:4280/security.php"
    - "http://20.80.162.88:4280/vulnerabilities/csrf.*"

authentication:
  type: "browser"
  loginPageUrl: "http://20.80.162.88:4280/login.php"
  pollUrl: "http://20.80.162.88:4280/index.php"
  loggedInRegex: "Welcome to Damn Vulnerable Web Application!"

8. Troubleshooting

Login appears successful, but verification fails:
- Check if backend API is on a different domain.
- Ensure pollUrl points to a protected endpoint in the same context.
Session not detected:
- Verify headers; add business headers if required.
Autodetect fails on SPA:
- Switch to pollUrl or explicit response verification.

9. Browser-Based Authentication Flow

                  ┌───────────────────────────────┐
                  │       Login Page (Browser)    │
                  └───────────────┬──────────────┘
                                  │
                ┌─────────────────┴─────────────────┐
                │                                   │
     ┌──────────▼──────────┐              ┌─────────▼───────────┐
     │ Response Verification│              │ Poll URL Verification│
     │ (Same domain SPA/MPA)│             │ (Different backend   │
     │ loggedInRegex        │             │ domain SPA)          │
     └──────────┬──────────┘              └─────────┬───────────┘
                │                                   │
     ┌──────────▼──────────┐              ┌─────────▼───────────┐
     │ Session Detection    │              │ Session Detection    │
     │ Cookies / Headers /  │              │ Cookies / Headers /  │
     │ Tokens               │              │ Tokens               │
     └──────────┬──────────┘              └─────────┬───────────┘
                │                                   │
          ┌─────▼─────┐                       ┌─────▼─────┐
          │ Headers   │                       │ Headers   │
          │ Injection │                       │ Injection │
          │ (Optional │                       │ (Optional │
          │ business  │                       │ business  │
          │ headers)  │                       │ headers)  │
          └───────────┘                       └───────────┘

Browser-Based Authentication — ZAP Reference Guide

1. YAML Configuration Overview​

Additional Notes:​

2. Key Fields​

3. Verification Methods​

4. Browser Authentication Scenarios​

5. Special Considerations​

6. Best Practices​

7. Example Configurations​

7.1 SPA, Same Domain (Response Verification)​

7.2 SPA, Different Backend Domain (Poll Verification)​

7.3 MPA with Autodetect​

7.4 MPA with Poll URL Verification​

8. Troubleshooting​

9. Browser-Based Authentication Flow​