Docs

Java Spring MVC

View on Github

Java Spring MVC

Gravatar for jim.anderson@auth0.com
By Jim Anderson

This tutorial demonstrates how to add user login to a Java Spring MVC application. We recommend you to Log in to follow this quickstart with examples configured for your account.

I want to explore a sample app

2 minutes

Get a sample configured with your account settings or check it out on Github.

View on Github
System requirements: Java 7 and up | Gradle 3.3 and up | Spring Boot 1.5.3 or above

New to Auth? Learn How Auth0 works, how it integrates with Regular Web Applications and which protocol it uses.

Configure Auth0

Get Your Application Keys

When you signed up for Auth0, a new application was created for you, or you could have created a new one.

You will need some details about that application to communicate with Auth0. You can get these details from the Application Settings section in the Auth0 dashboard.

You need the following information:

  • Domain
  • Client ID
  • Client Secret

If you download the sample from the top of this page these details are filled out for you.

If you have more than one application in your account, the sample comes with the values for your Default App.

App Dashboard

Configure Callback URLs

A callback URL is a URL in your application where Auth0 redirects the user after they have authenticated.

The callback URL for your app must be whitelisted in the Allowed Callback URLs field in your Application Settings. If this field is not set, users will be unable to log in to the application and will get an error.

If you are following along with the sample project you downloaded from the top of this page, the callback URL you need to whitelist in the Allowed Callback URLs field is http://localhost:3000/callback.

Configure Logout URLs

A logout URL is a URL in your application that Auth0 can return to after the user has been logged out of the authorization server. This is specified in the returnTo query parameter.

The logout URL for your app must be whitelisted in the Allowed Logout URLs field in your Application Settings. If this field is not set, users will be unable to log out from the application and will get an error.

If you are following along with the sample project you downloaded from the top of this page, the logout URL you need to whitelist in the Allowed Logout URLs field is http://localhost:3000.

Configure Spring to Use Auth0

Setup Dependencies

You will need to add the following dependencies to your Spring project:

You also need to add a Servlet Container as a dependency. You can refer to the sample application to see an example using Apache Tomcat.

If you are using Gradle, update your build.gradle file to include:

compile 'org.springframework.boot:spring-boot-starter-web:1.5.+'
compile 'com.auth0:mvc-auth-commons:1.+'

If you are using Maven, update your pom.xml to include:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
  <version>[1.5, 2.0)</version>
</dependency>
<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>mvc-auth-commons</artifactId>
  <version>[1.0, 2.0)</version>
</dependency>

Configure your Java Spring App

Your Spring application needs some information about your Auth0 Application in order for users to login. The sample stores this information in the src/main/resources/auth0.properties file. The required information is:

com.auth0.domain: YOUR_DOMAIN
com.auth0.clientId: YOUR_CLIENT_ID
com.auth0.clientSecret: YOUR_CLIENT_SECRET

Check populated attributes

If you download the sample using the Download Sample button, the domain, clientId and clientSecret attributes will be populated for you. You should verify that the values are correct, especially if you have multiple Auth0 Applications.

Project Structure

The Login project sample has the following structure:

- src
-- main
---- java
------ com
-------- auth0
---------- example
------------ App.java
------------ AppConfig.java
------------ Auth0Filter.java
------------ AuthController.java
------------ CallbackController.java
------------ ErrorController.java
------------ HomeController.java
------------ LoginController.java
------------ LogoutController.java
---- resources
------ application.properties
------ auth0.properties
---- webapp
------ WEB-INF
-------- jsp
---------- home.jsp
- build.gradle

The project contains a single JSP: the home.jsp which will display the tokens associated with the user after a successful login and provide the option to logout.

