Spring Security SAML 2.0 library comprises three modules:

Configuration of library is done using Spring context XML. An example of configuration can be found undersaml2-sample/src/main/resources/security/securityContext.xml. Setting up of the library typically involves these steps:

Additional steps such as configuration of authentication logging, customization of SAML 2.0 bindings, configuration of artifact resolution or configuration of time skews might be needed.

SAML module can be directly embedded into new of existing Spring applications. In this case application itself includes the SAML library in WEB-INF/lib directory of the war archive and processes all SAML interactions. The other option of using the SAML library is deploying it as a stand-alone module which transfers information about the authenticated user to the target application using a custom mechanism. This chapter only discusses the first option.

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

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

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

SAML metadata is an XML document which contains information necessary for interaction with SAML-enabled identity or service providers. Document contains e.g. URLs of endpoints, information about supported bindings, identifiers and public keys. Typically one metadata document will be generated for your own service provider and sent to all identity providers you want to enable single sign-on with. Similarly, each identity provider will make it's own metadata available for you to import into your service provider application.

Each metadata document can contain definition for one or many identity or service providers and optionally can be digitally signed. Metadata can be customized either by direct modifications to the XML document, or using extended metadata. Extended metadata is added directly to the Spring configuration file and can contain additional options which are unavailable in the basic metadata document.

<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>

<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
	<property name="bindingsSSO"><list><value>artifact</value></list></property>
	<property name="bindingsSLO"><list><value>redirect</value></list></property>
	<property name="bindingsHoKSSO"><list/></property>
</bean>

https://www.server.com:8080/context/saml/metadata

https://www.server.com:8080/context/saml/login/alias/defaultAlias

<bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
	<constructor-arg>
		<bean class="org.opensaml.saml2.metadata.provider.FilesystemMetadataProvider">
			<constructor-arg>
				<value type="java.io.File">classpath:security/idp.xml</value>
			</constructor-arg>
			<property name="parserPool" ref="parserPool"/>
		</bean>
	</constructor-arg>
	<constructor-arg>
		<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
	</constructor-arg>
</bean>

<bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
	<constructor-arg>
		<bean class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider">
			<constructor-arg>
				<value type="java.lang.String">http://idp.ssocircle.com/idp-meta.xml</value>
			</constructor-arg>
			<constructor-arg>
				<!-- Timeout for metadata loading in ms -->
				<value type="int">5000</value>
			</constructor-arg>
			<property name="parserPool" ref="parserPool"/>
		</bean>
	</constructor-arg>
	<constructor-arg>
		<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
	</constructor-arg>
</bean>

<bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
	<constructor-arg>
		metadata provider bean
	</constructor-arg>
	<constructor-arg>
		<!-- Default extended metadata for entities not specified in the map -->
		<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
	</constructor-arg>
	<constructor-arg>
		<!-- Extended metadata for specific IDPs -->
		<map>
			<entry key="http://idp.ssocircle.com">
				<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
			</entry>
		</map>
	</constructor-arg>
</bean>

TODO

SAML exchanges involve usage of cryptography for signing and encryption of data. All interaction with cryptographic keys is done through interface org.springframework.security.saml.key.KeyManager. Default implementation relies on a single JKS key store which contains all private and public keys. KeyManager must contain at least one private key which should be marked as default by using the alias of the private key as part of the KeyManager constructor.

Make sure that your configuration of SAML module contains bean keyManager with your custom key store and passwords.

<bean id="keyManager" class="org.springframework.security.saml.key.JKSKeyManager">
	<constructor-arg value="classpath:security/samlKeystore.jks"/>
	<constructor-arg type="java.lang.String" value="nalle123"/>
	<constructor-arg>
		<map>
			<entry key="apollo" value="nalle123"/>
		</map>
	</constructor-arg>
	<constructor-arg type="java.lang.String" value="apollo"/>
</bean>

keytool -genkeypair -alias some-alias -keypass changeit -keystore samlKeystore.jks

keytool -importkeystore -srckeystore key.p12 -srcstoretype PKCS12 -srcstorepass password \
-alias some-alias -destkeystore samlKeystore.jks -destalias some-alias -destkeypass changeit

keytool -list -keystore key.p12 -storetype pkcs12

