Authentication (Scanning Pages Behind a Login)

Many of the pages that matter most - member dashboards, account settings, checkout steps, internal tools - are only visible after signing in. Without authentication, a scheduled scan sees what an anonymous visitor sees: the login screen or an "access denied" page. The score you get back describes that page, not your actual application.

With Authentication enabled, QualiBooth signs in first and then scans your pages exactly as a logged-in user experiences them.

Authentication is configured per scan configuration, so you can have one configuration for your public pages and another for the area behind the login.

Note: Authentication is available for Scheduled Scanning only. Real-Time Scanning already runs inside your visitors' browsers, so it always sees authenticated pages without any extra setup.

Before You Start

We strongly recommend creating a dedicated test account for scanning instead of using a real person's credentials:

• Give it the same visibility as a normal user, so scans reflect the real experience
• Avoid accounts with administrative or destructive permissions (delete, publish, refund, purchase)
• Avoid accounts protected by two-factor authentication or any other additional verification step (see What Your Login Page Needs)
• Exclude pages that trigger irreversible actions from the configuration's URL list

A scan visits pages the way a browser does. Any page that performs an action just by being opened may perform that action during a scan.

What Your Login Page Needs

A scan signs in the way a visitor would: it opens your login page, fills in the two fields and submits. For that to work, your login page has to meet a few conditions.

The sign-in form must be visible as soon as the login page opens. QualiBooth looks for the username and password fields on the page it lands on. If the form only appears after an interaction - clicking a "Sign in" or "Log in with email" button, opening a pop-up or modal window, switching a tab, or expanding a section - the scan will not find it and cannot sign in.

Note: Selector overrides do not work around this. The fields have to already be present and visible on the page; pointing at a field that does not exist yet has nothing to fill in.

