Configuring & 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 setup SSO with Uptime.com, and provides some basic troubleshooting steps for common SSO issues.

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

Table of Contents

Use these links to troubleshoot SSO depending on the error returned during the configuration process.

Uptime.com has partnered with the following SSO Identity Providers, and users should refer to these instructions as applicable:

Using SSO with Uptime.com

Return

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. The process looks like this:

  1. The user attempts to sign into Uptime.com from the IdP
  2. IdP verifies the user credentials match those from Uptime.com
  3. IdP logs the user into Uptime.com

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).

IDP Values

Your IdP configuration will require an EntityID, Audience Restriction, or Audience URI from any SP providing SSO.

The EntityID is a unique identifier for Uptime.com that defines it as the SP.

The IdP will also require an ACS URL, or a location your IdP will use to send SAML assertions. The SP (Uptime.com) “listens” for requests at this URL.

A WAYFless URL allows you to log in directly to Uptime.com from your IdP. It’s useful for testing your SSO is configured properly by completing the first handshake and logging into Uptime.com.

SP Values

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 trigger a login through the user’s IdP. Once the user logs into the IdP, this link redirects to Uptime and authenticates the user.

Finally, we require a valid X.509 IdP Certificate in PEM format for signing by the IdP.

Now that we’ve established some basics, let’s setup SSO.

SSO Setup Instructions

Return

The following instructions assume you have prepared your IdP platform for Single Sign On capabilities, including enabling or installing any SSO related applications specific to your platform.

Step One: Register the Uptime.com Application with your IdP

ACS stands for Assertion Control Service, or more generally the Consumer URL, and it’s the URL where SAML assertions are sent. Copy and paste the ACS/Consumer URL into the Single Sign On/ACS URL field of your provider.

Paste the EntityID/Audience URI value into the Audience Restriction or EntityID field of your SSO provider.

If you receive an error related to ACS or Audience URI, click here.

register-Uptime.png

This step also requires you define the extra information the IdP must send with an authenticated login request. These attributes identify a user, and can create a corresponding user in Uptime.com based on the user’s IdP credentials. NOTE:These attributes are case sensitive. Please ensure the following attributes are enabled and sent through your IdP's configuration interface:

  • An SAML user unique identifier, expressed as: NameID / Subject NameID
  • The user's email, expressed as: Email  / User.Email  / eduPersonPrincipalName
  • The user's first name, expressed as: FirstName  / User.FirstName  / givenName
  • The user's last name, expressed as: LastName  / User.LastName  / sn

These attributes are case sensitive. You can use the bolded values above to identify these attributes.

The NameID is often an email address that matches the Email/User.Email value.

If you receive an error related to Missing SAML Assertions, click here.

Step Two: Paste in the SSO Login Details and Certificate of Your IdP

Uptime.com, requires an EntityID from the IdP. Additionally, you must supply the URL that triggers the SSO login with your IdP.

values-from-IDP.png

The final steps in your SSO configuration are to download the IdP X.509 certificate, and paste it into Uptime.com.

Please ensure this certificate is in PEM format.

NOTE: Uptime.com supports SHA 256. Check the box for “Use legacy SHA-1 for signing instead of the recommended SHA-256” if your provider does not support SHA-256.

Final Step: Testing

Once you believe you have configured your SSO with Uptime.com, test the process. There are several error screens built into the SSO process that provide some information that may assist you in troubleshooting.

Users are advised to use the optional WAYfless URL for testing purposes to complete the first SSO “handshake”. The WAYfless URL will connect to Uptime.com via the IdP you configured, and will present any errors this process encounters along the way.

More troubleshooting information is below.

Basic SSO Troubleshooting

Return

We provide an error page each time Uptime.com encounters an SSO error. This roadmap is intended to provide a set of troubleshooting steps you can take depending on the error screen you may encounter during setup.

We first suggest checking that each value from the above steps have been 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

Return

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

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.  

If you have used the certificate your IdP has provided, and are still seeing this error, contact your IdP to request a properly formatted and current certificate. Once you verify current details, contact Uptime.com for support.

SAML Assertion Missing Username

Return

Verify that your NameID, Email, FirstName and LastName are required attributes, and that they match the user’s details on their Contact screen.

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

  • An SAML user unique identifier, expressed as: NameID / Subject NameID
  • 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

Review these fields for accuracy.

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

If the error persists, try turning off encryption to avoid any potential errors with encoding.

Incorrect SAML Issuer (EntityID)

Return

Verify the EntityID matches your IdP.

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 sent in the SAML assertion 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

Return

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

Return

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.