Troubleshooting Single Sign-On (SSO)

SSO (Single Sign-On) is useful for enterprises that prefer to manage users and permissions in a single internal system known as an identity provider (or IdP). IdPs control all internal and third-party tools users can access. SSO eliminates or dramatically reduces the need for multiple logins, as individuals maintain a single sign-on.  

This article explains how to use SSO in Uptime.com, as well as some of the basic troubleshooting steps for common SSO issues.

First, we will explain how SSO works in Uptime.com. Next we’ll talk about common causes of errors and suggest some quick fixes.

SSO is available in all Uptime.com plans except the Basic plan.

Using SSO with Uptime.com

To setup or disable SSO in Uptime.com, go to Settings>SSO. 

The most common technology or protocol used for SSO today is SAML2 (Security Assertion Markup Language 2.0), a secure method to authenticate the enterprise's user management system (or IdP) and a third-party service, known as the Service Provider (or SP).

When using SSO, Uptime.com is acting as the SP.

Uptime.com provides you with three values to properly configure SSO:

  • EntityID (or Audience URI)
  • ACS URL (or Consumer URL)
  • WAYFless URL (an optional parameter).

SSO.png

Your IdP configuration will ask you for an EntityID, Audience Restriction, or Audience URI. In all of the previously mentioned situations, you will provide the EntityID that Uptime.com has listed. This is a unique identifier for Uptime.com that defines it as the SP.

The IdP will also require an ACS URL. This is the location your IdP uses to send SAML assertions. This URL is how Uptime.com “listens” for requests.

A WAYFless URL allows you to log in directly to Uptime.com from your IdP.  

You will need to provide Uptime.com your IdP EntityID, as well as the URL that will trigger your SSO login. The SSO Target URL will display the usual Uptime.com login screen, but utilize credentials created for SSO purposes. Finally, we require a valid X.509 IdP Certificate in PEM format for signing by the IdP.SSO-2.png

 

Now that we’ve established some basics, let’s look at some common problems and solutions.

Basic SSO Troubleshooting

We provide an error page when Uptime.com encounters an SSO error. We collect some technical detail about the error, but the context for SSO errors can be difficult to pinpoint. We’ve created something of a roadmap to use when you encounter the error page, which should help identify key causes for failures and correct them.

The first troubleshooting steps involve checking that a few values are entered correctly within your IdP configuration. The three most common IdP configuration errors when using SSO with Uptime.com are:

  • SAML Assertion Was Not Signed
  • SAML Assertion Missing Username
  • Incorrect SAML Issuer (EntityID)

The sections below detail corrective actions that address these problems in this order. Testing these errors in this order carries a higher likelihood of troubleshooting success.

SAML Assertion Was Not Signed

Every SAML assertion requires an IdP certificate signature. While it’s possible that the entire response was signed (which is optional), this is insufficient. The assertion itself is what requires a signature. Be sure that your IdP configuration signs the SAML assertion (and not the entire response) with an IdP certificate.  

Verify that you are using a valid X.509 Certificate in PEM format, then paste this certificate into the IdP Certificate field.

SAML Assertion Missing Username

The IdP must send details of the user’s identity as SAML attributes to verify for usage. Uptime.com requires three details:

  • The user's email, one of: Email  / User.Email  / eduPersonPrincipalName
  • The user's first name, one of: FirstName  / User.FirstName  / givenName
  • The user's last name, one of: LastName  / User.LastName  / sn

Therefore, the next IdP configuration setting to review for accuracy would be Email, User.Email or eduPersonPrincipalName, then the first name, then the user’s last name.

If you use OneLogin, you can provide those attributes using the SAML Test Connector (IdP w/attr.)

Incorrect SAML Issuer (EntityID)

Once we’ve established the login is correct, and verified our SAML assertion is correctly signed, we can diagnose an incorrect Issuer or EntityID.

Uptime.com will check for an appropriate metadata entry for the Issuer specified in the SAML response when checking an assertion. Quite often, due to mismatches with http vs. https (or other typos), the IdP EntityID doesn’t match what was filled in in the Uptime.com SAML Setup form. Verify that you have provided the correct EntityID before moving on to more testing.

Double-checking these values fixes the most common errors, so please verify the EntityID, User Attributes, and Assertion Signing first before you move on to more advanced troubleshooting.

More Advanced Troubleshooting

These errors are less frequent, but the solutions listed below tend to cover most Uptime.com support issues that were not corrected by the steps above. Begin this section after completing the tests listed in the section above.

Assertion Missing Subject NameID

Uptime requires that a SAML assertion contains a Subject NameID with a valid NameQualifier which uniquely identifies the user. Ideally, this would be the user’s email, the same value as the Username attribute referred to above.

Inside the SAML assertion the code looks like so:

<saml:Subject>
   <saml:NameID SPNameQualifier="xxx">joe@noemail.com</saml:NameID>
</saml:Subject>

This Subject/NameID node is required by our SAML library.

For a detailed live example, refer to this page.

To fix this error, verify that the Subject and NameID nodes are present in your assertion and contain a proper NameQualifier.

SSO Login Does Not Work from Uptime Form

This error tells us that the IdP is not accepting the login request originating from Uptime’s login form for some reason. It gives us the generic status code urn:oasis:names:tc:SAML:2.0:status:Responder, and no identity assertion.

Microsoft describes this error as “The request could not be performed due to an error on the part of the SAML responder or SAML authority.”

Users should review all relevant fields within the IdP and Uptime.com for accuracy. After a review, please gather all technical data available from your IdP and submit a support ticket to Uptime.com.

Final Thoughts

If these steps did not solve your SSO issues, please submit a ticket and be sure to detail the support steps you have already taken so we can better serve you.

SSO/SAML is an elegant tool that compliments enterprise software suites well. Our goal is to provide you with seamless integration into your current workflow.