Skip to main content

Here’s a structured, clean documentation you can include in your platform guide for ZAP authentication verification. I’ve organized it by method, typical application type, and recommended usage.

ZAP Authentication Verification Methods Documentation

ZAP provides multiple methods to verify whether authentication has succeeded during automated scans. Choosing the correct verification method is critical, especially for modern Single Page Applications (SPAs) and API-driven backends.

1. Verification Methods Overview​

MethodDescriptionTypical UsageKey Parameters
autodetectZAP attempts to automatically determine which responses indicate successful login based on cookies, session tokens, headers, or form submissions.Only reliable for traditional web apps with standard session cookies (e.g., PHPSESSID, JSESSIONID) or form-based logins.None (automatic)
responseMatches a specified regex against responses within the authenticated context to determine login success.Suitable for SPAs or apps where backend APIs return predictable messages upon successful login.loggedInRegex – regex to match a successful response.
pollFrequency / pollUnits – how often to check responses.
pollMakes requests to a specific URL at a defined frequency and checks the response body against a regex.Recommended for SPAs or API-driven apps where the frontend URL differs from the backend authentication endpoint.pollUrl – the URL to poll.
loggedInRegex – regex to match authenticated response.
pollFrequency / pollUnits.

Conclusion:

  • poll is the most reliable verification method across all types of applications. When properly configured with a pollUrl pointing to a protected endpoint, it works consistently for SPAs, server-rendered apps, hybrid apps, and API-driven apps.
  • response works well for JSON-based authentication or predictable backend responses, but may fail if frontend and backend domains differ or if redirects occur.
  • autodetect is the least reliable and should be avoided for SPAs, API-driven apps, and hybrid applications. It is only suitable for traditional server-rendered apps with standard session cookies or simple form-based logins.

Recommendation: Prefer poll wherever possible. Use response only when polling is not feasible and autodetect only for legacy MPA/form-based logins.

2. Application Type Guidance​

2.1 Browser-based Authentication​

  • Method to Use: poll (preferred) or response

  • When to Use: SPA frontend where login is performed via JavaScript and backend APIs handle authentication.

  • Notes:

    • autodetect often fails for SPAs because it cannot reliably match tokens or cookies across frontend and backend endpoints.
    • Even if frontend route differs from backend API, response works as long as the regex matches any response in the authenticated context.
    • For higher reliability, provide an explicit pollUrl pointing to a stable backend endpoint that confirms authentication.

Important Notes for Browser-based Authentication in SPA / Multi-domain Applications:

  • The primary host in the context must always be the frontend URL, because browser-based authentication will attempt to load the login page using a browser. If the backend API is set as the primary host, authentication will fail since the browser cannot directly load API endpoints.
  • The context can include multiple hosts (an array), but ZAP reports authentication results based on the first host (primary host) in the context.
  • If the backend API domain is different from the frontend domain, verification via regex may fail because ZAP only evaluates responses within the current context domain.
  • To handle this reliably, provide an explicit pollUrl pointing to a backend endpoint that confirms successful authentication. This avoids relying on autodetect or response checks against mismatched domains.

2.2 JSON / API-based Authentication​

  • Method to Use: response or poll

  • When to Use: REST APIs or AJAX endpoints that return JSON responses with authentication status.

  • Notes:

    • Specify the backend API URL explicitly using pollUrl for SPAs.
    • Use loggedInRegex or JSON path references (e.g., Authorization header) for validation.
    • autodetect may fail because ZAP cannot infer login success from JSON alone without guidance.

2.3 Form-based / HTML Authentication​

  • Method to Use: form (traditional HTML login form)

  • When to Use: Legacy web applications with server-rendered login forms.

  • Notes:

    • autodetect can sometimes work if the session mechanism is standard, but it is not fully reliable.
    • Using response-based verification may fail for apps like DVWA that redirect (302) immediately after login without returning a usable response body, or set cookies server-side.
    • Poll-based verification is generally more reliable for form-based authentication. Set a pollUrl pointing to a page that requires authentication.
    • Ensure the pollUrl or loggedInRegex points to a page visible only to logged-in users.

Recommendation: For most form-based HTML applications, prefer poll-based verification. Response-based verification is optional and may fail on redirects or when login responses do not contain identifiable content.

3. Best Practices​

  1. Always prefer explicit verification over autodetect, especially for modern SPAs and API-driven apps.

  2. Use pollUrl for SPAs:

    • Points directly to a backend API endpoint that reliably confirms authentication (e.g., /api/users/me).
    • Reduces false negatives compared to autodetect.

  3. Use response verification for browser-based authentication:

    • Provide a regex matching a known success indicator in API or HTML response.

  4. Reserve autodetect for legacy or simple HTML login forms:

    • May work with standard session cookies but is unreliable for JSON or SPA-based flows.

  5. Always test verification settings before running full automated scans:

    • Check the auth-summary section in the auth-report.
    • Look for Verification URL identified: true to confirm ZAP recognized authentication.
  1. Configure authentication (browser or JSON method).
  2. Set verification to response or poll.
  3. For JSON/SPA: explicitly provide backend URL (pollUrl).
  4. Define loggedInRegex based on a reliable success message or JSON property.
  5. Run a small test scan and check the auth-report summary.

5. ZAP’s autodetect heuristics​

ZAP’s autodetect looks for changes in session state or the presence of tokens, not strictly HTML responses.

If a login request returns a set-cookie header, an Authorization header, or any session token, ZAP may detect it as “successful login” even without a full HTML page.

Juice Shop’s /rest/user/login returns a JWT in JSON. ZAP apparently can detect the Authorization header being set or session token being present.

6. Summary​

  • SPAs / AJAX-heavy applications: Prefer poll or response with explicit URL/regex.
  • JSON API-based authentication: Explicit backend URL with poll or response.
  • HTML form login: form verification or autodetect if standard session cookies exist.
  • Autodetect is not reliable for SPA applications and should generally be avoided.