The documentation for ServiceNow’s SAML setup is the best that it has ever been. More and more customers are able to set up SAML correctly without having to engage outside help. That being said, what happens when you set up SAML and things just aren’t working out correctly?

When debugging SAML issues in ServiceNow, there are two things I recommend:
1. Use the Debug Log statements in ServiceNow
2. Use a network tracer such as those built into Chrome & Firefox, or Fiddler for Windows users.

This article covers the first recommended action, following the Debug Log statements inside ServiceNow.

Enabling and Viewing Debug Logging

This will ensure that the SAML debug statements will be logged to your instance’s System Log.

Now, to browse your System Log, simply go to “System Logs -> All”. I like to sort my logs on creation date where the create time on the filter for the log is after the last statement before I attempt to do a SAML login.

Typical Log Statements

The following is typical log output for a successful SAML authentication:

This line just shows the SAML processing URL (the one that the IdP will send the Response to when it is done) and also the calculated base URL of the instance for use later on in the script.

Now, in the case of this example, we were using deep linking. This means that we clicked on a non-home page link an after authentication we want to be redirected to that specific page. In order for SAML to trigger on that, the url needs to use “nav_to.do”. This is what link we were using in this example:

https://myinstance.service-now.com/nav_to.do?uri=incident.do?sys_id=46e482d9a9fe198101d3e3f3e2a14459

In this next log statement, we analyze the destination URL to see if there is deep linking. The request URI is the page that is being accessed, and the “Query String” statement is the parameters on that URL.

Based on the URI an Query String, the script will attempt to use Deep Linking since it found query string parameters.

If we were not deep linking, then most of those statements above would be empty, or show a “null” value.

Next SAML will try to generate a Relay State parameter. This is sent to the IdP. Once authentication is complete on the Identity Provider’s side, it will redirect back to ServiceNow and it will post this Relay State with the SAML Response. This lets ServiceNow know where to redirect the browser once the login is completed.

The SAML plugin will URL encode the Relay State value since this is going on the URL that we send to the IdP. We don’t want any special URL characters to interfere with the base URL redirection that we are doing.

If there is no relay state, then a default relay state is generated. Out of the box, this relay state will be the main page of your instance.

Once the Relay State is generated, the system will generate an AuthnRequest XML document. This document will then be DEFLATED, base64 encoded, and URL Encoded and added to the URL as a “SAMLRequest” parameter. The log will show both the XML document for the request, and the full URL with SAMLRequest and RelayState that we will use for redirection to the IdP.

Here, the user’s browser is redirected to the IdP for authentication. Logging is now the responsibility of the IdP. We will not receive any more log messages in the SAML process until the IdP processed the authentication and redirects the user back to ServiceNow with the SAML response document and relay state.

Logging resumes as we get the response back from the IdP. Before we act on the response, we first do a number of validation and security checks to ensure we can trust this SAML response.

After the SAML response is validated and trusted by the system, we will process it and attempt to login using the nameId token passed back to use from the IdP.

The log will display the NameID token received from the IdP. We will match this up with a real user in our system and establish a valid ServiceNow session.

At this point, we redirect the user’s browser to the page indicated by the RelayState that was passed back to us from the IdP. This should be the same relay state that we sent to the IdP to hold on for us.

The user is then authenticated and redirected to the relay state’s URL.