Spring Security SAML Extension

Reference Documentation
1.0.0.RC3-SNAPSHOT

Vladimr Schfer

Copyright 2009-2013 Vladimr Schfer

Spring Security SAML Extension

Table of Contents
I. Getting Started ....................................................................................................................... 1
1. Introduction .................................................................................................................... 2
1.1. What this manual covers ..................................................................................... 2
1.2. When to use Spring Security SAML Extension ...................................................... 2
1.3. Features and supported profiles ........................................................................... 2
1.4. Requirements ...................................................................................................... 3
1.5. Source code ........................................................................................................ 3
1.6. Builds ................................................................................................................. 3
1.7. License ............................................................................................................... 3
1.8. Support ............................................................................................................... 3
2. Glossary ........................................................................................................................ 4
3. Quick start guide ............................................................................................................ 6
3.1. Pre-requisites ...................................................................................................... 6
3.2. Installation steps ................................................................................................. 6
Compilation of the module .................................................................................. 6
Configuration of IDP metadata ............................................................................ 6
Generation of SP metadata ................................................................................ 7
Deployment ........................................................................................................ 7
Uploading of SP metadata to the IDP .................................................................. 7
3.3. Testing single sign-on and single logout ............................................................... 8
II. Configuring SSO with SAML ................................................................................................... 9
4. Configuration and integration ........................................................................................ 10
4.1. Overview ........................................................................................................... 10
4.2. Integration to applications .................................................................................. 10
Maven dependency .......................................................................................... 10
Bean definitions ................................................................................................ 11
Spring Security integration ................................................................................ 11
4.3. Metadata configuration ....................................................................................... 11
Service provider metadata ................................................................................ 11
Automatic metadata generation ................................................................. 11
Pre-configured metadata ........................................................................... 14
Downloading metadata ............................................................................. 15
Identity provider metadata ................................................................................. 16
File-based metadata provider .................................................................... 16
HTTP-based metadata provider ................................................................. 16
Signature verification ................................................................................ 17
Extended metadata .......................................................................................... 17
4.4. Entity alias ........................................................................................................ 17
4.5. Key management .............................................................................................. 17
Sample keystore .............................................................................................. 18
Generating and importing private keys ............................................................... 18
Importing public keys ........................................................................................ 19
Loading SSL/TLS certificates ............................................................................ 19
4.6. Security profiles ................................................................................................. 19
Metadata interoperability profile (MetaIOP) ........................................................ 19
PKIX profile ...................................................................................................... 20
Custom profile .................................................................................................. 20

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

ii

Spring Security SAML Extension

4.7. Reverse proxies and load balancers ...................................................................

4.8. IDP selection and discovery ...............................................................................
4.9. Single sign-on process .......................................................................................
4.10. Logout process ................................................................................................
4.11. Authentication object ........................................................................................
4.12. Authentication log ............................................................................................
4.13. Context provider ..............................................................................................
4.14. Validity intervals ...............................................................................................
4.15. Enhanced client/proxy ......................................................................................
5. Administration user interface .........................................................................................
6. IDP integration guide ....................................................................................................
6.1. Active Directory Federation Services 2.0 (ADFS) .................................................
Initialize IDP metadata ......................................................................................
Initialize SP metadata .......................................................................................
Test SSO .........................................................................................................
7. Troubleshooting ............................................................................................................
7.1. Logging .............................................................................................................
7.2. Common problems ............................................................................................
A. Configuration reference ........................................................................................................
A.1. Extended metadata ...................................................................................................
A.2. Web SSO profile options ...........................................................................................

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

20
21
22
22
22
24
24
25
25
26
27
27
27
27
28
29
29
29
31
31
32

iii

Part I. Getting Started

This chapter provides essential information needed to enable your application to act as a service
provider and interact with identity providers using SAML 2.0 protocol. Later in this guide you can find
information about detailed configuration options and additional use-cases enabled by this component.

Spring Security SAML Extension

1. Introduction
1.1 What this manual covers
This manual describes Spring Security SAML Extension component, it's uses, installation, configuration,
design and tested environments.

1.2 When to use Spring Security SAML Extension

Component enables both new and existing applications to act as a Service Provider in federations based
on SAML 2.0 protocol and enable Web Single Sign-On. Spring Security Extension allows seamless
combination of SAML 2.0 and other authentication and federation mechanisms in a single application.
All products supporting SAML 2.0 in Identity Provider mode (e.g. ADFS 2.0, Shibboleth, OpenAM/
OpenSSO, RM5 IdM or Ping Federate) can be used to connect with Spring Security SAML Extension.
Extension can also be used in applications which are not primarily secured using Spring Security. It can
be adapted for both single and multi-tenant environments.
Spring Security SAML Extension can be either embedded inside your application and work along
other authentication or single sign-on mechanisms, or it can be deployed separately and convey
authentication information to applications using a custom mechanism.
Spring Security Extension is probably the most complete open-source SAML 2.0 SP implementation
with the widest feature-set and configuration possibilities. Other Java open-source alternatives are e.g.
native SAML service providers integrating with IIS or Apache from Shibboleth (SAML processing is done
on the web server and not on the application level) or OpenAM Fedlet.

1.3 Features and supported profiles

Current implementation should be conformant to SAML SP Lite and SAML eGovernment profile. The
following profiles, bindings and features are supported as part of the product:
Web single sign-on profile
Web single sign-on holder-of-key profile
IDP and SP initialized single sign-on
Single logout profile
Enhanced client/proxy profile
Identity provider discovery profile and IDP selection
Metadata interoperability and PKIX trust management
Automatic service provider metadata generation
Metadata loading from files, URLs, file-backed URLs
Processing and automatic reloading of metadata with many identity providers
Support for authentication contexts
Logging for authentication events
Customization of both SP and IDP metadata
Processing of SAML attributes and user data using UserDetails interface
Support for HTTP-POST, HTTP-Redirect, SOAP, PAOS and Artifact bindings
Easy integration with applications using Spring Security
Sample application with an user interface for quick configuration
Internal processing of SAML messages, marshalling and unmarshalling is handled by OpenSAML.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Spring Security SAML Extension

