A SAML tracer is a tool that captures and decodes Secure Assertion Markup Language (SAML) requests and responses exchanged between a Service Provider (SP) and Okta, acting as the Identity Provider (IdP). Reviewing the decoded payload enables administrators to identify common configuration errors, such as Assertion Consumer Service (ACS) URL mismatches, audience mismatches, certificate errors, and attribute mapping issues. This article covers installing SAML Tracer, capturing SP- and IdP-initiated flows, and reading the trace to diagnose issues.

• Okta Identity Engine (OIE)
• Okta Classic Engine
• Secure Assertion Markup Language (SAML)
• SAML Tracer
• Identity Provider (IdP)
• Service Provider (SP)

How is SAML Tracer Installed and Configured?

The video and steps below cover installing SAML Tracer and opening the trace window in the browser. Similar browser extension tools are available (for example, SAML DevTools or SAML Chrome Panel for Chrome); the examples below use SAML Tracer. Select the tool that best fits organizational guidelines.

1. Install SAML Tracer using the appropriate browser link:
   • Firefox: SAML Tracer for Firefox
   • Google Chrome: SAML Tracer for Google Chrome
2. After installation, open SAML Tracer from the browser menu bar by choosing Tools > SAML Tracer.
3. Similar tools, such as SAML DevTools and SAML Chrome Panel, are available for other browsers. Examples in this article will utilize SAML Tracer.

How is an SP-Initiated Flow Captured?

The following steps capture a SAML request and response for an SP-initiated flow, where the login begins at the application.

1. Open SAML Tracer and navigate to the application. If the user is not already signed in, the application redirects the user to the Okta sign-in page.
2. Review the SAML Tracer window to observe the SAMLRequest sent from the application to Okta.
3. Okta returns a SAML Response, which appears in the SAML Tracer window.

How is an IdP-Initiated Flow Captured?

The following steps capture a SAML response for an IdP-initiated flow in which the login begins at Okta.

1. Assign the SAML application to a user.
2. Navigate to that user's End-User Dashboard and select the application icon.
3. The application opens in a new browser window and, if successful, Okta sends a SAML Response.

NOTE: The IdP-initiated flow can also be started by selecting the App Embed Link in a browser. Navigate to SAML App > General > App Embed Link.

How is SAML Tracer Enabled in a Private Browser?

The following steps enable SAML Tracer in an Incognito window in Google Chrome. Testing in a private browser prevents cached cookies or prior sessions from obscuring issues.

1. Select the Extensions puzzle icon in the top-right corner of the Google Chrome browser.
2. Select the Manage Extensions gear icon.
3. Locate SAML-tracer.
4. Select Details.
5. Toggle on Allow in Incognito.

How is the SAML Trace Read to Identify Errors?

After capturing a flow, select the relevant entry in the SAML Tracer window (for example, a POST /sso/saml entry tagged SAML) and open the decoded XML payload. The table below describes the key fields to review.

The following four errors are the most common issues identifiable in the decoded payload.

ACS URL Mismatch

Locate the AssertionConsumerServiceURL field in the SAMLRequest or the Destination field in the SAML Response. If the value does not exactly match the ACS URL configured in the Okta application settings, Okta rejects the response or the SP rejects the assertion. Symptoms include redirect loops and SP error pages.

<samlp:AuthnRequest
  AssertionConsumerServiceURL="https://<sp-domain.com>/saml/acs"
  ...>

Audience Mismatch

Locate the AudienceRestriction element in the decoded SAML Response. The value must exactly match the SP Entity ID configured in the Okta application settings. A mismatch causes the SP to reject the assertion.

<saml2:AudienceRestriction>
<saml2:Audience>https://<sp-entity-id></saml2:Audience>
</saml2:AudienceRestriction>

Certificate and Signature Errors

Locate the Signature and X509Certificate elements in the decoded SAML Response. Errors in this area typically result from an incorrectly copied certificate, extra whitespace, or a formatting issue in the certificate value. Verify that the certificate in the Okta application settings matches the value present in the assertion.

<ds:Signature>
<ds:X509Certificate>MIICmDCCAYA...</ds:X509Certificate>
</ds:Signature>

Attribute Mapping Errors

Locate the AttributeStatement element in the decoded SAML Response. Verify that the attribute names and values sent by Okta match the SP's expectations. Missing attributes or mismatched names may cause provisioning and role mapping to fail.

<saml2:AttributeStatement>
<saml2:Attribute Name="email">
<saml2:AttributeValue>user@<domain.com></saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="firstName">
<saml2:AttributeValue><FirstName></saml2:AttributeValue>
</saml2:Attribute>
<saml2:Attribute Name="groups">
<saml2:AttributeValue><GroupName></saml2:AttributeValue>
</saml2:Attribute>
</saml2:AttributeStatement>

How Are SAML Tracer Findings Correlated with Okta System Logs?

After reviewing the trace, confirm the result in the Okta System Log to confirm that Okta successfully generated the SAML Response. The following steps describe how to access and search the System Log.

1. Sign in to the Okta Admin Console.
2. Go to Reports > System Log.
3. Search for the following event types to locate the relevant authentication events:
   • app.auth.sso
   • user.authentication.sso

Related References

• Sanitizing HTTP Traces