12. Integrating Identity Providers

Section provides additional information regarding integration of Spring SAML with popular Identity Providers.

12.1 Active Directory Federation Services 2.0 (AD FS)

AD FS 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)

12.1.1 Initialize IDP metadata

  • Download AD FS 2.0 metadata from e.g. https://adfsserver/FederationMetadata/2007-06/FederationMetadata.xml

  • Store the downloaded content to sample/src/main/resources/metadata/FederationMetadata.xml

  • Modify bean metadata in sample/src/main/webapp/WEB-INF/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.ResourceBackedMetadataProvider">
    			<constructor-arg>
    				<bean class="java.util.Timer"/>
    			</constructor-arg>
    			<constructor-arg>
    				<bean class="org.opensaml.util.resource.ClasspathResource">
    					<constructor-arg value="/metadata/FederationMetadata.xml"/>
    				</bean>
    			</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>

12.1.2 Initialize SP metadata

  • Deploy SAML 2 Extension war archive from sample/target/spring-security-saml2-sample.war, or use embedded Tomcat with command: mvn tomcat7:run

  • Open Spring SAML in browser, e.g. at https://localhost:8443/spring-security-saml2-sample, making sure to use HTTPS protocol

  • Click Metadata Administration, login and select item with your server name from 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 the metadata.xml file created earlier. Select Next

  • The wizard 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 endpoint values. If not, verify that your metadata was generated with HTTPS protocol 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 "SAM-Account-Name" as LDAP Attribute and "Name ID" as "Outgoing claim type", finish the wizard and confirm the claim rules window, in ADFS 3.0 you might need to configure the Name ID as a Pass Through claim

  • Open the provider by double-clicking it, select tab Advanced and change "Secure hash algorithm" to SHA-1

12.1.3 Test SSO

Open the Spring SAML sample application at e.g. 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, import it to your samlKeystore.jks by following instructions in the error report.

12.2 Okta

Okta supports single sign-on to customer specified SAML 2.0 Service Provider applications, such as Spring SAML Extension. Before starting with the configuration make sure that the following pre-requisites are satisfied:

  • Have an Okta instance and administration account ready, Okta license must allow you to add custom applications

  • Install a Java container (e.g. Tomcat) for deployment of the SAML 2 Extension

12.2.1 Deploy Spring SAML sample application

  • Deploy SAML 2 Extension war archive from sample/target/spring-security-saml2-sample.war, or use embedded Tomcat with command: mvn tomcat7:run

  • Open Spring SAML in browser, e.g. at http://localhost:8080/spring-security-saml2-sample

  • Click Metadata Administration, login and select item with your server name from the Service providers

  • Note the Entity ID field, and Assertion Consumer Service URL (ACS) from the metadata XML, e.g. http://localhost:8080/spring-security-saml2-sample/saml/SSO

Information such as entity ID and URLs of your Spring SAML can be customized, see Section 7.1, “Service provider metadata” for details.

12.2.2 Configure Okta

  • Login to Okta as an administrator, select Admin, select Applications and click Create New App

  • From the list of supported protocols select SAML 2.0 and press Create

  • Define app name (e.g. Spring SAML), optionally define app image and press Next

  • Configure SAML with the following settings:

    Table 12.1. 

    Single Sign on URLUse value noted during Spring SAML initialization, e.g. http://localhost:8080/spring-security-saml2-sample/saml/SSO
    Audience URI (SP Entity ID)Use value noted during Spring SAML initialization, e.g. http://localhost:8080/spring-security-saml2-sample/saml/metadata
    Default RelayStateLeave empty, unless you require Okta to provide a value to Spring SAML
    Name ID formatSelect any of the available options, depending on your requirements
    Application usernameSelect any of the available options, depending on your requirements
    Response (advanced settings)Select "signed"
    Assertion (advanced settings)Select "signed"
    Authentication context class (advanced settings)Select any of the available options
    Request compression (advanced settings)Select "Uncompressed"


  • Optionally define attributes to be sent to Spring SAML after single sign-on, and press Next

  • On Feedback page select "This is an internal application that we created" and press Finish

  • Make sure to distribute the newly created application to users you want to use for testing

12.2.3 Import Okta metadata to Spring SAML

  • In Okta click link "Identity provider metadata" and store the downloaded content to sample/src/main/resources/metadata/okta.xml

  • In Spring SAML modify bean metadata in sample/src/main/webapp/WEB-INF/securityContext.xml and replace classpath:security/idp.xml with classpath:security/okta.xml:

    <bean class="org.springframework.security.saml.metadata.ExtendedMetadataDelegate">
        <constructor-arg>
            <bean class="org.opensaml.saml2.metadata.provider.ResourceBackedMetadataProvider">
                <constructor-arg>
                    <bean class="java.util.Timer"/>
                </constructor-arg>
                <constructor-arg>
                    <bean class="org.opensaml.util.resource.ClasspathResource">
                        <constructor-arg value="/metadata/okta.xml"/>
                    </bean>
                </constructor-arg>
                <property name="parserPool" ref="parserPool"/>
            </bean>
        </constructor-arg>
        <constructor-arg>
            <bean class="org.springframework.security.saml.metadata.ExtendedMetadata"/>
        </constructor-arg>
    </bean>

  • Restart Spring SAML for the changes to get applied

12.2.4 Test SSO

Open the Spring SAML sample application at e.g. http://localhost:8080/spring-security-saml2-sample, select your Okta server and press login. Alternatively start IDP-initialized single sign-on using App Embed Link provided by Okta in application configuration, e.g. https://v7security.okta.com/home/v7security_springsaml_1/0oa4vkeakAsUtZ8AI0y6/39139.