SAML Tracing


SAML provides a useful and secure framework for sharing an identity across multiple applications within an organization and across multiple networks.  SAML refers to the XML variant language used to encode the identity of the subject and the necessary validation mechanisms, all into a single document.  While this information is always available to the user, an implementer may need to dig deeper into this XML document to understand the behavior of the application or Identity Provider. There are a variety of tools available at your disposal, but here are our recommendations on how capture the relevant information.


Getting started

Browser

The most robust extensions, add-ons, and tools are compatible with Google Chrome and Mozilla Firefox, and we recommend sticking to these platforms while troubleshooting SAML authentication. 

Google Chrome

  • SAML Chrome Panel - This Google Chrome extension uses the built-in Developer Tools, by adding its own tab/panel.  With your focus on this panel while performing a SAML authentication, this tool will capture both the SAML Request (if performing SP-Initiated SSO login) and the SAML Response. 
  • SAML Message Decoder - This Chrome extension runs in the background at all times and allows you to quickly investigate a SAML-related problem by clicking the extension's button in the toolbar.  You will be able to see all recent SAML Requests and SAML Responses. 

Firefox

  • SAML Tracer - For troubleshooting SAML on Firefox, look no further.  Once installed, use the SAML Tracer toolbar button to open the tracing interface.  Once it's open, you'll see any SAML-related calls highlighted with a "SAML" label.  You will be able to review the headers, parameters, and the related XML document that was exchanged. 


How to Trace SAML

Google Chrome - Using SAML Chrome Panel

Once you have the extension installed, you'll need to open Chrome Developer Tools to begin using it.  The quickest way to open this panel is with either of these keyboard shortcuts:

  • Ctrl + Shift + J (on Windows)
  • Ctrl + Option + J (on Mac)

You should receive a window like this:


Initiate a login via SAML, as you normally would.  If you're logging into the Aqua console, either click the SSO button (SP-initiated SSO) on the login page, or initiate the login from your identity provider dashboard (IdP-Initiated SSO).  For SP-Initiated SSO, you will see two entries in your SAML Chrome Panel - the SAML Response and the SAML Request.  For IdP-Initiated SSO, you will just see one, the SAML Response.



In the above image, you can see the SAML Request XML produced by Aqua.  The information was relayed to the Identity Provider, so it can then know how to prompt you, and how it should produce a SAML Response.  The second entry in the SAML Chrome Panel is the SAML Response.



The XML in the image above contains the security assertion that Aqua (the Service Provider, or "SP") will use to identify the user, and also validate that this information was produced by the trusted Identity Provider.  


An Aqua Support representative may ask you to copy and paste either the SAML Request or SAML Response into a support ticket.


Firefox - SAML Tracer

Tracing on Firefox with SAML Tracer is quite simple.  Once installed, activate the tracing panel by clicking the "SAML" button in the toolbar. (You will find it in older versions of Firefox under the "Tools" menu bar).  Once this panel is open, you're ready to begin tracing.  




Initiate a login via SAML, as you normally would.  If you're logging into the Aqua console, either click the SSO button (SP-initiated SSO) on the login page, or initiate the login from your identity provider dashboard (IdP-Initiated SSO).  For SP-Initiated SSO, you will see two highlighted entries in the SAML tracer - the SAML Response and the SAML Request.  For IdP-Initiated SSO, you will just see one, the SAML Response.



An Aqua Support representative may ask you to copy and paste either the SAML Request or the SAML Response into a support ticket.