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.

To enable form-based authentication, navigate to Site → Settings → Agent Settings and check This Site requires authentication box. Provide a URL to your login form, username, password and CSS selectors for the form and 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 valid HTML markup to be able 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. [type='submit'][value='Sign in']
  2. [type='submit'][value='Next']
  3. [type='button']
  4. button
  5. [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. Learn more about Recognising the Calibre Agent.

Test Profiles: Cookies and Custom Headers

Test Profiles allow changing the conditions that your Sites are tested under, including authentication. You can add authentication to selected or all Test Profiles with Cookies or Custom Headers. This method will be useful in cases when Form Authentication is not sufficient, such as more complex authentication flows, which have confirmation steps that can be bypassed with a cookie.

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.

The Calibre Agent will use the set Cookie or Custom 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.

Related Articles