Java Spring Security Introduction

This multistep quickstart guide will walk you through the process of managing authentication in your Java Spring Security Web Application with Auth0.

System Requirements

These tutorials and seed projects have been tested with the following:

  • Java 7 or above
  • Maven 3.0.x or above

Auth0 provides and manages a Spring Security MVC SDK. This SDK allows you to use Auth0 with Java for server-side Spring Security web apps, leveraging Spring Boot dependencies.

You can find a listing of all our Java offerings and several sample projects in Java technologies and Auth0 libraries.

Sample Projects

There are two options to follow along with this quickstart. You can either download the seed project or the samples provided at each page of this quickstart.

The seed project is a regular Java Spring Security app, with all the Auth0 dependencies set, but nothing more. It's an empty canvas meant to be filled as you follow the steps of this quickstart. If you prefer this option download the seed from our GitHub repository and follow along.

Instead, you can choose to follow the samples that are included in each step. Each sample uses the seed project as a starting point and builds on it, according to the configuration of each step. For example, the Login sample would be the seed project plus the configuration required to implement login functionality. If you choose to follow this approach continue reading, the rest of this document will guide you through setting up the required prerequisites.

Seed project Structure

Let's take some time and explain how our seed project is structured.

- src
-- main
---- java
------ com
-------- auth0
---------- example
---- resources
---- webapp
------ WEB-INF
-------- jsp
---------- home.jsp
---------- login.jsp
-------- web.xml
- pom.xml

The project contains two JSP: the login.jsp that will handle the user login, and the home.jsp which will display user information after a successful login and provide the option to log out.

The project contains also the following files:

  • The configuration file that holds information such as the port your app will use, the logging level, etc.
  • The configuration file that holds Auth0 related information, like the client id, client secret, etc. You can find more detailed information in the Configure your Java Spring app section of this document.
  • A Java class that uses Spring Boot’s method to launch the application.
  • The security configuration class. By subclassing, and overriding authorizeRequests method, you can define the endpoint security configuration (authentication and authorization) suitable for your own needs.
  • The controller that handles the errors.
  • The controller that handles landing page requests.
  • The controller that handles the login.
  • The controller that handles the logouts.

Create a Client

Fetch your credentials (Domain, Client ID, and Client Secret) from your dashboard and store them somewhere safe. You will need them while configuring your application. The sample is configured with your `Default App` credentials if you prefer to start with having a look at it.

Make sure that your Auth0 Client has one or more connections configured, for example, Google Social Connection, or username-password DB connection.

Client Dashboard

Configure Callback URLs

Callback URLs are URLs that Auth0 invokes after the authentication process. Auth0 routes your application back to this URL and attaches some details to it including a token. Callback URLs can be manipulated on the fly and that could be harmful. For security reasons, you will need to add your application's URL in the client's Allowed Callback URLs. This will enable Auth0 to recognize the URLs as valid. If omitted, authentication will not be successful for the app instance.

Callback error

If you follow our seed project or the samples based on it, the values you must configure are:

  • Allowed Callback URL: http://localhost:3099/callback
  • Allowed Logout URLs: http://localhost:3099/logout

Setup Dependencies

To integrate your Spring Security application with Auth0 you need to have the following dependencies set:

  • auth0-spring-security-mvc: is the Java library that allows you to use Auth0 with Spring Security for server-side MVC web apps. It validates the JWT from Auth0 in every API call to assert authentication according to configuration.

If you are using maven, add the dependency to your pom.xml:


If you are using Gradle, add it to the dependencies block:

