Authentication Decision Tree on ZAP

Auth: All Done

Mon, 01 Jan 0001 00:00:00 +0000

You now have a context that handles authentication for your app.

However if you do not do anything with it then it will be lost when you close the ZAP desktop!

Change to use a Headless Browser

By default the Authentication Tester will use the Firefox browser - this means that you will see the browser being launched in order to login. This helps when testing as we can then see what is going on.

Auth: All Information Available

Mon, 01 Jan 0001 00:00:00 +0000

You have a context for your app and have configured it to handle authentication.

We now need to check that it really does work as expected.

Action: Create an Automation Framework Plan

There are other ways to test the context manually, but this will make it easier to retest if you need to make any changes.

Auth: App Does Not Load in Time

Mon, 01 Jan 0001 00:00:00 +0000

Some modern apps can take a long time to load.

Keep increasing the ‘Time to Wait (seconds)’ field in the Authentication Tester and retesting until you see your app completely load in the browser.

This field controls the time the browser will wait before closing. Be aware it might take even longer in CI/CD.

Auth: Application Type

Mon, 01 Jan 0001 00:00:00 +0000

Modern web apps make heavy use of JavaScript.

Traditional web apps typically return a full HTML page when you follow links.

APIs do not have a UI, but may be used by both modern and traditional web apps.

Auth: Authentication Tester

Mon, 01 Jan 0001 00:00:00 +0000

Run the Authentication Tester in the ZAP desktop.

You should do this even if you want to automate ZAP from the command line, as it will help us understand which parts of the authentication process ZAP can automatically handle.

If ZAP can automatically handle things then it will make your life easier.

Auth: Browser Fails to Launch

Mon, 01 Jan 0001 00:00:00 +0000

Follow the FAQ How can I fix ‘browser was not found’?

Next Step: Run the Auth Tester again

Keep following the FAQ until you can launch a browser, or until you get to the end of the FAQ.

Auth: Cannot Access The App

Mon, 01 Jan 0001 00:00:00 +0000

Follow the FAQ: Why can’t ZAP connect to my web application?

Note that if the app does not have a static URL for the login page then you can also try using a URL that has a link to the login page.

Next Step: Run the Auth Tester again

If ZAP can access your app but still cannot authenticate then:

Auth: Fails to Find The Login Fields

Mon, 01 Jan 0001 00:00:00 +0000

We want to make sure that ZAP can automatically fill in as many different types of login forms as possible, so please share details of the page with the ZAP team.

We will want to know the HTML fragments for the form and all of the input fields in it. Feel free to obfuscate any sensitive information.

Auth: Fails to Identify a Verification URL

Mon, 01 Jan 0001 00:00:00 +0000

ZAP has failed to identify a suitable URL to use to verify if the user is logged in, so you will need to do that. For more details see Finding a verification URL.

Auth: Fails to Identify the Session Handling

Mon, 01 Jan 0001 00:00:00 +0000

ZAP has failed to identify your app’s session handling, so you will need to do that. For more details see Session handling.

If you succeed in identifying the session handling then you will need to also manually identify the verification handling.

Auth: Modern Web UI

Mon, 01 Jan 0001 00:00:00 +0000

Your app is “modern” i.e. it makes heavy use of JavaScript.

In order to explore your app in automation you will need to use the AJAX Spider - this launches browsers in order to explore your app.

Injecting session state into a browser is not always possible, and where it is, it is always application specific.

Auth: Multiple Header Based Authentication

Mon, 01 Jan 0001 00:00:00 +0000

You can do this via:

Background

You have more than one authentication token which you need to supply in HTTP headers.

Auth: No Easy Options

Mon, 01 Jan 0001 00:00:00 +0000

There are currently no easy options available to you, but we have lots of guides that can take you through the more complicated options that ZAP supports.

Auth: Preparing to Test

Mon, 01 Jan 0001 00:00:00 +0000

Either ZAP has identified all of the information required, or you have found the parts it could not identify.

We now need to update the context created by the Authentication Tester to test it.

To edit the context double click on the ‘Authentication Test’ context in the Sites tree.

Auth: Record a Login Script

Mon, 01 Jan 0001 00:00:00 +0000

In the Authentication Tester change the “Auth Method” to “Client Script” and then click on the “Record…” button.

ZAP will launch your chosen browser and open the Login URL.

ZAP will have created and selected a new “Client Script” which it will use to authenticate when you run the next test.

Auth: Session Not Identified

Mon, 01 Jan 0001 00:00:00 +0000

Next Step: Run the Auth Tester again

This time try exploring the app by clicking on links and filling in fields once ZAP has successfully logged in.

Auth: Simple Header Based Authentication

Mon, 01 Jan 0001 00:00:00 +0000

The easiest way to do this will be via Authentication env vars.

Other options are available, as detailed on Handling Authentication Yourself.

Background

You do have a single authentication token which you need to supply in a header.

Auth: Support

Mon, 01 Jan 0001 00:00:00 +0000

You have reached the limits of this guide and will need support.

Explain:

That you have followed this guide
Exactly which steps you have taken
Full details of what went wrong

If you fail to provide these details then we’ll just ask you for them, which will delay the whole process. The more information you can provide to us at the start then the quicker we will be able to help you.

Auth: Tester Outcome

Mon, 01 Jan 0001 00:00:00 +0000

The Authentication Tester will help us understand which parts of the authentication process ZAP can automatically handle.

If ZAP can automatically handle things then it will make your life easier. Even if it cannot handle everything it may still give you a better starting point.

Auth: Token Based Authentication

Mon, 01 Jan 0001 00:00:00 +0000

Your app is either an API or a traditional web app.

If you have a reliable token that will not be invalidated during the scan then this is probably your best option to use.

Auth: Verification Not Identified

Mon, 01 Jan 0001 00:00:00 +0000

Next Step: Run the Auth Tester again

This time try exploring the app by clicking on links and filling in fields once ZAP has successfully logged in.