You can use the following supported standards as a reference:

SAML 2.0 basic profiles
http://docs.oasis-open.org/security/saml/v2.0/saml-core-2.0-os.pdf
http://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf
http://docs.oasis-open.org/security/saml/v2.0/saml-profiles-2.0-os.pdf
http://docs.oasis-open.org/security/saml/v2.0/saml-authn-context-2.0-os.pdf
http://docs.oasis-open.org/security/saml/v2.0/saml-bindings-2.0-os.pdf
http://docs.oasis-open.org/security/saml/v2.0/saml-conformance-2.0-os.pdf
SAML 2.0 additional profiles
http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-holder-of-key-browser-sso.pdf
http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml-idp-discovery.pdf
http://docs.oasis-open.org/security/saml/Post2.0/sstc-saml2-holder-of-key.pdf
http://docs.oasis-open.org/security/saml/Post2.0/sstc-metadata-iop.pdf
eGovernment profile
http://kantarainitiative.org/confluence/download/attachments/42139782/kantara-egov-saml2profile-2.0.pdf

1.4 Requirements
Spring Security SAML Extension requires as minimum Java 1.6.
TODO Apache Tomcat, Jetty, Oracle Weblogic, ....

1.5 Source code

Source code for the project is maintained on Github.

1.6 Builds
Snapshot builds of the project are available in the SpringSource repository

1.7 License
Source code of the module is licensed under the Apache License, Version 2.0. You may obtain copy of
the license at http://www.apache.org/licenses/LICENSE-2.0.

1.8 Support
Issue tracking for the module can be found at Spring Security Extensions Jira. Feel free to submit bugs,
patches and feature requests.
For community support please use Spring Security forum. For additional support you can reach me at
vladimir.schafer at gmail.com.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Spring Security SAML Extension

2. Glossary
Table 2.1. Definitions of terms used within this manual.
Term

Definition

Assertion

A part of SAML message (an XML document) which provides facts

about subject of the assertion (typically about the authenticated user).
Assertions can contain information about authentication, associated
attributes or authorization decisions.

Artifact

Identifier which can be used to retrieve a complete SAML message

from identity or service provider using a back-channel binding.

Binding

Mechanism used to deliver SAML message. Bindings are divided to

front-channel bindings which use web-browser of the user for message
delivery (e.g. HTTP-POST or HTTP-Redirect) and back-channel
bindings where identity provider and service provider communicate
directly (e.g. using SOAP calls in Artifact binding).

Discovery

Mechanism used to determine which identity provider should be used

to authenticate user currently interacting with the service provider.

Metadata

Document describing one or multiple identity and service providers.

Metadata typically includes entity identifier, public keys, endopoint
URLs, supported bindings and profiles, and other capabilities or
requirements. Exchange of metadata between identity and service
providers is typically the first step for establishment of federation.

Profile

Standardized combination of protocols, assertions, bindings and

processing instructions used to achieve a particular use-case such as
single sign-on, single logout, discovery, artifact resolution.

Protocol

Definition of format (schema) for SAML messages used to achieve

particular functionality such as requesting authentication from IDP,
performing single logout or requesting attributes from IDP.

Identity provider (IDP)

Entity which knows how to authenticate users and provides information

about their identity to service providers/relaying parties using
federation protocols.

Service provider (SP)

Your application which communicates with the identity provider in

order to obtain information about the user it interacts with. User
information such as authentication state and user attributes is provided
in form of security assertions.

Single Sign-On (SSO)

Process enabling access to multiple web sites without need to

repeatedly present credentials necessary for authentication. Various
federation protocols such as SAML, WS-Federation, OpenID or OAuth
can be used to achieve SSO use-cases. Information such as means
of authentication, user attributes, authorization decisions or security
tokens are typically provided to the service provider as part of single
sign-on.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Spring Security SAML Extension

Term

Definition

Single Logout (SLO)

Process terminating authenticated sessions at all resources which

were accessed using single sign-on. Techniques such as redirecting
user to each of the SSO participants or sending a logout SOAP
messages are typically used.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Spring Security SAML Extension

3. Quick start guide

This chapter will guide you through steps required to easily integrate Spring Security SAML Extension
with SSO Circle IDP service using SAML 2.0 protocol. When done you will have a working example of
Web SSO against a single Identity Provider. The steps will guide you through deployment of the module,
configuration of IDP metadata (XML document describing how to connect to the IDP server using SAML
2.0 protocol) and SP metadata (XML document describing your own service) and testing of web single
sign-on and single logout.

3.1 Pre-requisites
Please make sure the following items are available before starting the installation:
Supported application server or container
Spring Security SAML Extension
Java 1.6+ SDK
SAML Extension relies on XML processing capabilities of JAXP. Some older versions of JRE might
require updating of the embedded JAXP libraries. In case you encounter XML processing exceptions
please create folder jdk/jre/lib/endorsed in your JDK installation and include files in lib/endorsed from
the latest OpenSAML archive available at http://shibboleth.net/downloads/java-opensaml/. The location
of the endorsed folder may differ based on your application server or container.
Due to US export limitations Java JDK comes with a limited set of cryptography capabilities. Usage of
the SAML Extension might require installation of the Unlimited Strength Jurisdiction Policy Files which
removes these limitations.

3.2 Installation steps

Compilation of the module
When building from sources compile whole project using:
gradlew build

Command will create file spring-security-saml2-sample.war in directory saml2-sample/build/libs/.

When using the release zip compile the sample application available in the sample directory using:
mvn package

We will be customizing content of the application in the following steps.

Configuration of IDP metadata

Modify file WEB-INF/classes/security/securityContext.xml inside the war archive and replace metadata
bean as follows:

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Spring Security SAML Extension

<bean id="metadata"
class="org.springframework.security.saml.metadata.CachingMetadataManager">
<constructor-arg>
<list>
<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>
<value type="int">5000</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
</list>
</constructor-arg>
</bean>

