Implementing SSO

If you use a SAML2-compatible single sign-on (SSO) implementation, the SSO Settings page can be used to configure an SSO Identity Provider (IdP) and allow permitted users to login to the runZero console.

runZero’s SSO implementation is designed to work with common SAML providers with minimal configuration, but there are a few requirements:

Your users need to authenticate to a single domain such as example.com, not to multiple domains or a domain with many subdomains.
The domain name needs to be configured in the SSO identity provider settings in runZero. This is true even for self-hosted runZero deployments.
Your SAML IdP should provide something that looks like an email address in the NameID parameter. It doesn’t need to be a valid email address, but it should be a unique value that has the same syntax as an email address (user@example.com).
If the NameID does not look like an email address, runZero will check the fields email, user.email, emailaddress and email address for a suitable ID.
runZero will check for the user’s full name in the fields name, gecos, user.name and displayname. If no full name field is found, runZero will proceed to check for a first name in first_name, firstname, given_name, user.firstname, givenname or first name; and for a last name in last_name, lastname, family_name, user.lastname, surname, sn, or last name. These attributes are case insensitive.

Note that you must be a superuser to manage runZero SSO settings.

Note: If a user first registers using SSO, they are marked as an SSO-only user, and cannot bypass SSO by setting up a regular password. For this reason, we strongly recommend that you set up and keep a non-SSO superuser account, so that you can update the settings if SSO stops working for any reason.

Specific SSO providers

You can refer to the Azure AD or Okta pages for details on configuring these providers. The basic steps for configuration are:

Add runZero as an application.
Set up SSO in runZero.
Provision users to the runZero app.

For other SSO providers, the following information will help you to configure things.

Identity provider settings

To get to the identity provider settings, choose Your team from the left navigator, then click the SSO Settings button at the top right of the page.

The identity provider settings form is where you enter information about your SSO identity provider.

The easiest way to configure SSO is to use XML metadata, if your SSO service provides it. This will usually require that you set up runZero as an application on your SSO provider, then download an XML file. The XML can be then opened in a text editor, and copied and pasted into the box at the bottom of the runZero identity provider settings form. If the XML decodes successfully, the key fields on the form will then be set automatically.

Single Sign On mode

You can choose whether to allow regular runZero accounts, SSO-provisioned accounts, or both.

If both are allowed, you can set up backup administrator accounts in case your SSO provider is unavailable.

Domain name

The domain name is used by runZero to locate the correct SSO IdP settings when users choose to log in via SSO. This is so that it can redirect them to the correct SSO provider to log in. For example, if the domain is example.com, the runZero login page will expect users to begin logging in by entering an address of the form username@example.com.

The domain is also passed back by the SSO provider after login, and used to fetch the SSO IdP settings so that runZero can verify and process the data.

The domain is included in the ACS URL in the login request sent to the SSO provider. If you change the domain, you will need to reconfigure the SSO provider to accept the new ACS URL.

Issuer URL

The issuer URL, also often referred to as the entity ID, is a URL your SSO provider uses to uniquely identify itself in data passed back to runZero. You need to obtain this value from your SSO provider. Note that the value is not normalized to add or remove trailing slashes; it needs to match exactly.

The login URL is the URL users should be redirected to in order to begin the login process for your SSO provider.

Certificate

The certificate is the PEM encoded CA certificate runZero will use to verify the signature on the data from your SSO provider.

If you paste multiple CA certificates into the box, your SSO provider will need to include a KeyInfo element in data passed back to runZero, to specify which certificate to check the signature against.

SSO walkthrough

To configure and debug SSO settings, it helps to understand how the SAML login process works.

SAML SSO login is carried out using messages passed by the user’s web browser. No direct connection occurs between runZero and the SSO identity provider (IdP) in either direction.

The normal login process starts with the user going to the runZero console login page, choosing Login via SSO, and entering their email address. The domain name of the email address is used to find the correct SSO identity provider settings in the runZero database.

runZero then redirects the user’s web browser to the Login URL specified in those SSO IdP settings. Some additional parameters are added to the URL, according to the SAML specifications. These are verified by the SSO IdP.

The user logs in on the SSO IdP website. The IdP then redirects the user’s web browser back to runZero, to the Assertion Consumer URL (ACS URL). The redirection includes a digitally signed blob of encoded data about the authenticated user. The ACS URL is shown on the service provider information tab of the SSO settings. Note that it includes the domain name, so that runZero can find the correct set of SSO settings to use to process the data.

runZero then decodes the encoded data, and checks its digital signature using the certificate that was provided as part of the identity provider settings. Assuming the certificate is valid, the decoded information about the user is then trusted by runZero. If necessary, a runZero user account is provisioned. The user is then logged in to begin a new runZero session.

Service provider information

After filling out the identity provider settings, you can switch to the service provider information tab to obtain information you need to provide to your SSO identity provider.

The Assertion Consumer URL, sometimes called the SSO URL, is the URL a person’s web browser will be redirected to after they log in successfully on the SSO identity provider. The URL contains the domain that was set up in the identity provider settings. runZero uses the domain to find the right set of SSO settings, so it can verify the data from the SSO provider. This means that if you change the domain in the identity provider settings for any reason, the ACS URL will change, and your SSO provider will need to be given the new URL.

The user login URL is a URL that you can visit to begin the login process. It displays the computed identity provider URL to aid in debugging.

Common problems

The most common cause of this problem is that the IdP has been configured with an Assertion Consumer URL that does not include the domain name that was set in the SSO identity provider settings in runZero, or includes the wrong domain name.

A correct ACS URL will look like https://console.runzero.com/auth/example.com/saml20/process where example.com is the domain name configured in the runZero SSO identity provider settings.

Missing x509 Element

The full error message is “invalid SAML response: error validating response: Missing x509 Element”

This error can occur if you have entered multiple CA certificates into the certificate field of the SSO settings in runZero, but your SSO IdP didn’t include a KeyInfo element to tell runZero which certificate to check the signature against. You will need to either configure your IdP to include information about which of the CA certificates to use as KeyInfo, or use a single CA certificate.

Updated September 12, 2024

Previous: Managing external users Next: Managing SSO group mappings