Troubleshooting SAML security

Troubleshooting a SAML (https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) based SSO application can be tricky because of the complexity of the underlying framework over which the development team will have very less control and transparency. There is also the added complexity of not knowing if the problem occurred at the Service Provider or the Identity Provider. These two teams will usually be separate and communication will be a challenge.

Recently while working on a Spring Security SAML project, there was a need to trouble shoot the application to find the root cause.

Here are three simple tips to make troubleshooting simpler for Spring applications that use SAML for security.

Enable SAML logging

SAML in Spring uses SLF4J for logging. Enable logging. More details here - http://docs.spring.io/spring-security-saml/docs/1.0.x-SNAPSHOT/reference/htmlsingle/#logging

Install a SAML plugin in your browser. 

Install a SAML plugin to the browser and debug the SAML requests. While there are several good plugins for Chrome and Firefox browsers, I found (subjectively) the SAML Tracer (https://addons.mozilla.org/en-US/firefox/addon/saml-tracer/) Firefox extension to be very simple and intuitive.

Firefox Extension - SAML Tracer

The SAML Chrome Panel (https://chrome.google.com/webstore/detail/saml-chrome-panel/paijfdbeoenhembfhkhllainmocckace) for Google Chrome browser is more advanced and can be used if you need more visibility.

Ensure that the error.jsp is configured correctly and prints the stacktrace

This is an usually underrated step, but it will be the easiest and best way to start debugging.

Every Authentication Manager in the Spring Security app shall have a Failure Handler. Ensure that a SimpleUrlAuthenticationFailureHandler (http://docs.spring.io/spring-security/site/docs/3.2.9.RELEASE/apidocs/org/springframework/security/web/authentication/SimpleUrlAuthenticationFailureHandler.html) is configured that forwards to a JSP page. 

This JSP page should be capable of catching and printing Exception stack traces.

Refer this code here for a good example of how this JSP should look like. https://github.com/spring-projects/spring-security-saml/blob/master/sample/src/main/webapp/error.jsp

Authentication log

Maintaining an Authentication log that has key steps can be very helpful in trouble shooting SAML events. More details here - http://docs.spring.io/spring-security-saml/docs/1.0.x-SNAPSHOT/reference/htmlsingle/#configuration-authentication-log