SAML Trace


What is a SAML Trace?

Security Assertion Markup Language (SAML) is an XML based Identity federation language standard that among other features enables Single Sign On (SSO).


When a SAML 2.0 connector is created in a customer's Identity Provider (IdP) service and used to log in with a federated account, a complex workflow occurs in the background which is mostly invisible to the user.


Part of this workflow is the passing and assertion of four key attributes:

  • NameID
  • Email
  • FirstName
  • LastName


When these attributes are correctly passed, they 'assert' the identity of the user attempting to log in and create a federated trust between an Identity Provider (IdP - Customer) and a Service Provider (SP - Essential Cloud) and SSO succeeds.


When there is a problem, it is useful for Essential Cloud customers and customer support staff to be able to trace these SAML assertions occuring between the IdP and SP.


A SAML Trace shows important values such as the Assertion Consumer Service URL, Issuer URL, and four key SAML 2.0 attributes.


What do I need to perform a SAML Trace?

SAML tracers are available in the form of Internet Browser Add-ons/Extensions are free to download and require no special permissions or other software.


Two of the most popular Add-ons are:


Firefox browser SAML Tracer Add On:

https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/


Google Chrome browser SAML Chrome Panel Browser Extension:

https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace?hl=en


How do I perform a SAML Trace?

It is recommended to install and use the Tracer on the client system with the user account that is experiencing the SSO issue. Note the links and steps provided here were correct at time of publishing.


Otherwise for general SSO testing, the Tracer can be installed and run from any client system and any Federated user account on the same network.


We are using the Firefox SAML Tracer Add-On, for example here:


  1. Using Firefox browser download and install the Firefox browser SAML Tracer Add On via the link provided earlier.

  2. When completed, note the new orange SAML tracer Add-on menu element in the Firefox menu bar

  3. Click the SAML tracer Add-on menu element and a new two-part browser. Trace window appears as shown. The upper half of the Trace Window shows the rolling HTTP POST, GET, and OPTIONS methods occurring in real time. The lower half of the Trace Window shows expanded details of each method when it is clicked.
  4. Click the Trace Window and the Main Window so that both are viewed simultaneously.  Then navigate to your Essential Cloud login page and click Sign In with Company Account


Sharing the output


  • This output in it's entirety with no modification should be provided along with other details of the issue to Essential Support when reporting a suspected SSO issue.
  • The case syntax of SAML assertion field names, for example: NameID, Email, FirstName, and LastName are crucial to SSO succeeding and can be quickly identified and modified in a customer's IdP configuration when required.