dependencies {
   * Existing dependencies
  compile 'com.auth0:auth0-spring-security-mvc:1.2.3'

Configure your Spring Security App

Your Spring Security app needs some information in order to authenticate against your Auth0 account. We have created a file for you but you need to update some of the entries with the valid values for your Client. The file is /src/main/resources/ and it contains the following:

auth0.domain: YOUR_AUTH0_DOMAIN
auth0.issuer: https://YOUR_AUTH0_DOMAIN/
auth0.clientId: YOUR_CLIENT_ID
auth0.clientSecret: YOUR_CLIENT_SECRET
auth0.onLogoutRedirectTo: /login
auth0.securedRoute: /portal/*
auth0.loginCallback: /callback
auth0.loginRedirectOnSuccess: /portal/home
auth0.loginRedirectOnFail: /login
auth0.base64EncodedSecret: false
auth0.authorityStrategy: ROLES
auth0.servletFilterEnabled: false
auth0.defaultAuth0WebSecurityEnabled: false
auth0.connection: {CONNECTION}
auth0.customLogin: false
#auth0.customLogin: true
auth0.signingAlgorithm: HS256
#auth0.signingAlgorithm: RS256
#auth0.publicKeyPath: /WEB-INF/certificate/cert.pem

Let's see what each attribute means.

Attribute Description
auth0.domain Your auth0 domain. You can find the correct value on the Settings tab of your client on the dashboard. *
auth0.issuer The issuer of the JWT Token. This is typically your auth0 domain with a https:// prefix and a / suffix. For example, if your auth0.domain is then the auth0.issuer should be set to (the trailing slash is important).
auth0.clientId The unique identifier for your client. You can find the correct value on the Settings tab of your client on the dashboard. *
auth0.clientSecret The secret used to sign and validate the tokens that will be used in the different authentication flows. You can find the correct value on the Settings tab of your client on the dashboard. *
auth0.onLogoutRedirectTo The page that users of your site are redirected to on logout. Should start with /.
auth0.securedRoute The URL pattern that should map to the URL endpoint you wish to secure. You should replace its value with the correct value for your implementation. It should start with /. *
auth0.loginCallback The URL context path for the login callback endpoint. Should start with /.
auth0.loginRedirectOnSuccess The landing page URL context path for a successful authentication. Should start with /.
auth0.loginRedirectOnFail The URL context path for the page to redirect to upon failure. Should start with /.
auth0.base64EncodedSecret A boolean value indicating whether the Secret used to verify the JWT is base64 encoded. The default is false.
auth0.authorityStrategy Indicates whether authorization claims against the Principal shall be GROUPS, ROLES or SCOPE based. The default is ROLES.
auth0.defaultAuth0ApiSecurityEnabled A boolean value that switches having the default config enabled. It should be set to false.
auth0.signingAlgorithm This is signing algorithm to verify signed JWT token. Use HS256 or RS256.
auth0.publicKeyPath Path location to the public key. Should always be set when using RS256 and is ignored for HS256.

Configuration values

If you download the seed using our Download Sample button then the domain, issuer, clientId and clientSecret attributes will be populated for you, unless you are not logged in or you do not have at least one registered client. In any case, you should verify that the values are correct if you have multiple clients in your account and you might want to use another than the one we set the information for. Do not forget to manually set the issuer attribute!

Configure an endpoint by context path

If you are using the default library configuration (not overriding with your own) which just secures a single, specific context path then the auth0.securedRoute value is important. However, if you are building an application which may have several different secured endpoints, or you don't want to specify an explicit configuration value in this .properties file then just set auth0.securedRoute to something that signifies this. Perhaps auth0.securedRoute: UNUSED. Then just ignore the securedRoute entirely when you specify your own configuration. See the section Extending Auth0SecurityConfig for further info. This property value is a convenience for the developer to configure an endpoint by context path (.eg all URLS with /api/v1/ in their context path), but there is no obligation to actually reference this property in your own HttpSecurity configuration.

Sample application

We have created a sample application that demonstrates using Auth0 with Spring Boot and Spring Security to create two traditional server-side MVC web apps that are configured for Single Sign On with one another. The sample application contains two demo websites that have been developed to demonstrate the Auth0 SSO capabilities between a main "portal" website and a Partner website that depends on the main "portal" site for SSO authentication. Fell free to check this out.

You are now ready to continue with the next tutorial in order to implement basic login using Lock!

Next Tutorial
2. Login
Use Auth0 for FREECreate free Account