keytool -importcert -alias some-alias -file key.cer -keystore samlKeystore.jks

java -jar sslextractor-0.9.jar www.google.com 443

Exchanges of messages between identity providers and service providers with SAML protocol involves usage of digital signatures. Signatures are typically constructed using means of asymetric cryptography and public key infrastructure with public and private keys signed by trusted certification authorities. Signatures are either applied directly to parts of XML representation of SAML messages using XML Signature or are part of the transport layer used to deliver the message like SSL/TLS.

Verification of signatures is executed in two phases. Signature is first checked for validity by comparing digital hash included as part of the signature with value calculated from the content. Subsequently it is verified whether party who created the signature is trusted by the recipient. Module provides two mechanisms for defining which signatures should be accepted - metadata interoperability mode and PKIX mode.

Security profiles are defined in Extended Metadata of your local SP. Profile can be defined separately for XML Signatures using property securityProfile and for SSL/TLS Signatures using propertysslSecurityProfile. Value of both properties can be either metaiop or pkix. For details about using Extended Metadata see Section 4.3, “Metadata configuration”, for reference of allowed values see Section A.1, “Extended metadata”.

SP initialized SSO process can be started in two ways:

After identification of IDP to use (for details see Section 4.8, “IDP selection”) SAML Extension creates an AuthnRequest SAML message and sends it to the selected IDP. Both construction of the AuthnRequest and binding used to send it can be customized using WebSSOProfileOptions object. SAMLEntryPoint determines WebSSOProfileOptions configuration to use by calling method getProfileOptions. Default implementation returns value specified in property defaultOptions. Method can be overriden to provide custom logic for SSO initialization.

The following SSO parameters can be customized using the WebSSOProfileOptions object:

Default settings for WebSSOProfileOptions can be specified in bean samlEntryPoint of your securityContext.xml, e.g.:

<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>

TODO

TODO

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. Instance of org.springframework.security.saml.userdetails.SAMLUserDetailsService can be provided to supply application specific information about the authenticated user. Property forcePrincipalAsString can be used to force String value of the principal property. 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 credential) throws UsernameNotFoundException {
		Attribute accountID = credential.getAttributeByName("accountID");
		if (accountID == null || accountID.getAttributeValues() == null
					 || accountID.getAttributeValues().size() == 0) {
			return null;
		}
		XMLObject attributeValue = accountID.getAttributeValues().iterator().next();
		return attributeValue.getDOM().getTextContent();
	}

}

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

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 it's bean in the securityContext.xml, e.g.:

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

Two basic implementations are provided by default:

Context provider populates information about the local service provider (your application) such as entityId, role, metadata, security keys, SSL credetials and trust engines for verification of signatures and SSL/TLS connections. Once populated context is made available to all components participating in processing of the incoming or outgoing SAML messages. ContextProvider can customized to alter behavior of the SAML Extension. The default implementation org.springframework.security.saml.context.SAMLContextProviderImpl relies on information available in the ExtendedMetadata and performs the followign steps for creation of the context:

During initialization of SSO ContextProvider is also requested to provide metadata of the peer IDP. System performs these steps to locate peer IDP to use:

For security reasons system limits the time window enabling processing of SAML messages and assertions. The time window parameters can be customized with the following settings.

Validity of assertions processed during the signle sign-on process is limited to 3000 seconds. Value can be customized with property maxAssertionTime of the WebSSOProfileConsumerImpl bean.

System allows users to single sign-on for up to 7200 seconds since their initial authentication with the IDP (based on value AuthInstance of the Authentication statement). Some IDPs allow users to stay authenticated for longer periods than this and you might need to change the default value by setting maxAuthenticationAge of the WebSSOProfileConsumerImpl bean.

As clocks between IDP and SP machines may not be perfectly synchronized a tolerance of 60 seconds is applied for time comparisons. The tolerance value (time skew) can be customized by settings property responseSkew in beans WebSSOProfileConsumerImpl and SingleLogoutProfileImpl.

SAML Extension can be deployed in scenarios where mutliple back-end servers process SAML requests forwarded by a reverse-proxy or a load balancer. SSL termination proxies which communicate using an unencrypted channel between the proxy and back-end servers are also supported. In order to confugure SAML Extension for deployment behing a load balancer or a reverse-proxy please follow these steps: