Implementing SSO

View as Markdown

If you use a SAML2-compatible single sign-on (SSO) implementation, configure your SSO Identity Provider (IdP) on the SSO Settings page so permitted users can sign in to the runZero console.

runZero’s SSO implementation is designed for common SAML providers and needs minimal configuration. A few requirements apply:

  • Your users authenticate to a single domain such as example.com, not to multiple domains or a domain with many subdomains.
  • You configure that domain name in the SSO identity provider settings in runZero. This applies even to self-hosted runZero deployments.
  • Your SAML IdP should send something that looks like an email address in the standard NameID parameter. It doesn’t need to be a valid email address, but it should be a unique value with the syntax of one (user@example.com). The field name NameID is case sensitive.
  • If the NameID does not look like an email address, runZero checks the fields email, user.email, emailaddress and email address for a suitable ID. These field names are not case sensitive.
  • runZero looks for the user’s full name in the fields name, gecos, user.name and displayname. If none is present, it looks 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 field names are not case sensitive.

You must be a superuser to manage runZero SSO settings.

Once a user signs in with SSO, they can no longer sign in with a password, even if they could before. We strongly recommend that you set up and keep a non-SSO superuser account, so you can update the settings if SSO stops working for any reason.

Specific SSO providers

The Azure AD and Okta pages cover those providers in detail. The basic configuration steps are:

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

For other SSO providers, the following sections explain the settings you need.

Identity provider settings

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

The identity provider settings form takes the details of your SSO identity provider.

The easiest way to configure SSO is with XML metadata, if your SSO service provides it. You usually set up runZero as an application on your SSO provider, then download an XML file. Open the XML in a text editor and paste it into the box at the bottom of the runZero identity provider settings form. If the XML decodes successfully, the form fills in the main fields for you.

Single sign on mode

Choose whether to allow regular runZero accounts, SSO-provisioned accounts, or both. Allowing both lets you keep backup administrator accounts in case your SSO provider is unavailable.

Domain name

runZero uses the domain name to find the correct SSO IdP settings when a user chooses to sign in via SSO, so it can redirect them to the right SSO provider. For example, if the domain is example.com, the runZero sign-in page expects users to start by entering an address of the form username@example.com.

The SSO provider also passes the domain back after sign in, and runZero uses it to fetch the SSO IdP settings it needs to verify and process the data.

The domain is part of the ACS URL in the sign in request sent to the SSO provider. If you change the domain, you need to reconfigure the SSO provider to accept the new ACS URL.

Default role in any organization

The default role given to users the first time they sign in through SSO. It accepts the built-in roles, any custom role defined for the account, and Superuser.

No access is a common choice when anyone in your identity provider can sign in. New users then start with no organization access, and you grant access to the appropriate organizations after they first sign in.

If a custom role set here is deleted, users who enroll afterwards are created with no access rather than inheriting something unintended. Recreating the role restores the assignment for those users.

Roles assigned through SSO group mappings apply on top of this default.

Issuer URL

The issuer URL, often called the entity ID, is a URL your SSO provider uses to identify itself in data passed back to runZero. Get this value from your SSO provider. runZero does not normalize trailing slashes, so the value must match exactly.

Sign in URL

The sign-in URL is where runZero redirects users to begin the sign-in process at your SSO provider.

Certificate

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

If you paste multiple CA certificates into the box, your SSO provider needs to include a KeyInfo element in the data it passes back, to say which certificate runZero should check the signature against.

SSO walkthrough

Configuring and debugging SSO settings is easier when you know how the SAML sign-in process works.

SAML SSO authentication runs on messages passed through the user’s web browser. runZero and the SSO identity provider (IdP) never connect to each other directly, in either direction.

A normal sign-in starts when the user opens the runZero console sign-in page, chooses Sign in via SSO, and enters their email address. runZero uses the domain name of that address to find the correct SSO identity provider settings in its database.

runZero then redirects the user’s web browser to the Sign in URL from those settings, adding parameters to the URL as the SAML specifications require. The SSO IdP verifies those parameters.

The user signs in on the SSO IdP website. The IdP then redirects the browser back to runZero, to the Assertion Consumer URL (ACS URL), along with a digitally signed blob of encoded data about the authenticated user. The ACS URL appears on the service provider information tab of the SSO settings. It includes the domain name, which is how runZero finds the correct set of SSO settings to process the data.

runZero decodes the data and checks its digital signature against the certificate from the identity provider settings. If the certificate is valid, runZero trusts the decoded information about the user, provisions a runZero user account if necessary, and signs the user in to a new runZero session.

Service provider information

After you fill out the identity provider settings, switch to the service provider information tab for the values your SSO identity provider needs from runZero.

The Assertion Consumer URL, sometimes called the SSO URL, is where the SSO identity provider redirects a person’s web browser after they sign in successfully. The URL contains the domain from the identity provider settings, which runZero uses to find the right set of SSO settings and verify the data from the SSO provider. If you change the domain in the identity provider settings for any reason, the ACS URL changes, and your SSO provider needs the new URL.

The user sign-in URL is a URL you can visit to begin the sign-in process. It displays the computed identity provider URL to help with debugging.

Common problems

A user signs in on the SSO provider, but runZero refuses the sign in

The most common cause is an Assertion Consumer URL on the IdP that is missing the domain name set in the runZero SSO identity provider settings, or that has the wrong domain name.

A correct ACS URL looks 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 entered multiple CA certificates in the certificate field of the runZero SSO settings but your SSO IdP didn’t include a KeyInfo element saying which certificate to check the signature against. Either configure your IdP to send KeyInfo naming the CA certificate to use, or use a single CA certificate.

Updated