The project contains a Filter: the Auth0Filter.java which will check for existing tokens before giving the user access to our protected /portal/* path. If the tokens don't exist, the request will be redirected to the LoginController. This Filter is set on the AppConfig.java class.

The project contains also five Controllers:

  • LoginController.java: Invoked when the user attempts to log in. The controller uses the client_id and domain parameters to create a valid Authorize URL and redirects the user there.
  • CallbackController.java: The controller captures requests to our Callback URL and processes the data to obtain the credentials. After a successful login, the credentials are then saved to the request's HttpSession.
  • HomeController.java: The controller reads the previously saved tokens and shows them on the home.jsp resource.
  • LogoutController.java: Invoked when the user clicks the logout link. The controller invalidates the user session and redirects the user to the login page, handled by the LoginController.
  • ErrorController.java: The controller triggers upon any non-handled exception and redirects the user to the /login path.

Lastly, the project defines a helper class: the AuthController.java which will be in charge of creating new instances of AuthenticationController. By defining it as a Spring Component, the framework will handle its creation.

Trigger Authentication

Let's begin by making your Auth0 credentials available on the App. In the AppConfig class, we tell Spring to map the properties defined in the auth0.properties file to the corresponding fields by using the @Configuration and @Value annotations. We also define the class as a @Component so we can later autowire it to make it available on other classes:

// src/main/java/com/auth0/example/AppConfig.java

@Component
@Configuration
public class AppConfig {
    @Value(value = "${com.auth0.domain}")
    private String domain;

    @Value(value = "${com.auth0.clientId}")
    private String clientId;

    @Value(value = "${com.auth0.clientSecret}")
    private String clientSecret;
}

Create a Component that will generate the Authorize URLs and handle the callback request to obtain the tokens for the authenticated user.

  • If your Auth0 Application is configured to use the RS256 signing algorithm (the default when creating a new Auth0 Application), you need to configure a JwkProvider to fetch the public key used to verify the token's signature. See the jwks-rsa-java repository to learn about additional configuration options.
  • If your Auth0 Application is configured to use the HS256 signing algorithm, there is no need to configure the JwkProvider.

To learn more about the available signing algorithms, refer to the documentation.

The sample below hows to configure the AuthenticationController for use with the RS256 signing algorithm:

// src/main/java/com/auth0/example/AuthController.java

@Component
public class AuthController {
    private final AuthenticationController controller;

    @Autowired
    public AuthController(AppConfig config) {
        JwkProvider jwkProvider = new JwkProviderBuilder(config.getDomain()).build();
        controller = AuthenticationController.newBuilder(config.getDomain(), config.getClientId(), config.getClientSecret())
                .withJwkProvider(jwkProvider)
                .build();
    }

    public Tokens handle(HttpServletRequest request) throws IdentityVerificationException {
        return controller.handle(request);
    }

    public String buildAuthorizeUrl(HttpServletRequest request, String redirectUri) {
        return controller.buildAuthorizeUrl(request, redirectUri)
                .build();
    }
}

To enable users to login, your application will redirect them to the Universal Login page. Using the AuthenticationController instance, you can generate the redirect URL by calling the buildAuthorizeUrl(HttpServletRequest request, String redirectUrl) method. The redirect URL must be the URL that was added to the Allowed Callback URLs of your Auth0 Application.

// src/main/java/com/auth0/example/LoginController.java

@RequestMapping(value = "/login", method = RequestMethod.GET)
protected String login(final HttpServletRequest req) {
    String redirectUrl = req.getScheme() + "://" + req.getServerName() + ":" + req.getServerPort() + "/callback";
    String authorizeUrl = controller.buildAuthorizeUrl(req, redirectUrl);
    return "redirect:" + authorizeUrl;
}

After the user logs in, the result will be received in our CallbackController via either a GET or POST HTTP request. Because we are using the Authorization Code Flow (the default), a GET request will be sent. If you have configured the library for the Implicit Flow, a POST request will be sent instead.

The request holds the call context that the library previously set by generating the Authorize URL with the controller. When passed to the controller, you get back either a valid Tokens instance or an Exception indicating what went wrong. In the case of a successful call, you need to save the credentials somewhere to access them later. You can use the HttpSession of the request by using the SessionsUtils class included in the library.

// src/main/java/com/auth0/example/CallbackController.java

@RequestMapping(value = "/callback", method = RequestMethod.GET)
protected void getCallback(final HttpServletRequest req, final HttpServletResponse res) throws ServletException, IOException {
  try {
      Tokens tokens = controller.handle(req);
      SessionUtils.set(req, "accessToken", tokens.getAccessToken());
      SessionUtils.set(req, "idToken", tokens.getIdToken());
      res.sendRedirect("/portal/home");
  } catch (IdentityVerificationException e) {
      res.sendRedirect("/login");
  }
}

It it's recommended to store the time in which we requested the tokens and the received expiresIn value, so that the next time when we are going to use the token we can check if it has already expired or if it's still valid. For the sake of this sample, we will skip that validation.

Display the Home Page

Now that the user is authenticated (the tokens exists), the Auth0Filter will allow them to access our protected resources. In the HomeController we obtain the tokens from the request's session and set them as the userId attribute so they can be used from the JSP code:

// src/main/java/com/auth0/example/HomeController.java

@RequestMapping(value = "/portal/home", method = RequestMethod.GET)
protected String home(final Map<String, Object> model, final HttpServletRequest req) {
    String accessToken = (String) SessionUtils.get(req, "accessToken");
    String idToken = (String) SessionUtils.get(req, "idToken");
    if (accessToken != null) {
        model.put("userId", accessToken);
    } else if (idToken != null) {
        model.put("userId", idToken);
    }
    return "home";
}

Handle Logout

To properly handle logout, we need to clear the session and log the user out of Auth0. This is handled in the LogoutController of our sample application.

First, we clear the session by calling request.getSession().invalidate(). We then construct the logout URL, being sure to include the returnTo query parameter, which is where the user will be redirected to after logging out. Finally, we redirect the response to our logout URL.

// src/main/java/com/auth0/example/LogoutController.java

@RequestMapping(value = "/logout", method = RequestMethod.GET)
protected String logout(final HttpServletRequest req) {
    invalidateSession(req);

    String returnTo = req.getScheme() + "://" + req.getServerName() + ":" + req.getServerPort();

    // Build logout URL like:
    // https://{YOUR-DOMAIN}/v2/logout?client_id={YOUR-CLIENT-ID}&returnTo=http://localhost:3000
    String logoutUrl = String.format("https://%s/v2/logout?client_id=%s&returnTo=%s", domain, clientId, returnTo);
    
    return "redirect:" + logoutUrl;
}

private void invalidateSession(HttpServletRequest request) {
    if (request.getSession() != null) {
        request.getSession().invalidate();
    }
}

Run the Sample

To run the sample from a terminal, change the directory to the root folder of the project and execute the following line:

./gradlew clean bootRun

If you are using a Windows environment, execute gradlew clean appRun

After a few seconds, the application will be accessible on http://localhost:3000/. Try to access the protected resource http://localhost:3000/portal/home and note how you're redirected by the Auth0Filter to the Auth0 Login Page. The widget displays all the social and database connections that you have defined for this application in the dashboard.

Login using Lock

After a successful authentication, you'll be able to see the home page contents.

Display Token

Log out by clicking the Logout button at the top right of the home page.

Use Auth0 for FREE