Discovery helps your Service Provider determine which Identity Provider should be used for authentication of the current user. It is automatically initialized during calls to single sign-on endpoint at scheme://server:port/contextPath/saml/login. SAML Extension supports multiple modes of discovery including the Identity Provider Discovery Service Protocol and Profile.

IDP discovery modes can always be skipped during SSO initialization by specifying HTTP request parameter idp with the entityId of the required IDP, e.g. scheme://server:port/contextPath/saml/login?idp=mySelectedIDP.

The URL where local SP expects discovery response can be included in the SP metadata as one of the extensions. The feature can be enabled by setting property includeDiscoveryExtension to true on bean MetadataGenerator inside MetadataGeneratorFilter, e.g.:

<bean id="metadataGeneratorFilter" class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
	<constructor-arg>
		<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
			<property name="includeDiscoveryExtension" value="true"/>
		</bean>
	</constructor-arg>
</bean>

Spring SAML Extension supports both SP-initialized and IDP-initialized single sign-on.

<bean id="samlEntryPoint" class="org.springframework.security.saml.SAMLEntryPoint">
	<property name="defaultProfileOptions">
		<bean class="org.springframework.security.saml.websso.WebSSOProfileOptions">
			<property name="binding" value="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"/>
			<property name="includeScoping" value="false"/>
		</bean>
	</property>
</bean>

Spring SAML Extension supports both Local Logout and Single Logout mechanisms.

<security:http>
	<security:logout logout-url="/j_logout" logout-success-url="/logout.jsp"/>
</security:http>

Successful authentication using SAML token results in creation of an Authentication object by the SAMLAuthenticationProvider. By default instance of org.springframework.security.providers.ExpiringUsernameAuthenticationToken is created. Content of the resulting object can be customized by setting properties of the samlAuthenticationProvider bean in the securityContext.xml. An instance of org.springframework.security.saml.userdetails.SAMLUserDetailsService can be provided to supply application-specific information about the authenticated user.

The Authentication object will by default include string version of the NameID included in the SAML Assertion as itsprincipal. Property forcePrincipalAsString can be used to change this to include the raw NameID element.

The Authentication object is available in pages secured with Spring Security using SecurityContextHolder.getContext().getAuthentication() and is populated with the following values:

Custom implementation of the SAMLUserDetailsService can be provided as property userDetails of the SAMLAuthenticationProvider. Implementation can perform operation such as parsing of attributes present in the SAML Assertion, e.g.:

package fi.schafer.test.saml;

import org.opensaml.saml2.core.Attribute;
import org.opensaml.xml.XMLObject;
import org.springframework.security.core.userdetails.UsernameNotFoundException;
import org.springframework.security.saml.SAMLCredential;
import org.springframework.security.saml.userdetails.SAMLUserDetailsService;

public class TestUserDetails implements SAMLUserDetailsService {
	@Override
	public Object loadUserBySAML(SAMLCredential cred) throws UsernameNotFoundException {
		return cred.getAttributeAsString("accountID");
	}
}

Population of the authentication object can be further customized by overriding of the getUserDetails, getPrincipal, getEntitlements and getExpirationDate methods in the SAMLAuthenticationProvider.

Assertion used to authenticate user is stored in the SAMLCredential object under property authenticationAssertion. By default the original content (DOM) of the assertion is discarded and system only keeps an unmarshalled version which might slightly differ from the original, e.g. in white-spaces. In order to instruct Spring SAML to keep the assertion in the original form (keep its DOM) set property releaseDOM to false on bean WebSSOProfileConsumerImpl.

Assertion can be serialized to String using the following call:

XMLHelper.nodeToString(SAMLUtil.marshallMessage(credential.getAuthenticationAssertion()))

Key events such as single sign-on and single logout initialization, success or failure can be logged for creation of an audit trail. A custom logger can be created by implementing interface org.springframework.security.saml.log.SAMLLogger and including its bean in the securityContext.xml, e.g.:

<bean id="samlLogger" class="org.springframework.security.saml.log.SAMLDefaultLogger"/>

Two basic implementations are provided by default:

The logger is only called for messages which can be correctly received and parsed. For errors which occur before correct parsing see Section 6.5, “Error handling”.