The settings tell system to download IDP metadata from the given URL with timeout of 5 seconds. In
production system metadata should be either stored as a local file or be downloaded from a source
using SSL/TLS with configured trust or which provides digitally signed metadata.

Generation of SP metadata
Modify file WEB-INF/classes/security/securityContext.xml inside the war archive and replace
metadataGeneratorFilter bean as follows and make sure to replace the entityId value with a string which
is unique within the SSO Circle service (e.g. urn:test:yourname:yourcity):
<bean id="metadataGeneratorFilter"
class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
<constructor-arg>
<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
<property name="entityId" value="replaceWithUniqueIdentifier"/>
<property name="signMetadata" value="false"/>
</bean>
</constructor-arg>
</bean>

Deployment
Deploy the updated war archive to your application server or container. After deployment the SP module
will be available at e.g. http://localhost:8080/spring-security-saml2-sample

Uploading of SP metadata to the IDP

Download current SP metadata:
Open web browser at the URL of the deployed application.
Select Metadata information.
Select first item from category Service providers, e.g. http://localhost:8080/spring-security-saml2sample/saml/metadata/alias/defaultAlias
Copy content of the Metadata textarea to your clipboard.
Upload SP metadata to the IDP:
Register yourself at www.ssocircle.com and login to the service.
Select Metadata manager and click Add new Service Provider.
Enter entityId configured in the section called Generation of SP metadata to the FQDN field.
Paste content of clipboard to the metadata information textarea.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Spring Security SAML Extension

Store metadata by pressing the Submit button.

Logout from the SSOCircle service.

3.3 Testing single sign-on and single logout

Open the front page of your SP application, select http://idp.ssocircle.com IDP and press login. System
will generate new authentication request using SAML 2.0 protocol, digitally sign it and send it to the
IDP. After authentication at IDP with your account you will be redirected back to your application and
automatically signed-in.
Pressing local logout will destroy local session and logout the user. Session is still active at the IDP and
an attempt to reauthenticate will proceed without need to enter credentials.
Pressing global logout will destroy both local session and session at IDP.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

Part II. Configuring SSO with SAML

This chapter provides information about configuration and customization options of the SAML extension.
It will guide you throught typical scenarios including problems you migth encounter during integration
with identity providers.

Spring Security SAML Extension

4. Configuration and integration

This chapter will discuss aspects of configuring and using the library in target applications.

4.1 Overview
Spring Security SAML 2.0 library comprises three modules:
saml2-core contains implementation of the WebSSO profiles of the SAML 2.0 protocol and is required
for integration to target systems.
saml2-sample contains example of Spring configuration used for integration to target systems. It also
contains user interface for generation and management of metadata.
saml2-doc contains this documentation.
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:
integration to application using Spring XML configuration
import, generation and customization of SP and IDP metadata
configuration of signature, encryption and trust keys
configuration of security profiles
configuration of reverse proxy or load balancer
configuration of IDP selection or discovery
configuration of single sign-on process
configuration of logout process
configuration of authentication object
configuration of authentiction log
Additional steps such as customization of SAML 2.0 bindings, configuration of artifact resolution or
configuration of time skews might be needed.

4.2 Integration to applications

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.

Maven dependency
In order to include the library and all it's 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.5.3. Later versions of these libraries are likely to be compatible without modifications.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

10

Spring Security SAML Extension

Bean definitions
Configuration of the SAML library requires beans definitions included in the saml2-sample/src/main/
resources/security/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 Security integration

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>

4.3 Metadata configuration

SAML metadata is an XML document which contains information necessary for interaction with SAMLenabled 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.

Service provider metadata

Service provider metadata contains keys, services and URLs defining SAML endpoints of your
application. Metadata can be either generated automatically upon first request to the service, or it can
be pre-created (see Chapter 5, Administration user interface). Once created metadata needs to be
provided to the identity providers with whom we want to establish trust.
Automatic metadata generation
Automatic metadata generation is enabled by including the following filter in the Spring Security
configuration:
<security:custom-filter before="FIRST" ref="metadataGeneratorFilter"/>

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

11

Spring Security SAML Extension

Filter is automatically invoked as part of the first request to a URL processed by Spring Security. In
case there is no service provider metadata already specified (meaning property hostedSPName of the
metadata bean is empty) filter will generate a new one.
By default metadata will be generated with the following values which can be customized by setting
properties of the metadataGenerator bean:
Table 4.1. Metadata generator settings
Property

Description

Default value

entityBaseURL

Base URL to construct SAML

Values from the request in format:
endpoints from, needs to be a
scheme://server:port/contextPath
URL with protocol, server, port and
context path.

entityAlias

Local alias for the entityId which

can be part of a simple URL path
and contains only alphanum
characters. See Section 4.4,
Entity alias.

defaultAlias

entityId

Unique identifier of the service

provider.

<entityBaseUrl>/saml/ metadata/
alias/<entityAlias>

requestSigned

Flag indicating whether this service true

signs authentication requests.

wantAssertionSigned Flag indicating whether this service true

requires signed assertions.
signingKey

Key to include with usage "signing" Default private key from the
in the metadata. Value will be
KeyManager
set in ExtendedMetadata as
signingKey.

encryptionKey

Key to include with

usage "encryption" in the
metadata. Value will be set
in ExtendedMetadata as
encryptionKey.

Default private key from the

KeyManager

tlsKey

Key to include with usage

"unspecified" in the
metadata. Value will be set in
ExtendedMetadata as tlsKey.

By default not included. Key is

only included in metadata when
it's different from signing and
encryption keys.

signMetadata

When true generated metadata will true

be signed using XML Signature
using certificate with alias of
signingKey.

bindingsSSO

Bindings to be included in the

metadata for WebSSO profile.
Supported values are: POST,

1.0.0.RC3-SNAPSHOT

Artifact, POST, PAOS

Spring Security SAML Extension

12

Spring Security SAML Extension

Property

Description

Default value

