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
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 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.
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.
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">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.
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>
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.
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.
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.
Open the front page of your SP application, select http://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=/ssocircle&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.