This guide describes how to use Spring Security SAML to add support for Okta (via SAML) to Java applications that use the Spring framework.

In this guide, you will learn how to install and configure an Okta SAML application

This guide assumes that you are familiar with the basics of Java software development: editing text files, using the command line, and running Tomcat, Maven or Gradle.

If you’re already familiar with Okta and Spring, you can skip to the section titled “Configuring Spring Security SAML to work with Okta”.

Please make sure the following are installed before starting installation:

Java 1.6+ SDK - Check using the command below

java -version

Apache Maven - Check using the command below

mvn --version

This section covers what you need to do to install and configure Tomcat from scratch on Mac OS X. If you already have Tomcat on your system, you can skip to Step 2 below.

How to install the Spring Security SAML sample Okta application on Mac OS X:

1. Installing Tomcat

   • If it’s not already installed, install Tomcat with Homebrew using these directions: http://blog.bolshchikov.net/post/50277857673/installing-tomcat-on-macos-with-homebrew

2. Downloading the Spring SAML Extension

   • Use 'git clone' to clone the extention locally

   git clone https://github.com/spring-projects/spring-security-saml.git
   

3. Downloading sample application

   • Use 'git clone' to clone this repository locally

   git clone https://github.com/nshobayo/okta-SpringSAML.git
   

   • Use the command below to copy the sample Okta application into the Extension's "src" folder

   rm -rf spring-security-saml/sample/src/main
   cp -r okta-SpringSAML/src/main spring-security-saml/sample/src

4. Compilation

   • Make sure your working directory is the sample subdirectory of the spring-security-saml directory

   cd spring-security-saml/sample
   

   • To compile

   ../gradlew build install

   This task compiles, tests, and assembles the code into a .war file.

   A succesful build should look something like this

   • Your compiled war archive file, spring-security-SAML2-sample.war, can be found in directory build/libs/

5. Deployment

   • Assuming your current directory is spring-security-saml/sample Use the command below to copy the compiled spring-security-SAML2-sample.war file to the Tomcat directory you set up in step one

   cp build/libs/spring-security-SAML2-sample.war /Library/Tomcat/webapps/

6. Starting Tomcat

   • Use the command below to start Tomcat

   /Library/Tomcat/bin/startup.sh

7. Starting Application

   • Load the Spring SAML application by opening this Link: Sample App
   • Note :Links on app will not be functional as of yet because we have not yet configured any IDPs. Full app functionality will be completed after the "Configuring Spring Security SAML to work with Okta" section.

   Here's what it should look like:

   

1. Follow the directions under the "Configuring Okta to work with Spring Security SAML" at : http://developer.okta.com/docs/guides/spring_security_saml.html#configuring-okta-to-work-with-spring-security-SAML

   • ** STEP 7.a ** Attributes of the user to be sent in each SAML assertion can be added under "Attribute Statements" during this step if desired. Theses attribute values can be derived and used from the SP side.

   • Example of the attributes First Name, Last Name and Email being added can be found below:

1. Follow the directions under the "Configuring Spring Security SAML to work with Okta" at : http://developer.okta.com/docs/guides/spring_security_saml.html#configuring-spring-security-SAML-to-work-with-okta

#Testing#

Now that you’ve set up an application in Okta and configured the Spring Security SAML example application to use that application, you’re ready to test it out.

There are two ways to test a SAML application: Starting from the Spring application (“SP initiated”) and starting from Okta (“IdP initiated”). You will be testing both methods. In both cases, you will know of the test worked when you see a screen that looks like the one below:

1. Login from the Spring Security SAML sample application (this is know as an "SP initiated" login)

   • Open the sample application in your browser: http://localhost:8080/spring-security-saml2-sample
   • Select Okta
   • Click the “Start single sign-on” button.

2. Login from Okta (This is known as an “IdP initiated” login)

   • Log in to your Okta organization

   • Click the button for the application you created in the “Configuring Okta to work with Spring Security SAML” section above: Spring Security SAML

   

If you’re able to get to the “Authenticated User” page using both of the methods above, then you’re done.

Congratulations on getting Okta working with Spring.

#Next Steps

At this point you should be familiar with setting up SAML enabled application to work with an Okta organization and how to configure Spring Security SAML to work with Okta.

After you have Okta working with the example Spring Security SAML application, the next step is to take the example code and move it to your production application. The specifics of how this works is different depending on how your application is set up. Pay special attention to the securityContext.xml which allows you to add more IDPs to the app as well as control page redirects. Before any changes are made to the securityContext.xml file, you should consider reading the Spring Security SAML reference documents which provides a detailed overview of all the components and features of Spring Security SAML.

If you want to learn more about configuring in SAML and what to consider when writing a SAML application, Okta's in-depth SAML guidance is great place to learn more.