Artifact and PAOS. Order

of bindings in the property
determines order of endpoints in
the generated metadata.
bindingsHoKSSO

Bindings to be included in the

metadata for WebSSO Holderof-Key profile. Supported values
are: POST and Artifact. Order
of bindings in the property
determines order of endpoints in
the generated metadata.

Artifact, POST

bindingsSLO

Bindings to be included in the

metadata for Single Logout profile.
Supported values are: POST and
Redirect. Order of bindings in
the property determines order
of endpoints in the generated
metadata.

POST, Redirect

assertionConsumerIndex
Index of assertion consumer point
to be marked as default.

includeDiscovery

When true system will initialize

discovery process during attempt
to initialize single sign-on without
pre-selected IDP.

customDiscoveryURL

When includeDiscovery is true generated value for internal

value overrides default discovery
discovery service, deprecated,
request URL.
use property idpDiscoveryURL in
extendedMetadata instead

customDiscoveryResponseURL
When
includeDiscoveryExtension
is true value overrides default
discovery response URL.

true, deprecated, use property

idpDiscoveryEnabled in
extendedMetadata instead

generated value for entry

point response URL,
deprecated, use property
idpDiscoveryResponseURL in
extendedMetadata instead

includeDiscoveryExtension
When true generated metadata will false
contain extension indicating that
it's able to consume response from
an IDP Discovery service.
nameID

1.0.0.RC3-SNAPSHOT

Name identifiers to be included

in the metadata. Supported
values are: EMAIL, TRANSIENT,
PERSISTENT, UNSPECIFIED
and X509_SUBJECT. Order
of NameIDs in the property

EMAIL, TRANSIENT,
PERSISTENT, UNSPECIFIED,
X509_SUBJECT

Spring Security SAML Extension

13

Spring Security SAML Extension

Property

Description

Default value

determines order of NameIDs in

the generated metadata.
extendedMetadata

Additional settings such as

IDP discovery, ECP settings,
security profiles and signature
requirements can be specified
in the ExtendedMetadata, see
Section A.1, Extended metadata
for details.

Property entityBaseUrl is automatically generated based on values in the first HTTP request,
unless explictly specified in the MetadataGenerator. Generated value can be normalized to exclude
standard 80/443 ports for http/https schemes by setting property normalizeBaseUrl of the
MetadataGeneratorFilter to true.
Providing an empty collection or null value to properties bindingsSSO, bindingsHoKSSO and
bindingsSLO will disable and remove the given profile. For example the following setting removes the
holder-of-key profile from the generated metadata, forces artifact binding for single sign-on and redirect
binding for single logout:
<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>

By default generated metadata will be digitally signed using the default credential specified in
KeyManager (see Section 4.5, Key management for details). Digital signature can be disabled using
property signMetadata of the metadataGeneratorFilter bean.
In case application is deployed behind a reverse-proxy or other mechanism which makes the URL at
the application server different from the URL seen by client at least property entityBaseURL should
be set to a value e.g. https://www.server.com:8080 For details about load balancing see Section 4.7,
Reverse proxies and load balancers.
Pre-configured metadata
In some situations it is beneficial to provide static version of the metadata document instead of the
automatic generation. Need for manual changes in the metadata or fixing of production settings are
some of those. Custom metadata document describing local SP application can be added by updating
the metadata bean with correct ExtendedMetadata. Please follow these steps in order to do so:
Generate and download metadata, e.g. using the Metadata information -> Generate new service
provider metadata option in the sample application's administration UI or using instructions in the
section called Automatic metadata generation.
Store the metadata file as part of your project classpath, e.g. in WEB-INF/classes/security/
localhost_sp.xml.
Disable the automatic metadata generator by removing the following custom filter from the
securityContext.xml:

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

14

Spring Security SAML Extension

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

Include the SP metadata in the metadata bean and mark the entity as local in the extended metadata.
Make sure to specify the alias property in case it was used during metadata generation.
It is recommended to use the administration UI which also generates all the Spring declarations ready
for inclusion in your securityContext.xml.
<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/localhost_sp.xml</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
</constructor-arg>
<constructor-arg>
<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
<property name="local" value="true"/>
<property name="alias" value="default"/>
<property name="securityProfile" value="metaiop"/>
<property name="sslSecurityProfile" value="pkix"/>
<property name="signingKey" value="apollo"/>
<property name="encryptionKey" value="apollo"/>
<property name="requireArtifactResolveSigned" value="false"/>
<property name="requireLogoutRequestSigned" value="false"/>
<property name="requireLogoutResponseSigned" value="false"/>
<property name="idpDiscoveryEnabled" value="true"/>
<property name="idpDiscoveryURL"
value="https://www.server.com:8080/context/saml/discovery/alias/default"/>
<property name="idpDiscoveryResponseURL"
value="https://www.server.com:8080/context/saml/login/alias/default?disco=true"/>
</bean>
</constructor-arg>
</bean>

Same instance of your application can include multiple statically declared local service providers each
differentiated with it's own unique alias and entity ID. Each service provider can e.g. process a different
domain or have different security key settings. This feature makes it possible to create multi-tenant
applications with individual SAML settings for each of the tenants. In case multiple local SPs are
declared, property hostedSPName of the metadata bean should be set to the entity ID of the default one.
For details about available settings of the ExtendedMetadata see Section A.1, Extended metadata.
Downloading metadata
Metadata describing the default local application can be downloaded from URL:
https://www.server.com:8080/context/saml/metadata

In case application is configured to contain multiple service providers metadata for each can be loaded
by adding the alias:
https://www.server.com:8080/context/saml/login/alias/defaultAlias

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

15

Spring Security SAML Extension

URL for metadata download can be disabled by removing filter metadataDisplayFilter from the
securityContext.xml.
Metadata is also available in the sample application's administration UI under Metadata information > selected SP.

Identity provider metadata

Metadata for identity providers is imported to the metadataManager in a similar way as pre-configured
SP metadata. Metadata containing one or many identity providers can be added by providing an URL or
a file. Processing of metadata and processing of SAML messages can be customized using properties
of ExtendedMetadataDelegate and ExtendedMetadata.
File-based metadata provider
File-based provider loads metadata from a file available in the filesystem or classpath.
<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>

Metadata is automatically refreshed in intervals specified by properties minRefreshDelay and

maxRefreshDelay of the MetadataProvider bean.
HTTP-based metadata provider
HTTP-based provider loads metadata from an URL.
<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>

Metadata is automatically refreshed in intervals specified by properties minRefreshDelay and

maxRefreshDelay of the MetadataProvider bean.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

16

Spring Security SAML Extension

Alternatively class org.opensaml.saml2.metadata.provider.FileBackedHTTPMetadataProvider can be

used to provide a backup in case URL is temporarily unavailable. File to use as backup is specified as
third argument in the MetadataProvider bean constructor.
Signature verification
Importing of digitally signed metadata requires verification of signature's validity and trust. Metadata is
not required to be signed by default. When present, signature is verified with PKIX algorithm and uses
all public keys present in the configured keyManager as trust anchors. Make sure to include root CA
certificate and intermediary CA certificates of the signature in your keyStore. For details see the section
called Importing public keys.
You can limit certificates used to peform the verification by setting property metadataTrustedKeys of the
ExtendedMetadataDelegate bean. The provided collection should contain aliases of keys to be used
as trust anchors.
Signature verification can be disabled by setting property metadataTrustCheck to false in the
ExtendedMetadataDelegate bean. Setting metadataRequireSignature to true will reject metadata unless
it's digitally signed.

Extended metadata
Additional processing instructions related to SAML exchanges with the IDP can be defined in
ExtendedMetadata bean. In case your metadata document contains multiple identity providers (in
multiple EntityDescriptor elements) extended metadata can be set separately for each of them using a
map with entity ids as keys, e.g.:
<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>

For details about available settings of the ExtendedMetadata see Section A.1, Extended metadata.

4.4 Entity alias

TODO

4.5 Key management

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.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

17

Spring Security SAML Extension

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.

Sample keystore
Sample application contains a default key store with a sample private certificate usable for test purposes.
The key store is defined as:
<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>

The first argument points to the used key store file, second contains password for the keystore, third
then map with passwords for private keys with alias-password value pairs. Alias of the default certificate
is the last parameter.

Generating and importing private keys

Private keys (with either self-signed or CA signed certificates) are used to digitally sign SAML messages,
encrypt their content and in some cases for SSL/TLS Client authentication of your service provider
application. SAML Extension ships with a default private key in the samlKeystore.jks with alias apollo
which can be used for initial testing, but for security reason should be replaced with your own key in
early development stages.
In case your IDP doesn't require keys signed by a specific certification authority you can generate your
own self-signed key using the Java utility keytool, e.g. with:
keytool -genkeypair -alias some-alias -keypass changeit -keystore samlKeystore.jks

The keystore will now contain additional PrivateKeyEntry with alias mykey which can be imported to the
keyManager in your securityContext.xml.
Keys signed by certification authorities are typically provided in .p12/.pfx format (or can be converted to
such using OpenSSL) and imported to Java keystore with, e.g.:
keytool -importkeystore -srckeystore key.p12 -srcstoretype PKCS12 -srcstorepass password \
-alias some-alias -destkeystore samlKeystore.jks -destalias some-alias -destkeypass
changeit

The following command can be used to determine available alias in the p12 file:
keytool -list -keystore key.p12 -storetype pkcs12

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

18

Spring Security SAML Extension

Importing public keys

Cryptographic material used to decrypt incoming data and verify trust of signatures in SAML messages
and metadata is stored either in metadata of remote entities or in the keyManager. In order to import
additional trusted key to the keystore run, e.g.:
keytool -importcert -alias some-alias -file key.cer -keystore samlKeystore.jks

Imported keys can be referenced in ExtendedMetadataDelegate and ExtenedMetadata beans, for

details see the section called Signature verification and Section 4.6, Security profiles.

Loading SSL/TLS certificates

Direct SSL/TLS connections (used with HTTP-Artifact binding) require verification of the public key
presented by the server. The SSL Extractor utility can be used to extract certificates presented by an
SSL/TLS endpoint, e.g. with:
java -jar sslextractor-0.9.jar www.google.com 443

The certificates are stored as .cer files and can be imported to the keystore as a usual public key. For
details about configuring of trust for SSL/TLS connections see Section 4.6, Security profiles.

4.6 Security profiles

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.

Metadata interoperability profile (MetaIOP)

With MetaIOP mode certificates are not checked for expiration or revocation and certificate paths are
not verified. This means that it does not matter which certification authority issued the certificate, as
the fact whether the certificate is trusted or not is conveyed using other mechanisms (e.g. by secure
metadata exchange or digital signature of metadata itself).
Signature is deemed trusted when the certificate used to create it is included in one of the following
places:

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

19

Spring Security SAML Extension

Key with usage of signing or unspecified in entity metadata of a remote entity

Signing key specified in property signingKey of extended metadata of a remote entity
MetaIOP is the default profile for verification of XML signatures. For details about this profile see the
specification.

PKIX profile
With PKIX profile trust of signature certificates is verified based on a certificate path between trusted
CA certificates and the certificate in question. Certificate is trusted when it's possible to construct path
from a trusted certificate to the validated one. With this profile certificate expiration and revocation can
be checked.
Trusted keys (anchors) for PKIX verification of signatures are combined from the following places:
Key with usage of signing or unspecified in entity metadata of a remote entity
Signing key specified in property signingKey of extended metadata of a remote entity
All keys specified in trustedKeys set of extended metadata of a remote entity

Custom profile
Engine used to verify trust of signatures for given combination of SP/IDP
is created in methods populateTrustEngine and populateSSLTrustEngine of interface
org.springframework.security.saml.context.SAMLContextProvider and can be overriden with custom
implementation. See Section 4.13, Context provider for details on context customization.

4.7 Reverse proxies and load balancers

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:
Make sure that your reverse-proxy or load-balancer is configured to use sticky sessions. Information
about e.g. sent requests is stored within user's HTTP session and sending of response to another
back-end node would make the original request data unavailable and fail the validation. Sticky session
are not necessary in case only IDP-initialized SSO is used.
Provide information about front-end URL to the back-end servers by changing
the
contextProvider
bean
implementation
in
your
securityContex.xml
to
class
org.springframework.security.saml.context.SAMLContextProviderLB:
<bean id="contextProvider"
class="org.springframework.security.saml.context.SAMLContextProviderLB">
<property name="scheme" value="https"/>
<property name="serverName" value="www.myserver.com"/>
<property name="serverPort" value="443"/>
<property name="includeServerPortInRequestURL" value="false"/>
<property name="contextPath" value="/spring-security-saml2-sample"/>
</bean>

This setting enables extension to correctly form all generated URLs and verify endpoints of the
incoming SAML messages.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

20

Spring Security SAML Extension

In case you use automatically generated metadata make sure to configure entityBaseUrl matching
the front-end URL in your metadataGeneratorFilter bean:
<bean id="metadataGeneratorFilter"
class="org.springframework.security.saml.metadata.MetadataGeneratorFilter">
<constructor-arg>
<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
<property name="entityBaseURL" value="https://www.myserver.com/spring-security-saml2sample"/>
</bean>
</constructor-arg>
</bean>

4.8 IDP selection and discovery

SAML Extension supports the Identity Provider Discovery Service Protocol and Profile.
IDP discovery can always be skipped during SSO initialization by specifying HTTP request parameter
idp with the entityId of the required IDP, e.g. http://host:port/app/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>

It is possible to configure the following IDP discovery modes:

Local discovery service

SAML Extension includes a local IDP discovery service which presents user with an IDP selection page.
The selection page can be customized using property idpSelectionPath on bean samlIDPDiscovery.
System forwards to this page during discovery request and includes the following request attributes:
idpDiscoReturnURL - URL to send the IDP selection result to using GET action
idpDiscoReturnParam - name of the GET parameter to include the entity ID of the selected IDP
See the default implementation in saml2-sample/src/main/webapp/WEB-INF/security/idpSelection.jsp
for an example.

Remote discovery service

In order to enable external IDP discovery service configure property idpDiscoveryURL in your local
SP extended metadata to the external discovery URL. Make sure property idpDiscoveryEnabled is set
to true. For details on configuring local extended metadata see the section called Service provider
metadata.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

21

Spring Security SAML Extension

Default IDP without discovery

In this mode system automatically selects the default IDP and doesn't perform discovery. Mode can be
enabled by setting property includeDiscovery in the local SP extended metadata to false. For details on
configuring local extended metadata see the section called Service provider metadata.
The default IDP can be configured using propery defaultIDP on bean metadata in the Spring Security
configuration.

4.9 Single sign-on process

SP initialized SSO process can be started in two ways:
User accesses a resource protected by Spring Security which initializes SAMLEntryPoint
User is redirected to the SSO page at e.g. https://www.server.com/context/saml/login/alias/
defaultAlias
After identification of IDP to use (for details see Section 4.8, IDP selection and discovery) 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.
For details about available settings of the WebSSOProfileOptions see Section A.2, Web SSO profile
options.
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>

4.10 Logout process

TODO

4.11 Authentication object

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

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

22

Spring Security SAML Extension

pages secured with Spring Security using SecurityContextHolder.getContext().getAuthentication() and

is populated with the following values:
Table 4.2. ExpiringUsernameAuthenticationToken values.
Property

Value

Principal

When forcePrincipalAsString = false AND userDetail = null (default) - NameID

object included in the SAML Assertion (credential.getNameID() of type
org.opensaml.saml2.core.NameID)

Principal

When forcePrincipalAsString = true - String value of NameID included in the SAML

Assertion (credential.getNameID().getValue() of type java.lang.String)

Principal

When forcePrincipalAsString = false AND userDetail != null - UserDetail object

returned from the SAMLUserDetailsService

Credentials

SAML authentication object including entity ID of local and remote entity, name ID,
assertion and relay state (org.springframework.security.saml.SAMLCredential)

Authorities

Result of getAuthorities() call on the UserDetails object returned from

SAMLUserDetailsService, empty list when there's no UserDetail object available.

Expiration

Value of SessionNotOnOrAfter in the SAML Assertion when avaialble, null

otherwise. Authentication object will start returning false on the isAuthenticated()
after the expiration time.

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

org.opensaml.saml2.core.Attribute;
org.opensaml.xml.XMLObject;
org.springframework.security.core.userdetails.UsernameNotFoundException;
org.springframework.security.saml.SAMLCredential;
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.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

23

Spring Security SAML Extension

4.12 Authentication log

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:

org.springframework.security.saml.log.SAMLEmptyLogger
Doesn't perform any logging, simply ignores all events.
org.springframework.security.saml.log.SAMLDefaultLogger
Logs events as INFO level messages to the standard log configurable as described in Section 7.1,
Logging. Setting property logMessages to true will include content of the SAML messages as part
of the log. Logging of exceptions can be disalbed by setting logErrors to false.

4.13 Context provider

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:
Locate entityId of the local SP by parsing part of the URL after /alias/ (e.g. myAlias in https://
www.myserver.com/saml_extension/saml/sso/alias/myAlias?idp=myIdp) and match it with property
alias specified in the ExtendedMetadata. In case URL doesn't contain any alias part the default service
provider configured with property hostedSPName on the metadata bean is used.
Populate credential used to decrypt data sent to this service provider. In case ExtendedMetadata
specifies property encryptionKey it will be used as an alias to lookup a private key from the
keyManager bean. Otherwise defaultKey of the keyManager bean will be used.
Populate credential used for SSL/TLS client authentication. In case ExtendedMetadata specifies
property tlsKey it will be used as an alias to lookup key from keyManager bean. Otherwise no
credential will be provided for client authentication.
Populate trust engine for verification of signatures. Depending on securityProfile setting in the
ExtendedMetadata trust engine based on either the section called Metadata interoperability profile
(MetaIOP) or the section called PKIX profile is created.
Populate trust engine for verification of SSL/TLS connections. Depending on sslSecurityProfile setting
in the ExtendedMetadata trust engine based on either the section called Metadata interoperability
profile (MetaIOP) or the section called PKIX profile is created.
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:

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

