ZAP Script Authentication: A Step-by-Step Guide

TL;DR

This guide shows you how to authenticate with OWASP ZAP using a script, allowing it to scan protected areas of your web application. We’ll cover setting up the script and testing it.

Setting Up Authentication in ZAP

1. Open Your Script: In ZAP, go to Tools > Options.
2. Navigate to Scripts: Select the ‘Scripts’ tab.
3. Add a New Script: Click ‘Add’. Give your script a meaningful name (e.g., ‘MyAuthenticationScript’). Choose a suitable language (JavaScript is common).

Writing the Authentication Script

The core of authentication lies in the script itself. Here’s an example using JavaScript to handle basic HTTP authentication:

function scan(helper, ctx) {
  var request = helper.request;
  // Check if the request needs authentication (e.g., by URL)
  if (request.getURL().toString().startsWith("https://your-protected-app/admin/")) {
    // Add Authentication Header
    request.addHeader("Authorization", "Basic " + helper.getAuthenticationToken());
  }
}

Explanation:

• scan(helper, ctx): This function is called for each request ZAP intercepts.
• helper.request: Provides access to the current HTTP request object.
• request.getURL().toString(): Gets the URL of the request as a string.
• startsWith("https://your-protected-app/admin/"): Checks if the URL starts with your protected application’s admin path. Replace this with your actual URL!
• request.addHeader("Authorization", "Basic " + helper.getAuthenticationToken()): Adds an ‘Authorization’ header to the request, including a basic authentication token. The helper.getAuthenticationToken() function is crucial; we’ll define this next.

Getting the Authentication Token

You need a way for ZAP to obtain the authentication token (username/password). Here’s how you can implement that:

function getAuthenticationToken() {
  // Prompt user for credentials if not already cached.
  var username = ctx.getOption("authentication.username");
  var password = ctx.getOption("authentication.password");

  if (!username || !password) {
    var dialog = new Dialog();
    dialog.setTitle("Authentication Required");
    dialog.setPromptText("Username:", username);
    dialog.setPromptText("Password:", password);
    dialog.showDialog();
    username = dialog.getValue("Username");
    password = dialog.getValue("Password");

    ctx.setOption("authentication.username", username);
    ctx.setOption("authentication.password", password);
  }

  // Encode the credentials in Base64.
  var encodedCredentials = btoa(username + ':' + password);
  return encodedCredentials;
}

Explanation:

• ctx.getOption("authentication.username") and ctx.getOption("authentication.password"): Attempts to retrieve cached credentials from ZAP’s options.
• The if (!username || !password) block prompts the user for credentials if they aren’t already stored.
• btoa(username + ':' + password): Encodes the username and password in Base64, which is required for Basic Authentication.

Adding the Token Function to Your Script

Add the getAuthenticationToken() function to your script *before* the scan() function.

Testing the Script

1. Save Your Script: Save the changes to your authentication script.
2. Enable the Script: In ZAP, ensure the script is enabled (checkbox ticked in the Scripts tab).
3. Browse Your Application: Start browsing your protected application. ZAP will intercept requests and apply the authentication header if it matches your URL condition.
4. Check the History Tab: Verify that the ‘Authorization’ header is being added to requests targeting your protected areas in ZAP’s History tab. Select a request, then look at the ‘Request’ tab. You should see the header present.

Troubleshooting

• Incorrect URL: Double-check that the URL condition in your script (startsWith()) is correct.
• Base64 Encoding: Ensure the username and password are correctly encoded in Base64.
• Authentication Type: This example uses Basic Authentication. Adjust the script if your application uses a different authentication method (e.g., API keys, OAuth).