Authenticating Calibre

Calibre can authenticate to your protected websites and applications to monitor performance. There are several ways of recognising The Calibre Agent that might suit your needs.

Form Authentication

Calibre can log into your sites and applications as if it was one of your users. Form authentication supports the most common types of single and multi-step log in forms. Two-factor authentication (2FA) is not supported.

Adding form authentication to your Site

To enable form-based authentication, navigate to Site → Settings → Agent Settings. In the Form Authentication section, provide a URL to your login form, username, password and CSS selectors for the form and relevant inputs.

Credentials will be stored in clear text. We recommend that you create a special test account for Calibre.

Troubleshooting Form Authentication

Choose correct selectors

If Calibre cannot find the form on the page, the test will either fail or result in the form URL being tracked instead of the logged in version. To ensure authentication succeeds, use form and input selectors with high specificity, such as id or name.

Recommended: #sign-in-form, #login, #username, input[name="username"] or input[type="password"].

Not recommended: form, input, body, html, div, section.

Use semantic HTML markup

Calibre searches for a specified Submit selector first. If the selector is not found or not provided, the Test Agents will fall back to looking for valid HTML markup to submit the form and begin monitoring. A valid submission button should have one of the following characteristics:

  • be a button element.
  • have ARIA button role (role="button).
  • have the type of submit.

Non-semantic markup and multiple elements fulfilling the above requirements might cause failed tests. Calibre scans your Sites for submission buttons in the following order:

  1. Selector provided in Submit selector field
  2. [type='submit'][value='Sign in']
  3. [type='submit'][value='Next']
  4. [type='button']
  5. button
  6. [role='button']

Allow Calibre Agent IPs

In some cases, authentication might fail even when form-based authentication has been set up correctly. We recommend allowing Calibre Agent IP addresses to ensure Calibre can successfully view your sites and applications.

Cookies and Headers

When Form Authentication is not sufficient (for example, in the case of more complex authentication flows, which have confirmation steps), we recommend using Cookies or Headers to authenticate your sites and applications.

You can add authentication to specific Test Profiles, or globally at Test Agent level.

Test Profile Cookies and Headers

Test Profiles allow changing the conditions that your Sites are tested under, including authentication. To add Cookies or Headers to Test Profiles, navigate to Site → Settings → Test Profiles and choose a relevant Test Profile. Click Add a header or Add a cookie button to create a new one, then save the profile information:

Adding Headers and Cookies in Test Profiles
Cookies and Headers set in Test Profiles override Test Agent Cookies and Headers. Use Test Agent settings for global authentication and Test Profiles for more granular settings.

The Calibre Agent will use the set Cookie or Header when making requests to your Site.

Test Agent Cookies and Headers

To add Cookies or Headers to the Test Agent, navigate to Site → Settings → Test Agent. Click Add a header or Add a cookie button to create a new one, then save it.

Adding a Header at Test Agent level

The Calibre Agent will use the set Cookie or Header when making requests to your Site.

Getting help

If none of the above options quite work with your environment, reach out to our technical support team for further assistance.