24

Spring Security SAML Extension

Load parameter idp of the HttpRequest object and try to locate peer IDP by the entityId. When
there's no idp parameter provided system will either start IDP discovery process (when enabled in
the ExtendedMetadata of the local SP) or use the default IDP specified in the metadata bean.

4.14 Validity intervals

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.

4.15 Enhanced client/proxy

Support for enhanced client/proxy can be configured using property ecpEnabled of the service
provider's extended metadata. Once enabled, ECP profile is automatically activated with requests
containing HTTP headers Accept: application/vnd.paos+xml and PAOS: ver='urn:liberty:paos:2003-08';
'urn:oasis:names:tc:SAML:2.0:profiles:SSO:ecp'. Binding used to server ECP profile is always
automatically set to PAOS.
ECP can be enabled in combination with the automatic metadata generation using the following settings:
<bean class="org.springframework.security.saml.metadata.MetadataGenerator">
<property name="extendedMetadata">
<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
<property name="ecpEnabled" value="true"/>
</bean>
</property>
</bean>

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

25

Spring Security SAML Extension

5. Administration user interface

TODO

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

26

Spring Security SAML Extension

6. IDP integration guide

This chapter provides step-by-step guides for basic configuration of SAML Extension with specific IDP
products. Integration can be further configured with settings discussed in previous chapters.

6.1 Active Directory Federation Services 2.0 (ADFS)

ADFS 2.0 supports SAML 2.0 in IDP mode and can be easily integrated with SAML Extension for both
SSO and SLO. Before starting with the configuration make sure that the following pre-requisites are
satisfied:

