Table of Contents
Performing a SAML Trace using SAML-Tracer Browser Add-on
Situation
Integrating a new service provider (SP) with a SAML identity provider (IdP) can be frustrating at times. Depending on the SP and IdP, the error handling can be as helpful as asking a mime for a restaurant recommendation.
Performing a SAML trace will reveal the entire flow of the SAML exchange captured from HTTP traffic in your browser session. This article will attempt to equip you to perform a trace and interpret the results.
Background
SAMLV2 routes all messaging through the end user’s browser agent. This is a useful property. It is fairly straightforward to instrument a browser with software to intercept and parse this traffic.
NOTE - because you are effectively installing software to perform a web browser man-in-the-middle attack, choose tools from reputable sources.
Diagnostic tools such as Fiddler are powerful ways to look at this traffic, but are often overkill for solving most SAML integration problems. There are also several different web browser add-ons to choose from. Cirrus Identity recommends the SAML-tracer browser add-on (https://github.com/SimpleSAMLphp/SAML-tracer) developed by members of the SimpleSAMLphp project. The add-on is available for the following browsers:
1. Google Chrome or MS Edge – https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en-US
2. Firefox – https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/
Performing a SAML Trace using SAML-Tracer Browser Add-on
In this example, we will trace Connie Contrail’s authentication to Athena Institute Demo, Cirrus’ test Service Provider. We are using the SAML-tracer browser add-on mentioned above.
1. Navigate to the Service Provider’s sitehttps://athena-institute.demo.cirrusidentity.com/gateway.php?authenticate
SAML-tracer will automatically begin to log HTTP requests and responses. See example below.
Connie authenticates to Cirrus’ test SP successfully and is presented with the screen below.
SAML requests and responses are tagged with SAML as in the example below.
5. Click on a SAML tag to analyze it. You will also need to select the SAML tab from the window below.
The above SAML is an AuthnRequest. Common things to check for correctness:
Is the Destination going to the expected identity provider endpoint?
Does the AssertionConsumerServiceURL reflect the expected service provider?
Is the NameIDPolicy transient, persistent, or a format that might not be supported by the IdP?
6. The SAML below shows the attribute/value pairs that are released to the SP. This is helpful to confirm the assertion data is accurate and complete.
NOTE - If the IdP is encrypting the response, the contents of the assertion will not be readable. It may be necessary to temporarily disable encryption while tracing an issue. Remember to re-enable when done.
Exporting a SAML Trace File
When troubleshooting, Cirrus may ask to see a SAML Trace file. Here is how you export it.
In the SAML-tracer window, select the ‘Export’ function and the ‘Mask values’ option to help prevent the sharing of sensitive data. Then, Export the file. It will be in a JSON format. You can attach it to an email and send it to support@cirrusidentity.com.
Key Takeaways
- Performing a SAML trace is helpful for troubleshooting. It enables you to view the complete exchange of SAML transactions and hone in on the source of the problem. You are also able to verify that the data in the SAML exchange is accurate and complete.
- There are free tools available to perform a SAML trace. You should only use tools from a reputable source and use them responsibly.
- You can export a SAML trace file.
About This Series
“Cirrus Assertions” is a series of articles about common challenges with implementing access management in Higher Education. The articles attempt to provide practical advice based on the many collective years of Cirrus Staff experience supporting IT services for the Higher Education community.
The advice provided comes from observation and field experience working on diverse identity and access management deployments. The guidance may not be appropriate for all organizations or use cases.