On this page
Spring Security SAML
This guide describes how to use Spring Security SAML to add support for Okta (through SAML) to Java applications that use the Spring framework. In this guide, you 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 Configure Spring Security SAML to work with Okta section.
Note: The Spring Security SAML toolkit that you download isn't an Okta toolkit and isn't supported by Okta.
Requirements
Make sure that the following are installed before starting installation:
Java 1.6+ SDK (opens new window)
Check using the following command:
java -version
Apache Maven (opens new window)
Check using the following command:
mvn --version
Installation
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 the Download the Spring SAML Extension step.
How to install the Spring Security SAML sample Okta application on Mac OS X:
1. Install Tomcat
If it's not already installed, install Tomcat with Homebrew using these directions (opens new window).
2. Download the Spring SAML Extension
Use git clone
to clone the extention locally:
git clone https://github.com/spring-projects/spring-security-saml.git
3. Download the sample application
Use git clone
to clone this repository locally:
git clone https://github.com/nshobayo/okta-SpringSAML.git
Use this command 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. Compile
Make sure that 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 successful build should look something like this:
You can find your compiled WAR archive file (spring-security-SAML2-sample.war
) in the build/libs/
directory.
5. Deploy
Assuming that your current directory is spring-security-saml/sample
, use the following command to copy the compiled spring-security-SAML2-sample.war
file to the Tomcat directory that you set up in step one:
cp build/libs/spring-security-SAML2-sample.war /Library/Tomcat/webapps/
6. Start Tomcat
Use the following command to start Tomcat:
/Library/Tomcat/bin/startup.sh
7. Start the Application
Load the Spring SAML application by opening this link: http://localhost:8080/spring-security-saml2-sample/saml/discovery?entityID=http%3A%2F%2Flocalhost%3A8080%2Fspring-security-saml2-sample%2Fsaml%2Fmetadata&returnIDParam=idp
Note: Links in the app aren't functional yet because we haven't configured any IDPs. Full app functionality is completed after the Configure Spring Security SAML to work with Okta section.
Here's what it should look like:
Configure Okta to work with Spring Security SAML
Before we can configure Spring Security SAML, we need to set up an application in Okta that connects to Spring Security SAML.
In SAML terminology, what we are doing here is configuring Okta, which is our SAML Identity Provider (SAML IdP), with the details of Spring Security SAML that is the new SAML Service Provider (SAML SP) that you create next.
Here is how to configure Okta:
1. Sign in to your Okta organization as a user with administrative privileges. If you don't have an Okta organization, you can create a free Okta Developer Edition organization (opens new window).
2. Click Admin to open the Admin Console. Go to Applications > Applications.
3. Click Create App Integration.
4. In the dialog that appears, select SAML 2.0, and then click Next.
5. In the General Settings section, enter Spring Security SAML in the App name box, and then click Next.
6. In the Configure SAML section, paste the following URL into the Single sign on URL box:
http://localhost:8080/spring-security-saml2-sample/saml/SSO
7. Then paste the following URL into the Audience URI (SP Entity ID) box:
http://localhost:8080/spring-security-saml2-sample/saml/metadata
You can add user attributes sent in each SAML assertion under Attribute Statements during this step, if desired. You can derive these attribute values and use them from the service provider side.
8. Click Next.
9. In the Feedback section, select the This is an internal application that we created checkbox and click Finish.
The Sign On section of your newly created Spring Security SAML application appears.
10. Copy the Identity Provider metadata link by right-clicking the Identity Provider metadata link and selecting Copy. You need this link later.
11. Right-click the People section of the Spring Security SAML application and select Open Link In New Tab (so that you can come back to the Sign On section later).
12. In the new tab that opens, click Assign Application.
13. The Assign Spring Security SAML to up to 500 people dialog appears. Enter your username into the search box, select the checkbox next to your username, and then click Next.
14. You are prompted to enter user-specific attributes. Click Confirm Assignments to keep the defaults.
Configure Spring Security SAML to work with Okta
Now that you have configured a Spring Security SAML application, you are ready to configure Spring Security SAML to work with Okta. In this section we use the Identity Provider metadata link that you copied in the last section to configure Spring Security SAML. After you've completed these steps, you have a working example of connecting Okta to Spring.
Open the
securityContext.xml
file in your favorite text editor. If you followed the instructions in the last section for "Installing the Spring Security SAML sample application" on Mac OS X, this file is located at/Library/Tomcat/webapps/spring-security-saml2-sample/WEB-INF/securityContext.xml
. (Normally, you would do this step before running Maven or Gradle to create the WAR file that you deploy to Tomcat. In this case, I'm having you edit the file in the Tomcat path directly, since it's easier to make small changes and test them this way).AFter you open the
securityContext.xml
file, add the following XML to the end of the tag identified by this CSS selector syntax:
#metadata > constructor-arg > list
<bean class="org.opensaml.saml2.metadata.provider.HTTPMetadataProvider">
<!-- URL containing the metadata -->
<constructor-arg>
<!-- This URL should look something like this: https://${yourOktaDomain}/app/abc0defghijK1lmN23o4/sso/saml/metadata -->
<value type="java.lang.String">${metadataUrl}</value>
</constructor-arg>
<!-- Timeout for metadata loading in ms -->
<constructor-arg>
<value type="int">5000</value>
</constructor-arg>
<property name="parserPool" ref="parserPool"/>
</bean>
Be sure to replace the contents of
${metadataUrl}
with the link that you copied in step 11 of the Configure Okta to work with Spring Security SAML (opens new window) section.Save the
securityContext.xml
file, and then restart Tomcat. If you are using Mac OS X, you can restart Tomcat using the following commands:
/Library/Tomcat/bin/shutdown.sh
/Library/Tomcat/bin/startup.sh
Test the SAML integration
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 test both methods. In both cases, you know if the test worked when you see a screen that looks like the following:
- Sign in from the Spring Security SAML sample application (This is known as an "SP-initiated" sign-in flow).
-Open the sample application in your browser:
http://localhost:8080/spring-security-saml2-sample
-Select the Okta IdP from the list. It is a URL that starts with: http://www.okta.com/
.
-Click Start single sign-on.
- Sign in from Okta (This is known as an "IdP-initiated" sign-in flow).
-Sign in to your Okta organization.
-Click the button for the application that you created in the Configure Okta to work with Spring Security SAML section.
If you're able to access the Authenticated User page using both of these methods, 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 applications 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
that 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 (opens new window) that provide a detailed overview of all the components and features of Spring Security SAML.
If you want to learn more about configuring SAML and what to consider when writing a SAML application, see the in-depth Okta SAML guidance (opens new window) documentation, which is great place to learn more.