Install AD FS 2.0 (http://www.microsoft.com/en-us/download/details.aspx?id=10909)

Run AD FS 2.0 Federation Server Configuration Wizard in the AD FS 2.0 Management Console
Make sure that DNS name of your Windows Server is available at your SP and vice-versa
Install a Java container (e.g. Tomcat) for deployment of the SAML 2 Extension
Configure your container to use HTTPS, this is required by AD FS (http://tomcat.apache.org/
tomcat-6.0-doc/ssl-howto.html)

Initialize IDP metadata

Download
AD
FS
2.0
metadata
from
https://server/FederationMetadata/2007-06/
FederationMetadata.xml
Store the downloaded content to saml2-sample/WEB-INF/src/main/resources/security/
FederationMetadata.xml
Modify bean metadata in securityContext.xml and replace classpath:security/idp.xml with
classpath:security/FederationMetadata.xml and add property metadataTrustCheck to false to skip
signature validation:
<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/FederationMetadata.xml</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
</constructor-arg>
<constructor-arg>
<bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
</constructor-arg>
<property name="metadataTrustCheck" value="false"/>
</bean>

Initialize SP metadata
Deploy SAML 2 Extension war archive from saml2-sample/target/spring-security-saml2-sample.war
Open browser at e.g. https://server:port/spring-security-saml2-sample, make sure to use HTTPS
protocol, system will automatically generate metadata document
Click Metadata information, select item with your server name in the Service providers list
Store content of the Metadata field to a document metadata.xml and upload it to the AD FS server
In AD FS 2.0 Management Console select "Add Relying Party Trust"
Select "Import data about the relying party from a file" and select file created earlier, select Next

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

27

Spring Security SAML Extension

System may complain that some content of metadata is not supported, you can safely ignore this
warning
Continue with the wizard, on the "Ready to Add Trust" make sure that tab endpoints contains multiple
endpoing values, if not verify that your metadata was generated with https protocol in their URLs
Leave "Open the Edit Claim Rules dialog" checkbox checked and finish the wizard
Select "Add Rule", choose "Send LDAP Attributes as Claims" and press Next
Add NameID as "Claim rule name", choose "Active Directory" as Attribute store, choose "SAMAccount-Name" as LDAP Attribute and "Name ID" as "Outgoing claim type", finish the wizard and
confirm the claim rules window
Open the provider by double-clicking it, select tab Advanced and change "Secure hash algorithm"
to SHA-1

Test SSO
Open SAML Extension at https://localhost:8443/spring-security-saml2-sample, select your AD FS
server and press login. In case Artifact binding is used and SSL/TLS certificate of your AD FS is not
already trusted you have to import it to your samlKeystore.jks by following instructions in the error report.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

28

Spring Security SAML Extension

7. Troubleshooting
7.1 Logging
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.
You can enable debug logging by modifying file saml2-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.

7.2 Common problems

Time synchronization
Processing of SAML messages and assertions is often limited to a specific time window which e.g.
prevents possibilities of replay attacks. Validation of messages can fail when internal clocks of the IDP
and SP machines are not synchronized. Make sure to use a time synchronization service on all systems
in the federation.

Error 'InResponseToField doesn't correspond to sent message' during SSO

Make sure that application uses the same HttpSession during sending of the request and reception of
the response. Typically, this problem arises when the auhentication request is initialized from localhost
address or http scheme, while response is received at a public host name or https scheme. E.g., when
initializing authentication from URL https://host:port/app/saml/login, the response must be received
at https://host;port/app/saml/SSO, not http://host:port/app/saml/SSO or https://localhost:port/app/saml/
SSO.
The checking of the InResponseToField can be disabled by re-configuring the context provider as
follows:
<bean id="contextProvider"
class="org.springframework.security.saml.context.SAMLContextProviderImpl">
<property name="storageFactory">
<bean class="org.springframework.security.saml.storage.EmptyStorageFactory"/>
</property>
</bean>

System is redirecting to e.g. localhost address when public facing URL is

different
In case you use automatic metadata generation make sure to set property entityBaseURL on bean
MetadataGenerator to e.g. http://server:port/yourapp or use pre-generated metadata.

Single logout not working as expected

Make sure the <security:logout.../> element is not specified within the <security:http> element.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

29

Spring Security SAML Extension

System fails during decryption or encryption of fields, e.g. with 'Failed to

decrypt EncryptedData'
Make sure the Unlimited Strength Jurisdiction Policy Files are correctly installed in your JDK. See
Section 3.1, Pre-requisites for details.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

30

Spring Security SAML Extension

Appendix A. Configuration reference

This chapter provides reference for settings available in configuration beans of the SAML module.

A.1 Extended metadata

Extended metadata provides additional settings for customization of IDP and SP behavior. Bean can
be found in package org.springframework.security.saml.metadata.ExtendedMetadata. For details on
setting up extended metadata please consult the section called Service provider metadata for local
SP, and the section called Identity provider metadata for remote IDPs. The same class is used for
both local service providers and remote identity providers; each value contains information about the
entities it's valid for.
Table A.1. Extended metadata settings
Property

Default

Entities

Description

local

false

local
and
remote

True for metadata of a local service provider.

False for remote identity providers.

alias

defaultAlias
local
only

Unique alias used to identify the selected local

service provider based on used URL. See
Section 4.4, Entity alias.

idpDiscoveryEnabled

false

local
only

When true system will initialize IDP discovery

when no IDP is selected during SSO
initialization. See Section 4.8, IDP selection
and discovery.

idpDiscoveryURL

internal local
discovery only
URL

URL of the IDP discovery service. Only used

when discovery is enabled.

idpDiscoveryResponseURL

internal local
discovery only
URL

URL expecting response from the IDP

discovery service. Only used when discovery is
enabled.

ecpEnabled

false

local
only

Property enables support for the SAML 2.0

ECP profile. See Section 4.15, Enhanced
client/proxy.

securityProfile

metaiop

local
only

Security profile for verification of message

signatures. See Section 4.6, Security profiles.

sslSecurityProfile

pkix

local
only

Security profile for vericiation of SSL/TLS

endpoint trust. See Section 4.6, Security
profiles.

signingKey

local
and
remote

For local entities alias of private key used to

create signatures. The default private key is
used when no value is provided. For remote

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

31

Spring Security SAML Extension

Property

Default

Entities

Description
identity providers defines an additional public
key used to verify signatures.

encryptionKey

local
and
remote

For local entities alias of private key used to

encrypt data. The default private key is used
when no value is provided. For remote identity
providers defines an additional public key used
to decrypt data.

tlsKey

local
and
remote

For local entities alias of private key used

for SSL/TLS client authentication. No client
authentication is used when value is not
specified. For remote identity providers
defines an additional public key used for trust
resolution.

trustedKeys

remote

Keys included as trusted anchors during PKIX

evaluation. All keys in the keyStore are used
as trust anchors with null value. Keys are only
used with PKIX security profile.

requireLogoutRequestSigned true

local
and
remote

For local entities enables requirement of signed

logout requests. For remote entities enables
signing of requests sent to the IDP.

requireLogoutResponseSigned false

local
and
remote

For local entities enables requirement of signed

logout responses. For remote entities enables
signing of responses sent to the IDP.

requireArtifactResolveSigned true

remote
only

Enables signing of artifact resolution requests

sent to the remote identity providers.

A.2 Web SSO profile options

Web SSO profile options customize creation of the authentication request sent to the IDP. For details
on using the profile consult Section 4.9, Single sign-on process. The following SSO parameters can
be customized using the WebSSOProfileOptions object:
Table A.2. org.springframework.security.saml.websso.WebSSOProfileOptions parameters
Property

Description

binding

Default: binding of the first declared SingleSignOnService

in IDP metadata. Binding used to send message to IDP.
Supported values depend on the SP configuration, typically
"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST",
"urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect",
"urn:oasis:names:tc:SAML:2.0:bindings:PAOS" and
"urn:oasis:names:tc:SAML:2.0:profiles:holder-of-key:SSO:browser".

providerName

Default: empty. Human readable name of the local SP sent with the
authentication request.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

32

Spring Security SAML Extension

Property

Description

assertionConsumerIndex

Default: empty. When set determines where should IDP send

response and which binding to use. Otherwise system uses the default
assertion consumer service marked as default, or first applicable.
Available indexes can be found in metadata of this service provider.

nameID

Default: empty. Name ID to request from IDP in the NameIDPolicy.

No NameIDPolicy is sent when not specified. Typical values are
"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
"urn:oasis:names:tc:SAML:2.0:nameid-format:transient",
"urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
"urn:oasis:names:tc:SAML:2.0:nameid-format:encrypted".

allowCreate

Default: empty. Only applicable when nameID is specified, when

true instructs IDP that it is allowed to create new user based on the
authentication request.

passive

Default: false. Sets whether the IdP should refrain from interacting with
the user during the authentication process.

forceAuthn

Default: false. When true IDP is required to re-authenticate user and

not rely on previous authentication events.

includeScoping

Default: true. When true request will include Scoping element.

allowedIDPs

Default: empty. Values to be included in the Scoping element on top

of the IDP message is sent to. Only applicable when includeScoping is
set to true.

proxyCount

Default: 2. Determines value to be used in the proxyCount attribute

of the scope in the AuthnRequest. Use zero to disable proxying or
value >0 to specify how many hops are allowed. Only applicable when
includeScoping is set to true.

authnContexts

Default: empty. Authentication contexts IDP is allowed to use when

authenticating user. See the specification for details.

authnContextComparison

Default: AuthnContextComparisonTypeEnumeration.EXACT.
Mechanism used by IDP to determine authentication method to use.
See the specification for details.

relayState

Default: empty. Value is sent to IDP and provided back to SP as part of

the authentication response.

1.0.0.RC3-SNAPSHOT

Spring Security SAML Extension

33