Troubleshoot: SAML SSO

Use JumpCloud SAML Single Sign On (SSO) to give your users convenient but secure access to all their web applications with a single set of credentials. Use this page to troubleshoot common SAML Single Sign On (SSO) errors and connection issues. We'll continue to update this KB as we discover new solutions to SAML-related issues.

About SAML SSO

The following terms are used frequently:

• Service Provider (SP): A resource like a webpage or an app that you want to access.
• Identity Provider (IdP): A service that can authenticate you.
• Principal (User): The JumpCloud customer using this technology. 
• Single Sign On (SSO): A session and user authentication service that permits a user to use one set of login credentials such as a username and password to access multiple applications. 
• Security Assertion Markup Language (SAML): An open standard that defines a XML-based framework for exchanging authentication and authorization information between an identity provider (IdP) and a service provider (SP), to enable web-based single sign-on (SSO). While there are earlier versions of SAML, JumpCloud only supports SAML 2.0.

How SSO Works

Service Provider (SP) Initiated SSO:

1. A user accesses the SP’s SAML application.
2. The SP sends the user to the IdP for authentication.
3. If the user isn’t already logged in, the IdP authenticates the user. 
4. The IdP sends a response to the SP with the assertion for the user.
5. The user is successfully authenticated using SAML SSO.

Identity Provider (IdP) Initiated SSO:

1. A user accesses their IdP login page or dashboard.
2. If the user isn’t logged in yet, the IdP interacts with the user to provide authentication.
3. The user selects the SAML application they want to access.
4. The IdP sends a response to the SP with the assertion for the user.
5. The user is successfully authenticated using SAML SSO.

SAML/SSO Troubleshooting in JumpCloud

Service providers can differ in their SAML/SSO configurations, features, and functionality. Use the troubleshooting tips we provide and refer to the support pages provided by the SP vendor.

Take a moment to compare settings.

Review your current configuration against the configuration the SP recommends in their documentation. 

Does your SP actually support SAML 2.0?

It’s rare but some SPs support other versions of SAML.

Is your certificate valid?

• JumpCloud SAML SSO connectors support SHA-256 certificates by default. Although JumpCloud supports SHA-1 certificates, if the service provider supports it, we recommend using SHA-256 for stronger security.
• Some Service Providers want you to include the ===begin certificate=== and ===end certificate=== headers and footers when you add the certificate; others don’t. Confirm the requirements for this.

Are you using optional attributes?

• Make sure your attributes are supported by the service provider.
• Make sure the attributes are mapped properly to JumpCloud attributes and vice versa.

Can you successfully configure the SP using the GENERIC SAML 2.0 connector?

If so, there’s an issue with the pre-built connector. See SSO using Custom SAML Application Connectors.

Did you remember to give your users access to the SSO application in the JumpCloud Admin Console?

Users are implicitly denied access to applications. After you connect an application to JumpCloud, you must authorize user access to that application. See Authorize Users to an SSO App. 

How is the workflow being initiated?

SP initiated SSO isn't supported by all applications. Confirm with your Service Provider vendor that it can support this functionality. If the SP doesn’t support SP-Initiated SSO, it may support IdP-Initiated SSO.

Why isn't JIT working?

• Does it work with existing users? This is a good test to ensure that the authentication is working as expected, then move onto troubleshooting the Just-in-Time (JIT) provisioning.
• Not all SPs currently support Just-In-Time Provisioning (JIT). Confirm with your SP vendor that JIT is supported.

What, if any, information are you getting from error messages?

• The error messages returned provide a good starting point for troubleshooting if everything else seems to be correct or as expected. Sometimes the service provider has information on specific errors that are returned.
• Some SPs do provide a SAML logging tool, so you can actually see why SAML SSO failed.
• You can also Google your error message and find helpful information.
• See the following table for common error messages:

Have you used Chrome Tools to analyze what’s happening, network-wise?

See Inspect Network Activity in Chrome.

Submit a Support Case for a SAML/SSO Problem

If you continue to have SAML SSO problems, submit a support case. To provide effective support, here are some guidelines that will help JumpCloud Support help you.

Gather Information

Collect and include information that helps answer the following questions:

• How many users experience the issue? Just one user? All users?
• Is this an issue with a new setup, or is this an existing integration that's stopped working?
• How many applications does the issue affect?
• What is the expected behavior? What is the behavior you're seeing?
• How far through the login sequence does the user get?
• What error messages are you receiving when you try to use the application?
• Did you successfully configure the GENERIC SAML connector? Please include the configuration information for it as well.

Provide Screenshots of the SP and IdP (JumpCloud) Configurations

Capture screen shots of what you've configured in JumpCloud and the Service Provide. 

Provide a Copy of the Service Provider’s Metadata 

• The metadata file is an XML file that contains all of the information that the SP is expecting in a SAML assertion from an IdP, which is JumpCloud in this case. In the absence of any other documentation or guidance, it is the definitive source on how to configure the SAML SSO connector in JumpCloud. 
• If the SP doesn’t have or offer a metadata file, refer to the SP’s documentation.
• If the SP doesn’t provide any documentation for SAML and/or requires manual setup from their end to configure SAML, we recommend to contact the SP’s  support to complete the integration.
• The SP’s engineer should be able to complete the integration with our SAML KB articles; a joint call is typically unnecessary.

Generate and Send a .HAR File

• This step may be necessary if the SP provides no metadata or does not provide clear instructions on how to configure SAML.
• A .HAR file is an JSON-formatted archive file containing a collection of network information for a browser session. They can be very useful for troubleshooting advanced SAML issues and other network issues. Learn how to create and save a .HAR file.

Why can’t I just use a SAML decoder, instead of a .HAR?

A SAML extension is usually a subset of the information contained in a .HAR file. The job of the browser extension is to make it easier to expose only the information you need or want to see. The .HAR file is a more complete snapshot of the chronological network requests.Our engineering team requests a complete .HAR file for troubleshooting when a support case needs to be escalated to them.

Can I Request a SAML Connector if it doesn’t appear in your list of pre-configured connectors?

You can make a request for a new connector by submitting an idea from the Admin Portal. See Contact JumpCloud Support for instructions. If you are unsure if the functionality already exists, or if you need assistance with the service, please submit a support request instead. See a list of pre-built connectors.