If your login form is behind an interaction, check whether your application also has a direct address that shows the form on its own (many do, for example https://example.com/login rather than the home page with a sign-in button). Use that address as the Login page URL. If no such address exists, your development team can usually provide one.

Username and password must be on the same page. Logins that ask for the username first and the password on a following screen are not supported.

No additional verification step. A scan can only supply a username and a password, so it cannot complete:

• Two-factor authentication (2FA/MFA) - one-time codes, authenticator apps, SMS codes, email codes or hardware keys
• CAPTCHA and bot challenges - "I'm not a robot" checkboxes, image puzzles, or invisible bot-protection challenges on the login page
• Security questions, device confirmation or "approve this sign-in" prompts

Use a scanning account that is exempt from these steps, or run scans against an environment where they are not enforced. Your development or security team can normally exempt a single service account, or allowlist the QualiBooth scanning IP addresses so the challenge is not triggered.

Nothing should cover the sign-in button. A cookie or consent dialog displayed on top of the form can prevent the scan from submitting it. If your login page shows one, ask your team whether it can be suppressed for the QualiBooth scanning IP addresses.

Note: If no sign-in form is visible where the scan lands, QualiBooth assumes it is already signed in and continues. In that case the scan reports the signed-out view of your pages, or the pages fail once QualiBooth detects it is not signed in - so a login page that hides its form usually shows up as failed pages or unexpectedly low scores rather than as a single obvious error. When results look like the anonymous view, this is the first thing to check.

Where to Find It

Authentication lives in the scan configuration editor:

1. Go to My Sites and select your website
2. Click Scheduled Scanning
3. Open an existing configuration, or click Add New Configuration
4. Expand the Access & network section

The configuration editor is organized into three collapsible sections so the form stays easy to read:

Section	What it contains
Basics	Display name, rate limiting, scan frequency
Scanning options	WCAG 2.2 AA and WCAG AAA rules, or inherit organization settings
Access & network	Proxy settings and Authentication

Each collapsed section shows a short summary of its current state (for example "Authentication: form login"), so you can see at a glance whether authentication is configured without expanding anything. All sections are saved together with a single Save action.

Choosing an Authentication Method

Option	Use it when
No authentication	Your pages are publicly accessible. This is the default for every new configuration.
Form login	Your site has a normal sign-in page with username/email and password fields. This covers most websites and applications, including sites using single sign-on.
HTTP Basic	Your site is protected by the browser's own pop-up sign-in prompt - common on staging and pre-production environments.

If you are not sure which one you need, open the protected page in a private browser window:

• You are taken to a page with a sign-in form → choose Form login
• A small browser dialog appears asking for a username and password before any page loads → choose HTTP Basic

Setting Up Form Login

1. Expand Access & network
2. Under Authentication, select Form login
3. Fill in:
   • Login page URL - the full web address of the page holding your sign-in form, including https:// (for example https://example.com/login)
   • Username - the account the scan signs in with
   • Password - the account's password
4. Click Save

From that point on, every scheduled and on-demand run of this configuration signs in before scanning.

QualiBooth finds the username field, the password field and the sign-in button on your login page automatically - you do not need to describe your page's structure. This works even when the fields have non-standard names, and when the form is built with a component framework.

The address you enter must open directly onto the visible sign-in form - see What Your Login Page Needs. If the form is present but cannot be identified automatically, see Advanced: Overriding Automatic Detection.

Single Sign-On (SSO)

Sites that use an identity provider - Microsoft Entra ID, Okta, Keycloak, Google Workspace and similar - are supported. In these setups your login page lives on a different address than your website (for example login.example.com while the site itself is app.example.com).

Enter the address of the page where you actually type your username and password. QualiBooth opens your site, lets it start its own sign-in flow, and completes the sign-in on the identity provider's page.

You can copy the address straight out of your browser's address bar while on the sign-in page - any extra parameters in the address are ignored.

Setting Up HTTP Basic

1. Expand Access & network
2. Under Authentication, select HTTP Basic
3. Enter the Username and Password
4. Click Save

There is no login page address to provide here, because there is no form to fill in - the credentials are handed straight to the browser's prompt.

HTTP Basic and proxy credentials cannot be combined. If this configuration uses a proxy that requires its own username and password, HTTP Basic cannot be used - a browser can only present one set of credentials for both requests. QualiBooth shows a message as soon as it detects the conflict and prevents saving.

To resolve it, either switch to Form login, or remove the proxy username under Proxy Settings (for a custom proxy) or Settings → Proxy Configuration (for the organization proxy).

Updating and Removing Authentication

• Reopening the editor - your login page address and username are shown as you entered them. The password is always shown masked, never in readable form.
• Changing other settings - leave the password field untouched and your stored password is kept as it is. Type a new password only when you want to replace it.
• Turning authentication off - select No authentication and save. The stored credentials are removed and later runs scan anonymously. Turning authentication back on starts from empty fields; previous credentials are not restored.
• While a scan is running - credentials are captured at the moment a run starts, so any change you save applies from the next run onwards, not to the run already in progress.
• Copying a configuration - the copy targets the same website, so it carries the same credentials (username visible, password masked).

Permissions

Only users who can manage scan configurations can view or change authentication settings. Other users see a read-only summary showing the method, the login page address and the username - the password is never included, in any form.

Advanced: Overriding Automatic Detection

Automatic detection handles the vast majority of login forms, including forms whose fields use non-standard names. If a scan reports that the login form could not be found, you can point QualiBooth at the right elements yourself. Typical cases where this is needed:

• The username or password box is a custom component rather than a normal input field
• The fields use unusual names or identifiers that do not resemble a username, e-mail or password field (for example field_1 and field_2, or names in a language other than English)
• The sign-in control is not a standard button - a link, an icon or a custom element
• The page contains more than one form with a password field, such as a sign-in form and a registration or password-change form side by side, and the wrong one is picked up
• The scan cannot tell whether sign-in succeeded, so you want to name an element that only appears once the user is signed in

Expand Advanced - override automatic detection under Form login. Four optional fields are available:

Field	What it identifies
Username field selector	The box where the username or email is typed
Password field selector	The box where the password is typed
Submit control selector	The button or control that submits the form
Login success indicator selector	An element that only appears once sign-in has succeeded - for example a dashboard container or a sign-out link

Each field takes a CSS selector, the same short identifier a developer uses to point at an element on a page - for example #username, .login-form input[name="email"] or button[type=submit]. Your web or development team can provide these in a couple of minutes using the browser's Inspect tool.

Notes:

• All four fields are optional, and they work independently. Fill in only the ones that need correcting; anything left empty continues to be detected automatically.
• Clearing a field returns it to automatic detection.
• If overrides are saved, the advanced area opens automatically when you reopen the editor, and its summary shows how many overrides are in effect - so they never take effect invisibly.
• Overrides cannot make an unsupported login work. A form that is only revealed after a click, a two-step login, a one-time code or a CAPTCHA still cannot be completed by a scan - see What Your Login Page Needs.

When a Scan Cannot Sign In

If sign-in fails, the affected pages are reported as Failed in the scan results, with the reason shown next to the status. Open Scan Results for the run and filter by status to review them.

Authentication failures are not retried with the same credentials, so a run finishes promptly instead of repeatedly attempting a sign-in that cannot succeed. The rest of the run still completes and its results are recorded as usual.

Common reasons and what to do:

Reported reason	What it means	How to fix it
Credentials rejected	The username or password was not accepted, or the site is still on the login page after submitting	Verify the credentials by signing in manually; check the account is not locked or expired
Login form not found	The sign-in form could not be identified on the page - most often because it is only shown after a click, or because its fields are custom components	Confirm the Login page URL opens directly onto the visible form (requirements); if the form is visible but still not found, supply selector overrides
Two-step login unsupported	The site asks for the username on one page and the password on the next	Not currently supported - see What Your Login Page Needs
Navigation failed	The login page could not be reached	Check the address, and whether the page is reachable from outside your network. A proxy or IP allowlisting may be required
Session lost	Sign-in succeeded but the session ended part-way through the run	Usually a short session timeout on the site. QualiBooth signs in again automatically; if it recurs, ask your team whether the session lifetime can be extended for the scanning account
Configuration invalid	The sign-in flow led somewhere unexpected, so no credentials were submitted	Re-check the Login page URL - it must be the address where credentials are actually entered

QualiBooth also captures a screenshot of the page at the moment sign-in failed, and the failure reason includes a reference to it. This makes it easy to tell "the password was wrong" apart from "an error page was displayed". If you need the screenshot itself, share the reason text with QualiBooth support and we will retrieve it for you.

Note: QualiBooth checks after each page that it is still signed in. If your site has signed the scan out, it signs in again and continues, rather than scoring a login page and reporting it as a successful scan.

Limitations

A scan can supply a username and a password on a single visible form, and nothing more. The following are not supported:

• Login forms revealed by an interaction - a form that appears only after clicking a "Sign in" button, or inside a pop-up, modal, tab or expandable section. The form must be visible when the login page opens.
• Two-step logins - where the username is submitted on one page and the password requested on the next. These are detected and reported clearly rather than counted as a successful sign-in.
• Two-factor authentication (2FA/MFA) - one-time codes, authenticator apps, SMS codes, e-mail codes and hardware keys cannot be completed by a scan. Use an account exempt from the second factor, or restrict scans to an environment where it is not enforced.
• CAPTCHA and bot challenges on the login page - a challenge designed to stop automated sign-in will also stop the scan. Ask your team to exempt the scanning account or to allowlist the QualiBooth scanning IP addresses.
• Additional confirmation steps - security questions, device approval, or "confirm this sign-in" prompts sent by e-mail or app.
• Some app-based sign-in systems - a small number of applications store the session in a way that cannot be carried between pages. Scanning still works; the scan simply signs in again for each page, which makes the run slower.

Full details and workarounds are in What Your Login Page Needs.

How Your Credentials Are Handled

• The password is stored encrypted and is never displayed back to you - the editor shows a fixed mask, never the stored value.
• Credentials are only ever entered on your own login page. If a sign-in flow leads to an unexpected address, the scan stops with an error instead of submitting them.
• The signed-in session is reused only across pages of the same website within the same run, and is discarded when the run completes.
• Changing the password automatically invalidates any session held from an earlier sign-in.
• Credentials are never written to your browser's console, analytics or error reports.

Related Pages

• Add New Configuration - all other scan configuration settings
• Proxy Configuration - reaching sites restricted by network or region
• Scan Results - reviewing a run, including failed pages