Troubleshooting SSO: SAML Trace

When investigating Account Provisioning errors it can be useful to capture a SAML trace and observe the exact information being transmitted in the SAML assertion. To capture a SAML trace you will need a browser compatible tool which analyzes SAML and network events. A free browser add-on would be:

• Google Chrome:
  • saml-tracer
• Firefox:
  • saml-tracer

With your tool prepared you can now analyze network events and parse out a SAML event. The tool saml-tracer must be open before attempting to capture the event as it does not look back historically. With the tool open, proceed through the following series of steps:

1. Confirm the SAML trace tracking tool is open/capturing.
2. Navigate through your Account Provisioning flow.
3. Encounter the error you are troubleshooting.
4. View the tool and parse for a recent SAML event.
   
5. Select the SAML event you want to investigate. Often this will be a POST pointing at an authentication endpoint. In saml-tracer you will observe SAML on the right hand side as well.
6. Various elements can be observed for the SAML event. Saml-tracer breaks out the different sections of the events into the following sections: HTTP, Parameters, SAML and Summary
   
7. Under the HTTP section, confirm the POST is looking at the correct location.
8. Under the SAML section the following may be relevant:
   
   • The X509Certificate section. Confirm this contains the correct X509/Key.
     
   • NameID Format. Confirm the correct identity property and value are supplied in this section.
     
   • Under AttributeStatement there will be the attributes sent for Account Provisioning. Confirm all required attributes are included, that they aren't derived from a schema, and that the names are exactly as listed in this article.
     
9. Under the Summary section you can observe information from the other panels in a convenient GUI. It can be worthwhile to investigate the SAML section prior to the Summary just in case there are notable differences.

Through the process of analyzing a SAML trace the issue often becomes apparent. Whether that is a missing SAML assertion all together, an out-dated X509 certificate or the attribute statement includes the usage of an XML Schema. Parsing the actual SAML assertion itself to confirm each portion is being communicated as intended is worthwhile.

If you observe a difference between what is configured in your IdP and what is sent in the SAML assertion. This may indicate there are server caching issues and a restart on the side of your IdP is required to POST the intended information during the Account Provisioning process.

Things To Look For

While troubleshooting a SAML trace, there are a few items worth reviewing to rule them out. These are as follows:

• If Account Provisioning, are you sending an Attribute Statement as part of your SAML assertion?
  • If you are sending an Attribute Statement, are the required Attribute Names spelled correctly? Attribute Name is a case-sensitive property and must be sent exactly as listed here.
• SkillSync can't process an XML schema if it is used to hold an Attribute value. Confirm all Attribute values are being sent without the use of an XML schema.
• The Identity Property must match the Attribute Value, if there is a match.
  • As an example, if Identity Property is set to Email Address, then Identity Property or Name ID (as it may be labelled in your SSO provider) must have the exact same value as the Email Address Attribute included in your Attribute Statement.
• Is the Route/Target the POST is being directed to the correct address?
• When a SAML assertion is made, some special characters get transformed into weird combinations of letters and other special characters, like & will, may become 'W*j9' as an example.
  
  • If you notice odd characters or symbols, this may indicate there is an encoding issue.
  • At times the best fix is to confirm the encoding of the information going into the SAML assertion, and if possible, minimize the use of special characters.