SAML SSO errors

This is a list of SSO errors that can be issued by runZero when attempting single sign-on, and what they indicate.

invalid audience

Each SAML response has a set of conditions specifying where and when it may be used. For example:

<saml2:Conditions NotBefore="2021-12-08T16:11:04.971Z" NotOnOrAfter="2021-12-08T16:21:04.971Z">
  <saml2:AudienceRestriction>
    <saml2:Audience>https://console.runzero.com</saml2:Audience>
  </saml2:AudienceRestriction>
</saml2:Conditions>

The audience restriction specifies the URL of the SP that should accept the SAML login. It's generally the URL of the runZero console. This error likely indicates that your SSO provider has the wrong URL configured as the Audience URL.

For a self-hosted environment, the runZero RUNZERO_CONSOLE value in the runZero server configuration should be the server URL with no trailing slash; for example, https://runzero.example.com. The configured audience URL in your SSO system should match that value exactly. The server log will contain an error listing the expected SP URL and the audience assertions from the SAML payload.

invalid time

Similarly to the "invalid audience" error, this indicates a problem with the Conditions in the SAML response. In this case, the problem is with the NotBefore or NotOnOrAfter attributes:

<saml2:Conditions NotBefore="2021-12-08T16:11:04.971Z" NotOnOrAfter="2021-12-08T16:21:04.971Z">

These determine the validity period for the SAML response, and must be timestamps in RFC 3339 format. Most likely, your SSO provider specified a time range that had either not started yet or had finished by the time runZero received the SSO response.

A common cause for this error is if the SSO provider is on a system with an inaccurate system clock. SSO providers should generally have their time synced using NTP.

error validating XML

This indicates that the SAML payload contained invalid XML. It almost certainly represents an error on the SSO side. One possibility is that the SSO provider is configured to use something other than SAML with runZero, such as OpenID Connect, LDAP, or OAuth 2.

invalid SAML response

This indicates a general error parsing the SAML response. A common cause is "Cert is not valid at this time", which indicates that the X.509 certificate the SSO IdP server is using has expired.

Another possible cause of this error is that the SAML response is missing required elements listed in the specification. If you use the browser developer tools, you can find the SAML payload that was sent to /auth/<your domain>/saml20/process, and check it using a validator such as https://samltool.io/

Note that the SAML payload is sent using base64 encoding, even though it's XML, to reduce the chances of corruption in transit.

404 not found

This error is issued when the SAML SSO provider redirects you to the wrong URL on the runZero console. The URL path should include the domain configured under "Client ID or Domain" in the runZero SSO settings, for example:

https://console.runzero.com/auth/example.com/saml20/process

This URL is generally known as the ACS URL (Assertion Consumer) in the SSO provider configuration.

SSO is not configured

This indicates missing or invalid information in your SSO configuration in runZero. Please refer to the documentation on how to configure SSO at https://www.runzero.com/docs/implementing-sso