Authentication
ZAP can handle a wide range of authentication mechanisms.
If you are new to ZAP automation then the best place to start is the ZAP
Authentication Decision Tree (external link).
Each Context has:
You can use any combination of Authentication Method and Verification Strategy which works for your webapp.
In order to perform the authentication of a user on a website /
in a webapp, the Authentication Method and Verification Strategy define how the authentication
is done (the process), while the necessary credentials (the exact
identifiers) are dependent on the user, so, in ZAP, they are
configured in the Users.
The generic main steps that are needed to configure authentication for a web application
are the following:
- Configure a ZAP Context for the web application, ensuring that all required URLs are included
- Set up the Session Management Method for the context to
the one that is used in your app
- Configure the Authentication Method for your application, specifying all the requirements
- Configure the Authentication Verification Strategy for your application, specifying at least one
of the Logged In Indicator or the Logged out indicator
- Configure one or more Users for the context that directly correspond to the
authentication method for the context
Configuration example
A configuration example showing how to fully configure a webapp that uses form-based authentication,
cookie-based session management and returns full HTML pages (including an indication of whether the user is logged in) is seen below:
- Set up a context for the web application
- Set up the session management method to Cookie-based Session Management
- Make sure your browser proxies everything through ZAP and log into your application using the browser
- Go to ZAP and identify the request that was done for the login (most usually it's a HTTP POST request
containing the username and the password and possibly other elements)
- If there is an anti-CSRF token in the login request, add the token name in
Options Anti CSRF screen, if not present.
- Set up the authentication method:
- Right click on the authentication request and 'Flag as Context... Form-based Auth Login Request'
- A window will be opened already containing the request URL and the parameters (if any). Use
the dropdown options to select which of the parameters correspond to the username and to the password
- Set up the authentication verification strategy:
- Select a message which has a suitable logged in or logged out indicator e.g. a logout link or a welcome message
- Select the relevant text, right click on it and select either 'Flag as Context... Authentication Logged-in Indicator' or
'Flag as Context... Authentication Logged-out Indicator' as appropriate
- Define as many users as you need in the Session Properties -> Users section.
After configuring authentication, various actions are available in ZAP. For example, you can now select the user in the
Spider dialogue.
Most of the steps above apply as well for other authentication methods. The only things that change when trying
to configure authentication using a different method is step 6. Instead of that, select the authentication
method required from the drop-down list and configure it as needed. More details about configuring each type
of authentication can be found in the Authentication Methods page and in the
Context Session screens.
When Forced User Mode is enabled then all interactions that go through ZAP for a given context will be
updated to be from the perspective of the specified User.
The Forced User Mode is enabled via a button in the toolbar (the one with the user and the lock) and
is configured via Session Properties -> Forced User Mode.
Important: Forced User Mode is just intended for manual testing and should not be used in automation -
there are much better alternatives.
A set of environmental variables are available which allow you to easily add an authentication header to all of the requests that are proxied through ZAP or initiated
by the ZAP tools, including the spiders and active scanner:
- ZAP_AUTH_HEADER_VALUE - if this is defined then its value will be added as a header to all of the requests
- ZAP_AUTH_HEADER - if this is defined then its value will be used as the header name - if it is not defined then the standard
Authorization header will be used
- ZAP_AUTH_HEADER_SITE - if this is defined then header will only be included in sites who's name includes its value
Configured via
See also
Official Videos