Configuring login details for sites
Last updated: May 17, 2022
Read time: 5 Minutes
When creating or editing a site in Burp Suite Enterprise Edition, you have the option to provide valid application logins that Burp Scanner should submit when it encounters any login forms on the site. This enables it to discover and audit content that is only accessible to authenticated users.
You have the following two options for providing application logins. Please note that you can only use one of these options per site.
Add login credentials
If your site only has a basic, single-step login mechanism, you can simply add sets of usernames and passwords, along with a label to help identify them.
This works well for classic login forms with only 2 input fields. However, with this option selected, Burp Scanner will be unable to deal with more complex login mechanisms involving single sign-on, for example. In this case, we recommend importing a recorded login sequence to ensure maximum coverage for your scans.
Add recorded login sequences
A recorded login sequence is essentially a set of instructions that tell Burp Scanner exactly how to log in to the site. This enables it to handle more complex login mechanisms, including single sign-on.
You can create recorded login sequences quickly and easily using our dedicated Chrome extension. The extension captures your interactions with the website while you perform the login sequence manually in your browser. It automatically generates a JSON-based "script", which you can then import as an application login for your site. When the scan begins an authenticated crawl, it will open a new browser session and use this script to replicate your actions, performing the full login sequence from scratch.
Limitations for recorded login sequences in Burp Suite Enterprise Edition
Please be aware of the following limitations before deciding to use recorded login sequences:
Recorded logins are only compatible with browser-powered scans. If Burp Scanner fails to initialize its browser, the scan will fail to start.
- Browser-powered scanning is only available if you have Burp Scanner version 2020.10 or higher. If you have disabled automatic updates for Burp Scanner, you may need to upgrade this manually.
- To support browser-powered scanning, the machine on which the scan will run must meet the relevant system requirements.
- Recorded logins are not compatible with two-factor authentication, character-select passwords, or CAPTCHA.
Burp Scanner is currently unable to replay login sequences that rely on popups or
- When using recorded logins, Burp Scanner will not be able to self-register users or deliberately trigger login failures by submitting invalid credentials. As a result, any "Login functions" crawl settings from your scan configuration will be ignored.
- Depending on your authentication system, the repeated logins made during the scan may be flagged as suspicious. This could trigger additional authentication steps or anti-robot measures that the crawler is unable to handle. In this case, we recommend running the scan on a test instance with these checks disabled.
How to record a login sequence for Burp Suite Enterprise Edition
To record a login sequence for Burp Suite Enterprise Edition to use during scans, you need to perform the following steps:
- Open your Chrome browser and add the Burp Suite Navigation Recorder extension.
- In the upper-right corner of the browser, click on the icon for the extension. When prompted, click "Open settings" and enable the "Allow in Incognito" option.
- Click on the extension again and select "Start recording". A new incognito window opens.
- In the incognito window, browse to the target website. A red outline indicates that the window is being recorded.
- Complete the login sequence that you want to capture. Make sure that you enter the credentials that you want Burp Suite Enterprise Edition to use during scans.
- Perform the rest of the login sequence as required. Make sure that you finish on a page that will be in scope for scans of this site.
- When you're done, click the extension icon again and select "Stop recording". The generated script is automatically copied to your clipboard. If you made a mistake, you can click the icon again to re-record the login sequence. If you accidentally lose the script from your clipboard, you can also copy the last recorded sequence.
- In Burp Suite Enterprise Edition, create a new site or go to the "Details" tab for an existing site. Under "Application Logins". Select the "Add recorded login sequences" option.
- Add a label to help you remember which login sequence this is. Finally, paste the data from your clipboard into the "Paste Script" field and click "OK". The recorded sequence is added to the list of application logins.
You can now repeat this process for each set of credentials that you want to use for scans of this site. For example, you might record one login sequence in which you log in as a normal user and another sequence in which you log in as an administrator.
In order for Burp Scanner to perform your recorded login sequences, it needs to use Burp's browser. Scans of any sites for which you have uploaded recorded login sequences will automatically use the browser even if you have not enabled the "Use Burp's browser for Crawl and Audit" option in your scan configuration.
Troubleshooting recorded login sequences for Burp Suite Enterprise Edition
You might sometimes find that Burp Scanner is unable to replay a recorded login sequence during a scan. Although this won't cause the scan to fail completely, it will prevent it from performing an authenticated crawl. There are several steps you can take to troubleshoot these issues.
- Check the list of limitations to make sure that the login mechanism you are crawling is compatible with the recorded logins feature.
- Download the event log for the scan. To do this, select the scan, go to the "Reporting and logs" tab, then click "Download event log". The error messages might tell you whether the issue was with the login sequence itself or whether there was a general issue with the browser. Please be aware that some log entries may only represent temporary failures that were later resolved. For example, if the target site imposes rate limits, you might see many entries saying that the crawler was unable to log in. However, it may have logged in successfully later in the scan.
- Double-check that the login sequence finishes on a page that is in scope for scans of this site. Although the crawler will temporarily be allowed to follow out-of-scope links during the login process, after you complete the final action, the login sequence must redirect you to a page that is in scope.