Note: Single Sign-On is only available on our Enterprise plans. Users with System privilege can set up or manage Single Sing-On settings.
Single Sign-On can be tricky to troubleshoot due to the array of different factors and variables involved. That said, most of the issues that clients report regarding their SSO implementation in Cascade fall into one of the categories below.
Note that these issues are 'provider agnostic' in that Cascade supports SSO with most SAML 2.0 providers (literally hundreds) so it's not possible to provide detailed examples for each provider. However the common problems outlined below are a good start to tracking down your specific issue:
Quick Tip - Use a SAML Tracer
With SAML 2.0 troubleshooting iterations, at some point it may be necessary to confirm/view the attributes that are actually being released from your identity provider and sent to Cascade during the authentication process. If the attributes from the identity provider are NOT encrypted in the SAML response, the Firefox browser SAML tracer Add-on or Chrome SAML Message Decoder can be used to view the attributes.
401 / Unauthorized Errors
If you're getting an error message after attempting to login similar to a '401' message, there are many reasons this could happen but the two common ones we see is either an invalid or mismatched x509 certificate set in Cascade or a mismatch between the username in Cascade and what's sent from your IdP.
To troubleshoot, first check if your x509 certificate in Cascade is valid (for example no return character, tags, etc) and if it matches the one in your identity provider.
If everything else is set up all correctly, check the username in Cascade and make sure it matches the one sent from your identity provider. For example if Jim's username in Cascade is 'jim' but your identity provider is trying to log in as ' jim@email.com', it will return a 401 error because the username cannot be found in Cascade. In this case, update the username format from Admin Organisation Users (you need Organisation privilege for this) should fix this error.
404 Error / Unable to download metadata
Users with System privilege can download metadata from Cascade at https://.executestrategy.net/api/v2/identity_providers//metadata. If you are getting a 404 error when trying to download metadata, first of all, make sure you have at least one identity provider record saved in Cascade. If you have multiple identity provider set up in Cascade, you can update or increment the identity provider ID in the URL to download your metadata.