auth0-java-mvc-common: A Java repository from OpenGov

Note As part of our ongoing commitment to best security practices, we have rotated the signing keys used to sign previous releases of this SDK. As a result, new patch builds have been released using the new signing key. Please upgrade at your earliest convenience.

While this change won't affect most developers, if you have implemented a dependency signature validation step in your build process, you may notice a warning that past releases can't be verified. This is expected, and a result of the key rotation process. Updating to the latest version will resolve this for you.

📚 Documentation - 🚀 Getting Started - 💻 API Reference 💬 Feedback

Documentation

Quickstart - our interactive guide for quickly adding login, logout and user information to a Java Servlet application using Auth0.
Sample App - a sample Java Servlet application integrated with Auth0.
Examples - code samples for common scenarios.
Docs site - explore our docs site and learn more about Auth0.

Getting Started

Requirements

Java 8 or above and javax.servlet version 3.

If you are using Spring, we recommend leveraging Spring's OIDC and OAuth2 support, as demonstrated by the Spring Boot Quickstart.

Installation

Add the dependency via Maven:

<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>mvc-auth-commons</artifactId>
  <version>1.11.0</version>
</dependency>

or Gradle:

implementation 'com.auth0:mvc-auth-commons:1.11.0'

Configure Auth0

Create a Regular Web Application in the Auth0 Dashboard. Verify that the "Token Endpoint Authentication Method" is set to POST.

Next, configure the callback and logout URLs for your application under the "Application URIs" section of the "Settings" page:

Allowed Callback URLs: The URL of your application where Auth0 will redirect to during authentication, e.g., http://localhost:3000/callback.
Allowed Logout URLs: The URL of your application where Auth0 will redirect to after user logout, e.g., http://localhost:3000/login.

Note the Domain, Client ID, and Client Secret. These values will be used later.

Add login to your application

Create a new AuthenticationController using your Auth0 domain, and Auth0 application client ID and secret. Configure the builder with a JwkProvider for your Auth0 domain.

public class AuthenticationControllerProvider {
    private String domain = "YOUR-AUTH0-DOMAIN";
    private String clientId = "YOUR-CLIENT-ID";
    private String clientSecret = "YOUR-CLIENT-SECRET";
    
    private AuthenticationController authenticationController;
    
    static {
        JwkProvider jwkProvider = new JwkProviderBuilder("YOUR-AUTH0-DOMAIN").build();
        authenticationController = AuthenticationController.newBuilder(domain, clientId, clientSecret)
                .withJwkProvider(jwkProvider)
                .build();
    }
    
    public getInstance() {
        return authenticationController;
    }
}

Note: The AuthenticationController.Builder is not to be reused, and an IllegalStateException will be thrown if build() is called more than once.

Redirect users to the Auth0 login page using the AuthenticationController:

@WebServlet(urlPatterns = {"/login"})
public class LoginServlet extends HttpServlet {

    @Override
    protected void doGet(final HttpServletRequest req, final HttpServletResponse res) throws ServletException, IOException {
        // Where your application will handle the authoriztion callback
        String redirectUrl = "http://localhost:3000/callback";

        String authorizeUrl = AuthenticationControllerProvider
                .getInstance()
                .buildAuthorizeUrl(req, res, redirectUrl)
                .build();
        res.sendRedirect(authorizeUrl);
    }
}

Finally, complete the authentication and obtain the tokens by calling handle() on the AuthenticationController.

@WebServlet(urlPatterns = {"/callback"})
public class CallbackServlet extends HttpServlet {
    
    @Override
    public void doGet(HttpServletRequest req, HttpServletResponse res) throws IOException, ServletException {
        try {
            // authentication complete; the tokens can be stored as needed
            Tokens tokens = AuthenticationControllerProvider
                    .getInstance()
                    .handle(req, res);
            res.sendRedirect("URL-AFTER-AUTHENTICATED");
        } catch (IdentityVerificationException e) {
            // handle authentication error
        }
    }
}

That's it! You have authenticated the user using Auth0.

API Reference

JavaDocs

Feedback

Contributing

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

Raise an issue

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting

Please do not report security vulnerabilities on the public Github issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Auth0 Logo

Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout Why Auth0?

This project is licensed under the MIT license. See the LICENSE file for more info.

OpenGov/auth0-java-mvc-common