4. Quick start guide

This chapter will guide you through steps required to easily integrate Spring Security SAML Extension with ssocircle.com's 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 sample application, 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.

Public demo of the sample application is available at saml-federation.appspot.com

4.1 Pre-requisites

Please make sure the following items are available before starting the installation:

  • Java 1.6+ SDK

  • Apache Maven

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 https://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.

4.2 Installation steps

4.2.1 Downloading sample application

Download the Spring SAML Extension either from sources or from one of the releases.

The Spring SAML Sample application is included in sample directory. We will be customizing content of the sample application in the following steps.

4.2.2 Configuration of IDP metadata

Modify file sample/src/main/webapp/WEB-INF/securityContext.xml of the sample application and replace metadata bean as follows:

<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">https://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.

4.2.3 Generation of SP metadata

Modify file sample/src/main/webapp/WEB-INF/securityContext.xml of the sample application, 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="extendedMetadata">
				<bean class="org.springframework.security.saml.metadata.ExtendedMetadata">
					<property name="signMetadata" value="false"/>
					<property name="idpDiscoveryEnabled" value="true"/>
				</bean>
			</property>
		</bean>
	</constructor-arg>
</bean>

4.2.4 Compilation

When building from sources compile whole project and install artifacts into your local Maven repository using:

gradlew build install

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

mvn package

You can find the compiled war archive spring-security-saml2-sample.war in directory sample/build/libs/ (gradle) or sample/target/ (maven).

Project files for your IDE can be created with gradlew eclipse or gradlew idea.

4.2.5 Deployment

You can start the application from the release sample directory using command:

mvn tomcat7:run

Same can be achieved using gradle with:

gradlew tomcatRun

After startup the Spring SAML sample application will be available at http://localhost:8080/spring-security-saml2-sample

Alternatively you can deploy the war archive to your application server or container.

4.2.6 Uploading of SP metadata to the IDP

Download current SP metadata:

  • Open web browser to the URL of the deployed application.

  • Select Metadata information.

  • Select first item from category Service providers, e.g. http://localhost:8080/spring-security-saml2-sample/saml/metadata

  • 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 Section 4.2.3, “Generation of SP metadata” in the FQDN field.

  • Paste content of clipboard into the metadata information textarea.

  • Store metadata by pressing the Submit button.

  • Logout from the SSOCircle service.

4.3 Testing single sign-on and single logout

Open the front page of your SP application, select https://idp.ssocircle.com IDP and press login. The system will generate a 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. While a session is still active at the IDP an attempt to reauthenticate will proceed without need to enter credentials.

Pressing global logout will destroy both local session and the session at IDP.

You can test IDP initialized single sign-on with URL https://idp.ssocircle.com:443/sso/saml2/jsp/idpSSOInit.jsp?metaAlias=/publicidp&spEntityID=replaceWithUniqueIdentifier, after replacing the service provider identifier with the one configured as entityId in your securityContext.xml. It is possible to provide relayState data sent to your SP with parameter RelayState.