If you are going to be developing web applications in Java, there is no doubt you are familiar with Spring Boot, a veritable toolbox for developing web applications. The most common method of authenticating users is database authentication, where credentials are stored in a database to identify authorized users that are accessible by the application. A common open standard is SAML, which can be used to handle authentication, specifically between service providers and identity providers.
While configuring SAML auth in Spring Security is common and can be shown in many different examples, like this one from the Okta blog, it can add another layer of difficulty when continuing both database and SAML authentication methods in the same Spring Boot application. This will allow the user to be authenticated both ways, and this tutorial will show you how to find a solution!
Acknowledgment: Much of the groundwork for the implementation of SAML 2.0 authentication used in this project was developed by Vincenzo De Notaris and can be found in this project on GitHub. For this project, some changes have been made to support dual DB + SAML authentication and use Okta as the SAML identity provider rather than SSOCircle.
SAML Authentication With Spring Security
There are several benefits to using SAML to handle authentication for your application:
- Loose coupling between your application and your authentication mechanism increases independence between the two, allowing for more rapid development and evolution of application logic, with less risk of regression
- Shifts the responsibility of authentication, which involves storing and retrieving sensitive user information, to the identity provider (e.g., Okta), which almost always offers less risk since identity management is their business model
- Allows for an improved user experience via Single Sign-On while navigating between multiple apps
Okta is a very well established identity provider with robust features and a wealth of support. Managing users, accounts, and permissions with Okta is simple and straightforward. Simultaneously, it is still flexible and extensible enough to support your application no matter how much it grows (even as it grows into several applications). And the friendly, growing community is available to answer any questions you may have!
You’ll need to create a forever-free Okta developer account to complete this tutorial. If you already have a developer account, you should complete this tutorial by switching to the Classic UI in the top-left corner.
In case you need to support legacy systems or because you have strange security requirements, you may need to allow users to authenticate using either SAML or database credentials. The process to combine SAML 2.0 with DB auth in Spring Boot is what we’ll tackle here!
Set Up Your Okta Account With SAML and Run the Application
Please complete the following ten steps to see a working example.
Step 1: Clone the okta-spring-security-saml-db-example repository:
Step 2: Sign up for a free developer account at https://developer.okta.com/signup. This is required to create SAML 2.0 applications in Okta.
Step 3: Log in to your Okta account at
https://your-okta-domain.okta.com. If you see a developer dashboard like the screenshot below, click on Developer Console in the top left, and select Classic UI.
Step 4: Create a new application via Admin > Applications > Add Application > Create New App with the following settings:
- Sign On Method:
Enter an App name like
Spring Boot DB/SAML (or whatever you’d like). Click Next.
Enter the following SAML Settings:
- Single Sign-On URL:
- Use this for Recipient URL and Destination URL:
- Audience URI:
Select the following two options:
- I’m an Okta customer adding an internal app
- This is an internal app that we have created
Then, click Finish.
Step 5: Navigate to Assignments > Assign to People.
Step 6: Assign to your account with the custom username
Step 7: Navigate to Sign On and copy the following values to your
saml.metadataUrl— Right-click and copy the URL from the Identity Provider metadata link below the View Setup Instructions button.
saml.idp — Click the View Setup Instructions button and copy the value in (2) Identity Provider Issuer.
For example, here are the values I used:
Step 8: Run your Spring Boot application in your IDE or via Maven:
Step 9: Navigate to your application’s home page at
Step 10: For database authentication, log in using
firstname.lastname@example.org / oktaiscool.
You should see a success message saying you’re logged in.
For SAML authentication, sign in using
You should be prompted to select your identity provider.
Then, you should be redirected to the SAML Okta auth flow and returned to your application following successful authentication.
You’re done! You’ve successfully configured your project to support authentication via both the database and SAML 2.0!
It’s nice to see everything working, but what about the code that makes it happen? Keep reading for a walkthrough of the code and how it works.
How to Combine Database and SAML Authentication in Spring Boot
To get a better understanding of how DB and SAML auth are combined in this example, clone the repository for this tutorial if you have not already:
Open the project up in your favorite IDE or editor and take a look at the Maven POM file located at
This application inherits from the
spring-boot-starter-parent parent project. This provides you with Spring Boot’s dependency and plugin management:
This project uses the following Spring Boot Starter dependencies:
spring-boot-starter-webprovides support for building web applications
spring-boot-starter-securityprovides support for securing the application (e.g., Basic Auth, Form Login)
spring-boot-starter-data-jpaprovides support for the Java Persistence API, which is used to communicate with the database for DB authentication
spring-boot-starter-thymeleafprovides support for the Thymeleaf templating engine, a simple and powerful way to create web pages for Spring Boot applications
spring-security-saml2-core extension for Spring Boot provides the necessary SAML-related libraries. This extension depends on the
opensaml library, which is contained in the Shibboleth repository and is added to the
The following dependencies also make life easier:
com.h2database:h2to provide a simple in-memory database
org.projectlombok:lombokto reduce boilerplate code (e.g. getters, setters,
nz.net.ultraq.thymeleaf:thymeleaf-layout-dialect, a useful add-on for formatting Thymeleaf templates
NOTE: Some IDEs have trouble digesting Lombok-ified code due to version and plugin incompatibilities. If you have difficulty compiling this project, consider removing this dependency and adding the missing boilerplate code, or just use Maven to build and run.
The SAML and Database Auth “Pre-Login” Page
You want to have an initial page in which a user enters their username for login. Depending on the username pattern, you either direct the user to a standard username-and-password page for authenticating against the database, or direct them to the SAML auth flow.
IndexController is the backend
@Controller defined to serve this page and handle requests:
IndexController, you are checking whether the username matches a particular pattern and redirecting accordingly.
Authenticate With SAML and Spring Security
WebSecurityConfig class, which extends the
WebSecurityConfigurerAdapter parent, defines much of the security settings, including:
- The filter chains to handle SAML requests and responses
- How and when to authenticate a user with either the database or SAML and Okta
- Required permissions for URLs within the application
- Logging out
When redirected to the
/doSaml endpoint, the SAML flow is initiated by a custom authentication entry point defined in
Here you can see if the requested URL ends with
doSaml, the request is handled by the
SamlEntryPoint defined in your configuration. This redirects the user to authenticate via Okta, and returns the user to
/doSaml upon completion. To handle this redirect, a
Controller is defined to redirect the user following a successful SAML auth:
At this point, the user should be successfully authenticated with the app!
Authenticate With a Database and Spring Security
If the username matches another pattern, the user is redirected to a standard-looking form login page:
The login submission is handled by a
@Controller which calls on the
AuthenticationManager built in
DbAuthProvider is a custom component which performs standard DB authentication by checking the supplied password versus a hashed copy in the database:
The above class calls on
CombinedUserDetailsService which is another custom component providing an appropriate
UserDetails object depending on whether the user is authenticated using the database or SAML, by implementing
@Controller to handle DB authentication looks like this:
doLogin() is called via
AuthenticationManager handles the username and password authentication and redirects the user if successful.
For ease of use, two users are defined in the database: one for DB auth and one for SAML. Both users are defined in our database, but only one of them is authenticated against the database:
Learn More About SAML and Okta
Much of the complexity of this project comes from the need to combine both database and SAML authentication in one app. Normally you would choose one or the other. If you want to use only SAML for authentication (which is a fine idea, especially using Okta), visit this blog post using the standard Spring SAML DSL extension to integrate with Okta and SAML to secure your application.
The source code used in this example is on GitHub.
See a good primer on how SAML works here: What is SAML and How Does it Work?
Please provide comments, questions, and any feedback in the comments section below.
We’re also streaming on Twitch, follow us to be notified when we’re live.