Skip to main content

How to add form-based authentication

Your 'how to' guide for adding Form-based authentication

Written by Naomi Purvis

⚠️ Important: If you're thinking of an admin user when adding authentications, please read this article first: Adding an admin user when adding authentications

💡 Tip: If you have any trouble with form-based authentication, as a good first step, it might be worth trying the session cookie authentication method or using header-based authentication.

💡 Tip: If your login process is a little more complicated, you might want to have a quick skim of this article, and if you have questions about scan scope, you might want to give this article a read.

💡 Tip: You can also add, view, update, and delete authentications from your targets using our API. This can help if you wish to integrate vulnerability scanning as part of your CI/CD pipeline or otherwise update the authentication credentials automatically.

📹 Prefer a video walkthrough?

We also have a video tutorial on adding form-based authentication which you can find here:

🎥 Video: How to add form-based authentication

Before you start

The information below is required for our scanner to know where in your application to start scanning from, how to submit the login request, and what URL to avoid so that the scanner doesn't get logged out. A few extra tips:

  • http:// or https:// is required on your URLs

  • The Login page URL is optional but will be beneficial when our scanner tries to retrieve and update anti Cross-site Request Forgery (anti-CSRF) tokens

  • The Logged in pattern is optional but will help our scanner identify when it has authenticated correctly and if it needs to re-authenticate during the scan.

Adding a new target with authentication

Throughout this example, we will be using vulnerablesite.intrud.es where we are hosting our test application.
​

💡 Tip: If you're unsure where to find the parameters needed, we have just the article for you.

  1. Targets > Add target > External web application
    ​

  2. Type the target into the top box, add the Entrypoint URL and any tags (if applicable), and then click the Add target button.
    ​

  3. Select the 'Form based' option and add the relevant parameters to the configuration, then click the 'Next ->' button.
    ​


    Add the form parameters:
    ​


    Finally, enter the credentials and hit the 'Save and verify authentication' button:
    ​

Adding the Authentication to a pre-existing target

  1. Head back to Targets > All > ... > Add authentication
    ​

  2. Click the top box: 'Form based':
    ​

Adding the authentication

  1. Enter the details:


    Entrypoint URL

    The entrypoint URL tells the scanner where to start its crawling and scanning. The scanner will crawl and test anything it finds under the root of that entrypoint, so if you add 'https://example.com/example_path' as your entrypoint URL, we'll permit anything discovered under 'https://example.com/*'. Unlike form-based authentication, there is no login URL. Instead, the login details are sent with every request.

    In the example above, our entrypoint URL is http://vulnerablesite.intrud.es/DVWA

    Login page URL

    This is the URL where we can find the login page of the web application. In our example, we're using 'http://vulnerablesite.intrud.es/DVWA/login.php':

    Login request URL

    This is the URL to which your application sends the data that users have entered into the form. This can be found by right-clicking on the form (such as on the username field), and then selecting Inspect:
    ​

    You are looking for the form tag that encloses the username and password fields on your login form. The form tag will have an action field and the value of that field is what you're looking for. In our example, the value is login.php, which can be seen below:
    ​


    In our example, we see login.php is the value we see in the form. We need to add the prefix that we made a note of in our Login Page URL section above. So, the value we need to enter into our Login Request URL field is 'http://vulnerablesite.intrud.es/DVWA/login.php' You may notice that this is the same as our Login Page URL from the previous section - this may not be the case in your app.

    Logout URL

    In our example, we specify that there is a Logout URL that we want to exclude from scanning. The easiest way to find this would be to log in to the application and find the Logout button on your page (it may say Log Out or Sign Out or something similar). If you hover over the button you'll see the Logout URL in in the bottom of your page, you can also right click and 'Save link address', then paste into Intruder.
    ​
    If that's not working, you can right-click on the logout button and click on Inspect:
    ​

    In our example, the Logout URL is set to logout.php , but it needs to be fully-qualified by adding the path to the current page in front of the page. Which you can see in the screenshot above http://vulnerablesite.intrud.es/DVWA/logout.php:
    ​

    Note that if you have a Logout URL that includes query parameters (e.g. http://www.example.com/login?action=logout), then we would recommend always including the Logged In Pattern (optional) parameter.

    Allowed Domains

    This section lets you specify additional domains that your application depends on, so those requests are permitted to complete during a scan. The scanner will also run a limited set of security checks on those network requests. Please check out this article for more information.

  2. Enter the form parameters:


    ​

    Username field and Password field

    You are looking for the value of the name field for each. In this example, the username field (in the form on our target web application) is named username and the password field is named password. (These are not your user credentials for logging in).
    ​
    To find these, log out of the application, go to your Login Page URL, right-click on the username field, and click 'inspect':
    ​


    Note the value of the username field's name attribute:
    ​


    Note the value of the password field's name attribute:
    ​

    Additional Parameters

    If the authentication sends more than just the username and password parameters, these would also need to be added to the configuration by entering them into the Key/Value boxes and pressing the + Add Parameter button for any further parameters needed.

    CSRF token (optional)

    The scanner will attempt to use a CSRF Token from a list of the most common values (e.g. antiforgery-token, csrf-token, etc.). However, for the best results, it is always best to include the exact value used in your web app, especially if you use an uncommon name for the token.

    Anti-CSRF tokens are usually found in forms that submit data to the application. But, it might be possible that your application doesn't have an anti-CSRF token at all.


    Anti-CSRF tokens will usually have the following properties:

    • It will be an input field in the same form as your login fields

    • The input field will have a type and it will be set to "hidden" , which you can see in our example below as type="hidden"

    • The input will have a value and that value will usually be a long random block of text

    • The input will have a name but there is no specification which dictates what the name should be, it can be anything. But, the name may include the term csrf , authenticity , verification or token.


    In our example below, you can see that the field that fits all these properties is the user_token field, and this is our CSRF Token Field:
    ​

  3. Add the User credentials

    Username and password

    Finally, you will be asked to provide the credentials for the user that you want the scanner to authenticate as.

  4. Once you've clicked 'save and verify authentication' it's enabled and all scans will run from an authenticated perspective.
    ​


    Clicking on the target will take you to the target's detail page, where you can review the authentication:
    ​

Verifying the authentication

In progress

Before you get any responses, it'll look like this:
​

Complete

Given how nuanced apps are, we don't presume the accuracy of authentication – instead, we show you what the scanner encountered and allow you to decide whether it has worked or not (the screenshot in particular is helpful, as you can use that to gauge if the scanner can access pages behind the login).

You could get any combination of results, here are just a few:
​

Managing authentication(s)

Once you've completed this information, you will see the authentication appear under the Authentications tab.
​

To disable an authentication

Click ... > Disable:

And the modal will update to this:
​

To re-enable, just click the ellipsis again > Enable:
​

To check the status of the authentication

Click the ellipsis > Check status:
​

The next modal to pop up will be this one, where you can confirm the authentication, edit the details, or close the modal and disable the authentication.
​

Related Articles
How to add HTTP authentication
How to add header-based authentication
How to add session cookie authentication
How to add a recorded login
How to add OAuth 2.0 authentication
Did this answer your question?