Security Assertion Markup Language (SAML) Troubleshooting Tools
Put some of the tools we use in your toolbox.
In the Ping Support team, we often see various support requests come through that seek assistance in sorting out some issue with service providers complaining of being unable to use the SAML assertions in some form. These are commonly issues with what we call "roll your own" solutions, where the developer/provider isn't necessarily conforming to SAML specifications.
Rather than pay for an application like PingFederate, they have utilized a PHP, .Net, or PERL library, and haven't quite gotten the code exactly right. If that's what works for them, that's great, but sometimes it can be quite a headache when you're trying to troubleshoot a problem with an integration that you're trying to set up with one of your partners that has gone the way of the "roll your own" solution.
There are a few tools out there that can help solve these problems. Ultimately, you can do most of these from the command line if you have OpenSSL, access to logs, etc. But why reinvent the wheel when there are lots of good wheels lying around that can get you a long ways toward resolution without reverting to the command line.
I can hear it now - the wails of sysadmins everywhere simply flabbergasted that I would propose using some tool that doesn't involve 17 sed commands, 4 awks, 22 different pipes and a temp file the size of Nebraska. Not everyone is built that way!
Before we get started, let's get a caveat out of the way: A number of the tools described in the decoding and verification sections are online tools. In theory, they could attempt to capture and reuse current assertions via "replay." Obviously, that could be a bad thing, were any of them interested in doing so. As such, it's probably good to make sure that the assertions you're posting into them are: 1) Not for your production connections, and 2) The assertions have "timed out" and are no longer usable.
I'd like to point out that I don't believe any of these sites are doing that, but it's always prudent to understand risks.
Get Your SAML Data
First, you need to be able to get every possible drop of SAML information out of your browser. Nearly everything that you're going to do with SAML is going to be via your browser unless you're doing some fancy backchannel calls, but even then, the guts of your authentication requests and assertions are going through your browser, either as form POSTs or cookies.
Sure, a number of these things can be gleaned out of log files on either end, but in many instances, there may be processing that's already occurred. If you pull the data straight from the browser, you have what's being carried between the IdP and SP by the browser, beyond a shadow of a doubt.
There are a few tools for this. Some are browser plugins and some are actual proxies. The proxies generally require administrator access to the machine that they will be installed on, and so may not work for you in your environment, depending on your access to your machine. They are, however, capable of capturing from all browsers - IE, Chrome, Firefox, Safari, etc.
The plugins, have some drawbacks, too. For example: they may not capture everything, like issues surrounding 413 errors (request entity too large). For most users, however, they could suffice as long as you're able to use Firefox or IE. To be sure, you can use the developer tools in the browser, but those aren't quite as easy to configure to capture all traffic. Usage of these tools is outside the scope of this blog article - but there's plenty of documentation out there!
We've recently published a knowledgebase article, HTTP Tracing on the usage of these tools, so have a look at that if you're unfamiliar with the tool you're using.
The goal here is to get the SAML request or the response. That object, when using the POST or REDIRECT binding will look something like this:
Decode the SAML
Nice bit of gobbledy-gook, eh? So now what the heck do you do with that? Well, we'll want to decode it, to see what it actually contains. Sometimes they are Base64 encoded, sometimes they are Base64 encoded, deflated, and URL encoded. Who wants to figure out what is being used? So rather than do that, just point your browser to Feide RnD SAML 2.0 Debugger. It has samples that you can use as well, and once you've decoded the message, you can turn on PrettyPrint to do some XML Syntax highlighting. Good stuff. You'll end up with something like this:
<?xml version="1.0" encoding="UTF-8"?>
HTTP-POST" ProviderName="google.com" AssertionConsumerServiceURL="https://www.google.com/a/solweb.no/acs" IsPassive="true">
<samlp:NameIDPolicy AllowCreate="true" Format="urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified" />
Verify you have Valid XML
Maybe we should check that you're getting valid XML--after all, SAML is XML, right? The fine folks that run W3Schools have a nice DOM validation tool. You just paste that decoded sample you got from the debugger into the tool, click verify XML, and it lets you know the deal in a little popup ("no errors found") or it will describe the error and its location.
Verify Certificates and Signatures
So now you have the SAML decoded, and you've verified that you have valid XML. Super. But what if you're getting some complaint about certificates? Well, the guys over at XMLSec have you covered with the XML Digital Signature Verifier. Just copy the plain text out of the SAML Debugger, and paste it into the verifier. There are some caveats to the online tool - the X509 cert and the public key have to be included in the SAML message that you're going to check. Or, it has to use a common public Root CA (like Verisign), or it has to use one of the Merlin certs used for interoperability testing.
What if you don't have the certs in the SAML message? Well, then it gets harder - and quite frankly is outside the scope of this document. However, you can find all those answers at XMLSec. The online tool is really just a CGI built around the libraries available from there. Read more starting on the XMLSec Download Page.
Andy King is a Solutions Support Engineer at Ping Identity.
Find out more about SAML