In order to include the library and all its dependencies add the following dependency to your pom.xml file:

<dependency>
	<groupId>org.springframework.security.extensions</groupId>
	<artifactId>spring-security-saml2-core</artifactId>
	<version>${version}</version>
</dependency>

The current version of SAML Extension has been tested to work with Spring 3.1.2, Spring Security 3.1.2 and OpenSAML 2.6.1. Later versions of these libraries are likely to be compatible without need for modifications.

Configuration of the SAML library requires beans definitions included in the sample/src/main/webapp/WEB-INF/securityContext.xml configuration file. Include copy of the file in your own Spring application, either directly or with an inclusion. Configuration steps in the following chapters will be customizing beans included in the default context.

Beans of the SAML library are using auto-wiring and annotation-based configuration by default. Make sure that your Spring configuration contains e.g. the following settings in order to enable support for these features:

<context:annotation-config/>
<context:component-scan base-package="org.springframework.security.saml"/>

Spring SAML will include configuration classes for Spring Java-based configuration in future versions.

For an example of securityContext.xml translated into Java configuration in a Spring Boot application see project by Vincenzo De Notaris at https://github.com/vdenotaris/spring-boot-security-saml-sample.

Filters of the SAML module need to be enabled as part of the Spring Security settings. In case SAML authentication should be the default authentication mechanism of the application set bean samlEntryPoint as the default entry point. Make sure that filter samlFilter is included as one of the custom filters. In case SP metadata should be generated automatically during first request to the application include also filter metadataGeneratorFilter. The configuration directive may for example look as follows:

<security:http entry-point-ref="samlEntryPoint">
	<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>
	<security:custom-filter after="BASIC_AUTH_FILTER" ref="samlFilter"/>
</security:http>

Critical errors raised during processing of SAML messages are generally propagated as ServletExceptions to the Java container. In order to configure a custom error handling update your web.xml and provide a general handler for ServletExceptions:

<error-page>
	<exception-type>javax.servlet.ServletException</exception-type>
	<location>/error.jsp</location>
</error-page>

ServletException contains original reason for the failure as a cause. It is recommended that content of the exceptions is not displayed to end users, both for security and user experience reasons.

Errors produced during processing of the SAML AuthenticationResponse can be handled by plugging a custom implementation of the org.springframework.security.web.authentication.AuthenticationFailureHandler interface to the samlWebSSOProcessingFilter bean.

SAML Extension uses SLF4J framework for logging. The same applies to the underlaying OpenSAML library. The sample application by default uses log4j version 1.2 binding for SLF4J, configured with the following dependency:

<dependency>
	<groupId>org.slf4j</groupId>
	<artifactId>slf4j-log4j12</artifactId>
	<version>1.6.3</version>
	<scope>compile</scope>
</dependency>

In case you are using another logging library, make sure to change the dependency accordingly.

You can enable debug logging by modifying file sample/src/main/resources/log4j.properties and adding:

log4j.logger.org.springframework.security.saml=DEBUG
log4j.logger.org.opensaml=DEBUG
log4j.logger.PROTOCOL_MESSAGE=DEBUG

For details about using other logging frameworks please consult the SLF4J manual.