How to troubleshoot problematic SAML integrations

Objective

 To help troubleshoot and gather information regarding problematic SAML integrations.  This applies in SaaS or EOP situations. 

 This assumes you have already followed our documented process on SSO integration:

• SaaS
• On-prem

Issues

405/500 Errors

 If you are experiencing 405/500 errors when logging in for the first time after integrating SSO.

• Time for settings and propagation
  • SaaS: It can take 5-15 minutes before the new settings are migrated to all Contrast UI nodes.  
  • EOP: If you have multiple nodes, ensure the same changes have been made on all nodes and they have been restarted.

• Try using an incognito or private browser. 

Many times when first implementing SSO, the browser can end up causing some problems with cached data/tokens.  Try one of these modes or completely close your browser and try the login process again. 

• Try SP and IdP initiated login methods. 
  • SP initiated is when you start from the Service Provider. In this case starting at the Contrast UI.
  • IdP initiated is when you start from your Identity Provider. This would vary based on your company.  Examples: Okta, Ping, ADFS and Shibboleth. 

 Possible signature failures

• EOP: Check your contrast logs for exceptions indicating a Signature trust establishment failed around the SAML authentication.
• SaaS: Please log a case with support and we can quickly look into this for you. 

 Contrast UI version 3.6.8 and below: It may require the IdP's certificate (.pem) be uploaded with the IdP's metadata. 

 Contrast UI version 3.6.9 and up: These type of failures should be very infrequent. There may be a problem with the x509 certificate supplied by the idP's metadata.  This should be supplied in the metadata, valid and not expired. 

Two Factor Authentication is on

 Make sure Two Factor Authentication is turned off for the organization and users.  Once moving to SSO, the burden of 2FA shifts to the IdP.  Leaving this on can cause login problems after SSO integration. 

Make sure the user's e-mail address matches  

 Our SAML implementation relies on the user's e-mail address from the idP being mapped to the user's e-mail address in the Contrast UI.  Sometimes users may have several different formats to their e-mail address.  Ensure the one sent in the assertion from the IdP matches that which is stored in the Contrast Ui. 

Ensure the NameID is EmailAddress

IdP metadata entry should look similar to this:

<md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>

Ensure the NameID is defined in the subject

For our implementation the NameID must be part of the SAML subject.  The following error can be seen. 

The following error will be seen:

"NameID element must be present as part of the Subject in the Response message, please enable it in the IDP configuration"

EOP: see /contrast/data/logs/contrast.log

SaaS: Check with support

 Gathering information for further help

 Should none of the above tips help. Please capture a .har file while a user is attempting to login with SSO and failing. You can see how to do this in the linked article. 

For EOP: Also gather the /data/logs/contrast.log file.

Then please Submit a request to support for assistance.