Authenticating Calibre

Calibre can authenticate to your protected websites and applications to monitor performance. Below, you can find 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 → Authentication. In the Form Authentication section, provide a URL to your login form, username, password and CSS selectors for the form and relevant inputs.

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 monitored instead of the logged in page. 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.

Elements must be visible and within the main document

For Calibre to successfully navigate HTML forms, form elements must meet the following prerequisites:

• Elements should not be visually obstructed (hidden off-screen or using CSS opacity with value less than 1)
• Elements must appear within the main document (e.g., not nested within an <iframe>)
• Elements must respond to event handlers (e.g., click or submit)

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"]
3. [type='submit'][value='Sign in']
4. [type='submit'][value='Next']
5. [type='button']
6. button
7. [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.

Multi-step forms

Calibre can walk through multi-step forms. Set the Submit selector to target the submit button used in each step of your form, e.g.: #continue[type=submit], #signInSubmit[type=submit].

Using the example selectors above, Calibre will search for elements matching #continue and #signInSubmit and click the first matching element it finds.

Basic Authentication

Basic authentication is a simple way to authenticate built into the HTTP protocol. When Calibre Test Agent requests your Site, you can pass credentials in Authorization: Basic <credentials> header. The credentials have to be Base64-encoded.

To enable basic authentication, add a header to Agent Settings or a Test Profile with the following format:

• Name: Authorization
• Value: Basic Base64-encoded username:password

You can generate the Base64-encoded string using the base64 command in a terminal:

1echo -n 'username:password' | base64

For more information about Authorization headers, see MDN Authorization documentation.

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:

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.

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

Dynamically updating Cookies and Headers

You can use the Calibre API to dynamically update Site or Test Profile headers and cookies. If you have a custom authentication method, you can perform authentication steps and then use the API to update Calibre with current credentials.

Getting help

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