JSON-Based Authentication — ZAP Reference Guide

JSON-based authentication in ZAP is used for applications where login occurs via an API returning a JSON token (JWT, session token, or similar). This is common for SPA, mobile backends, or microservices.

Unlike browser-based authentication, there is no HTML page interaction; ZAP directly posts to the backend API and validates authentication via JSON responses.

---

1. YAML Configuration Overview

automation: true  # Must always be true

scope:
  entryUrls:
    # ⚠️ The first entry URL is critical: it will be used in the scan report.
    # For JSON-based auth, always set this to the backend API endpoint.
    # For frontend SPA, if set to frontend URL, authentication may appear failed in report.
    - "https://api.example.com"
  includePaths:
    - "https://api.example.com.*"
  excludePaths:
    - "https://api.example.com/logout.*"
    - ".*\.png"
    - ".*\.css"
    - ".*\.jpg"

headers:
  # Authorization token extracted from login response JSON
  Authorization: "{%json:Authorization%}"

  # Optional business headers. Remove if not needed.
  Type: "admin"
  Version: "1.21.5"

authentication:
  type: "json"
  loginPageUrl: "https://app.example.com/#/auth/login"
  loginBackendUrl: "https://api.example.com/users/login"

  # JSON body sent to login API
  bodyTemplate: |
    {
      "email": "{identifier}",
      "password": "{password}",
      "isAdmin": "yes"
    }

  # Optional poll URL to verify session
  # pollUrl: "https://api.example.com/organization/getAll"

  # Regex or keyword that confirms successful login
  loggedInRegex: "Data Fetched Successfully"

Additional Notes:

• Entry URL order matters: ZAP treats the first URL as the primary host in the scan context and uses it in the report.
• JSON-based login: First entry URL must point to the backend API that handles authentication.
• Browser-based SPA login: First entry URL should point to the frontend; backend API calls may still work for poll URL verification, but report may show authentication failed if first URL is frontend and auth is API-based.
• Include/Exclude paths: Can contain multiple domains or patterns. They are used for crawling/spidering and do not affect which URL appears in the report.

---

2. Key Notes

• loginBackendUrl: API endpoint used for authentication. ZAP posts the bodyTemplate here.
• bodyTemplate: Must include all keys expected by the API. {identifier} and {password} are placeholders.
• Authorization: Extracted from JSON response using {%json:Authorization%}. Supports nested JSON keys if needed.
• pollUrl: Optional, used to verify a protected endpoint after login. Useful for SPAs or APIs where response alone might not suffice.
• loggedInRegex: Regex/keyword used to confirm authentication; can be applied on login response or pollUrl response.

---

3. Verification Methods

Method	When to Use	Notes
Response Regex	Direct login response	✅ Recommended; simplest for API login. Works if API returns JSON with token or status.
Poll URL	Additional verification after login	✅ Optional; ensures session is valid for subsequent requests. Use loggedInRegex on the response.

Recommendation: For JSON-based auth, response regex is easiest and usually sufficient, but pollUrl can be added for extra reliability.

---

4. Key Fields

Field	Meaning
automation	Must be true.
scope.entryUrls	Starting URLs for API crawling.
scope.includePaths	Regex patterns for URLs to include in scan.
scope.excludePaths	Regex patterns for URLs to exclude (logout, static assets).
headers	Business headers (Authorization, custom headers).
authentication.type	Must be json for JSON-based login.
loginPageUrl	Optional; frontend login page (for context).
loginBackendUrl	Required API endpoint for login.
bodyTemplate	Full JSON payload sent to login API.
pollUrl	Optional endpoint to verify login.
loggedInRegex	Regex/keyword to confirm successful authentication.
loggedOutRegex	Optional; regex for logged-out state.

---

5. JSON Authentication Scenarios

Scenario	Setup	Notes
SPA, single API domain	response type	Easiest; match loggedInRegex on login response.
SPA, backend and frontend same domain	response type	Same as above; may include business headers if required.
SPA, backend and frontend different domains	pollUrl + loggedInRegex	Optional; use pollUrl to verify session if cross-domain issues arise.
SPA with business headers	Add headers section	Extract Authorization token from JSON response and inject into headers for subsequent calls.

---

6. Special Considerations

1. Authorization Header Extraction

   • Use {%json:Authorization%} to dynamically extract the token from login response JSON.
   • For nested JSON, use {%json:data.token%} or similar.

2. Full Body Template

   • Include all fields the API expects (email, password, isAdmin, etc.).
   • Omitting keys may cause login failure.

3. Poll URL (Optional)

   • Use only if response verification alone is not enough (cross-domain, multi-step login flows).
   • loggedInRegex applies on poll URL response.

4. Business Headers

   • Always inspect post-login traffic to determine required headers.
   • Headers must be injected on every API request for authenticated session.

---

7. Example Configurations

7.1 Response Type Verification (Simplest)

automation: true

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

headers:
  Authorization: "{%json:Authorization%}"
  Type: "admin"
  Version: "1.21.5"

authentication:
  type: "json"
  loginPageUrl: "https://app.example.com/#/auth/login"
  loginBackendUrl: "https://api.example.com/users/login"
  bodyTemplate: |
    {
      "email": "{identifier}",
      "password": "{password}",
      "isAdmin": "yes"
    }
  loggedInRegex: "login successful!"

7.2 Poll URL Verification

automation: true

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

headers:
  Authorization: "{%json:Authorization%}"

authentication:
  type: "json"
  loginPageUrl: "https://app.example.com/#/auth/login"
  loginBackendUrl: "https://api.example.com/users/login"
  bodyTemplate: |
    {"email":"{identifier}","password":"{password}"}

  pollUrl: "https://api.example.com/organization/getAll"
  loggedInRegex: "Data Fetched Successfully"

---

8. JSON Authentication Flow Diagram

              ┌───────────────────────────────┐
              │   Login API Request (JSON)    │
              │ https://api.example.com/users/login │
              └───────────────┬───────────────┘
                              │
                ┌─────────────┴─────────────┐
                │                           │
       ┌────────▼─────────┐         ┌───────▼────────┐
       │ Response Verification │     │ Poll URL Verification │
       │ (loginBackendUrl)     │     │ (Optional)             │
       │ loggedInRegex         │     │ loggedInRegex          │
       └────────┬─────────────┘     └────────┬─────────────┘
                │                           │
      ┌─────────▼─────────┐         ┌───────▼────────┐
      │ Session Detection  │         │ Session Detection │
      │ Cookies / Headers  │         │ Cookies / Headers │
      │ / Tokens           │         │ / Tokens          │
      └─────────┬─────────┘         └────────┬─────────┘
                │                           │
                │                           │
        ┌───────▼─────────┐         ┌───────▼─────────┐
        │ Headers Injection│         │ Headers Injection│
        │ Authorization /  │         │ Authorization /  │
        │ Business Headers │         │ Business Headers │
        └─────────────────┘         └─────────────────┘

Notes:

• Response verification is usually sufficient for JSON-based login.
• Poll URL verification is optional, used for additional reliability or complex flows.
• All required headers (Authorization, business headers) must be injected for subsequent requests.