Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
;
};
export const sections = [{
id: "system-requirements",
title: "System Requirements"
}, {
id: "configure-auth0",
title: "Configure Auth0"
}, {
id: "configure-java-ee-to-use-auth0",
title: "Configure Java EE to use Auth0"
}, {
id: "configure-java-ee-security",
title: "Configure Java EE Security"
}, {
id: "trigger-authentication",
title: "Trigger authentication"
}, {
id: "display-user-information",
title: "Display user information"
}, {
id: "handle-logout",
title: "Handle logout"
}, {
id: "run-the-sample",
title: "Run the sample"
}];
This tutorial demonstrates how to add user login to a Java EE web application. We recommend that you log in to
follow this quickstart with examples configured for your account.
This tutorial and sample project have been tested with the following:
* Java 11
### 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](https://manage.auth0.com/#/applications) 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.
### 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 added to the **Allowed Callback URLs** field in your [Application
Settings](https://manage.auth0.com/#/applications). 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 add to 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 added to the **Allowed Logout URLs** field in your [Application Settings](https://manage.auth0.com/#/applications). 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 add to the **Allowed Logout URLs** field is `http://localhost:3000/`.
### Set up dependencies
To integrate your Java EE application with Auth0, add the following dependencies:
* **javax.javaee-api**: The Java EE 8 API necessary to write applications using Java EE 8. The actual
implementation is provided by the application container, so it does not need to be included in the WAR file.
* **javax.security.enterprise**: The Java EE 8 Security API that enables handling security concerns in an EE
application. Like the `javax.javaee-api` dependency, the implementation is provided by the
application container, so is not included in the WAR file.
* **auth0-java-mvc-commons**: The [Auth0 Java MVC SDK](https://github.com/auth0/auth0-java-mvc-common) allows you to use Auth0 with Java for server-side MVC web
applications. It generates the Authorize URL that your application needs to call in order to authenticate a
user using Auth0.
If you are using Maven, add these dependencies to your `pom.xml`:
```xml lines
com.auth0mvc-auth-commons[1.0, 2.0)javaxjavaee-api8.0.1providedjavax.security.enterprisejavax.security.enterprise-api1.0provided
```
If you are using Gradle, add them to your `build.gradle`:
```java lines
// build.gradle
providedCompile 'javax:javaee-api:8.0.1'
providedCompile 'javax.security.enterprise:javax.security.enterprise-api:1.0'
implementation 'com.auth0:mvc-auth-commons:1. '
```
### Configure your Java EE application
The sample that accompanies this tutorial is written using JSP and tested with the [WildFly](https://wildfly.org/) application server.
You may need to adjust some of the steps if you working with a different application container or
technologies.
Your Java EE application needs some information in order to authenticate users with your Auth0 application. The
deployment descriptor `web.xml`file can be used to store this information, though you could store them
in a different secured location.
This information will be used to configure the **auth0-java-mvc-commons** library to enable users to login to
your application. To learn more about the library, including its various configuration options, see the [README](https://github.com/auth0/auth0-java-mvc-common/blob/master/README.md) of the library.
The Java EE 8 Security API introduced the `HttpAuthenticationMechanism` interface to enable
applications to obtain a user's credentials. Default implementations exist for Basic and form-based
authentication, and it provides an easy way to configure a custom authentication strategy.
To authenticate with Auth0, provide custom implementations of the following interfaces:
* HttpAuthenticationMechanism: Responsible for handling the authentication workflow for users returning from
Auth0. ([JavaDoc](https://javaee.github.io/javaee-spec/javadocs/javax/security/enterprise/authentication/mechanism/http/HttpAuthenticationMechanism.html)).
* IdentityStore: Responsible for validating the user's credentials ([JavaDoc](https://javaee.github.io/javaee-spec/javadocs/javax/security/enterprise/identitystore/IdentityStore.html)).
* CallerPrincipal: Represents the caller principal of the current HTTP request ([JavaDoc](https://javaee.github.io/javaee-spec/javadocs/javax/security/enterprise/CallerPrincipal.html)).
* Credential: Represents the credential the caller will use to authenticate ([JavaDoc](https://javaee.github.io/javaee-spec/javadocs/javax/security/enterprise/credential/Credential.html)).
First, make your Auth0 settings available to the application by creating an @ApplicationScoped bean to retrieve
the values from the web context and make them available via getters.
Next, create a custom `CallerPrincipal` that represents the caller of the current request:
```java lines
// src/main/java/com/auth0/example/security/Auth0JwtPrincipal.java
public class Auth0JwtPrincipal extends CallerPrincipal {
private final DecodedJWT idToken;
Auth0JwtPrincipal(DecodedJWT idToken) {
super(idToken.getClaim("name").asString());
this.idToken = idToken;
}
public DecodedJWT getIdToken() {
return this.idToken;
}
}
```
You can now implement a custom `Credential` that will be used to represent the user's credentials. It
will hold information about the principal:
```java lines
// src/main/java/com/auth0/example/security/Auth0JwtCredential.java
class Auth0JwtCredential implements Credential {
private Auth0JwtPrincipal auth0JwtPrincipal;
Auth0JwtCredential(String token) {
DecodedJWT decodedJWT = JWT.decode(token);
this.auth0JwtPrincipal = new Auth0JwtPrincipal(decodedJWT);
}
Auth0JwtPrincipal getAuth0JwtPrincipal() {
return auth0JwtPrincipal;
}
}
```
You now have defined the classes that represent a calling principal and credential. Next, create a custom
implementation of `IdentityStore`. This class will be responsible for validating the user's
credentials:
```java lines
// src/main/java/com/auth0/example/security/Auth0JwtIdentityStore.java
@ApplicationScoped
public class Auth0JwtIdentityStore implements IdentityStore {
@Override
public CredentialValidationResult validate(final Credential credential) {
CredentialValidationResult result = CredentialValidationResult.NOT_VALIDATED_RESULT;
if (credential instanceof Auth0JwtCredential) {
Auth0JwtCredential auth0JwtCredential = (Auth0JwtCredential) credential;
result = new CredentialValidationResult(auth0JwtCredential.getAuth0JwtPrincipal());
}
return result;
}
}
```
If the `credential` is an `Auth0Credential`, the calling user is authenticated and valid,
so a `CredentialValidationResult` created with the credential is returned to indicate success. If it is
not an `Auth0Credential`, return `CredentialValidationResult.NOT_VALIDATED_RESULT`.
Before implementing the `HttpAuthenticationMechanism` interface that will use all these collaborators,
create a bean that will provide a configured instance of the `AuthenticationController` from the Auth0
Java MVC SDK. The `AuthenticationController` is used to build the authorization URL where users will
login, and handle the token exchange to authenticate users.
* 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](https://github.com/auth0/jwks-rsa-java) 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](https://auth0.com/docs/tokens/concepts/signing-algorithms).
The sample below shows how to configure the `AuthenticationController` for use with the **RS256
signing algorithm**:
```java lines
// src/main/java/com/auth0/example/security/Auth0AuthenticationProvider.java
@ApplicationScoped
public class Auth0AuthenticationProvider {
@Produces
public AuthenticationController authenticationController(Auth0AuthenticationConfig config) {
JwkProvider jwkProvider = new JwkProviderBuilder(config.getDomain()).build();
return AuthenticationController.newBuilder(config.getDomain(), config.getClientId(), config.getClientSecret())
.withJwkProvider(jwkProvider)
.build();
}
}
```
Finally, implement a custom `HttpAuthenticationMechanism`
\`\`
```java lines expandable
// src/main/java/com/auth0/example/security/Auth0AuthenticationMechanism.java
@ApplicationScoped
@AutoApplySession
public class Auth0AuthenticationMechanism implements HttpAuthenticationMechanism {
private final AuthenticationController authenticationController;
private final IdentityStoreHandler identityStoreHandler;
@Inject
Auth0AuthenticationMechanism(AuthenticationController authenticationController, IdentityStoreHandler identityStoreHandler) {
this.authenticationController = authenticationController;
this.identityStoreHandler = identityStoreHandler;
}
@Override
public AuthenticationStatus validateRequest(HttpServletRequest httpServletRequest,
HttpServletResponse httpServletResponse,
HttpMessageContext httpMessageContext) throws AuthenticationException {
// Exchange the code for the ID token, and notify container of result.
if (isCallbackRequest(httpServletRequest)) {
try {
Tokens tokens = authenticationController.handle(httpServletRequest, httpServletResponse);
Auth0JwtCredential auth0JwtCredential = new Auth0JwtCredential(tokens.getIdToken());
CredentialValidationResult result = identityStoreHandler.validate(auth0JwtCredential);
return httpMessageContext.notifyContainerAboutLogin(result);
} catch (IdentityVerificationException e) {
return httpMessageContext.responseUnauthorized();
}
}
return httpMessageContext.doNothing();
}
private boolean isCallbackRequest(HttpServletRequest request) {
return request.getRequestURI().equals("/callback") && request.getParameter("code") != null;
}
}
```
The class overrides the `validateRequest` method, which is called on every request to our application,
and is responsible for notifying the container of the authentication status.
This sample uses the [Authorization Code
Flow](https://auth0.com/docs/flows/concepts/auth-code) to exchange an Authorization Code for a token during the authentication flow. If this request is to the
`/callback` endpoint and contains the `code` request parameter, it does a few important
things:
* Calls the `handle`method of the `AuthenticationController`to exchange the
Authorization Code for an ID token and an access token.
* Uses the ID token to create a new `Auth0Credential`.
* Calls the `validate`method of the custom `IdentityStore`implementation to obtain the
validation result.
* Notifies the application container of the login status.
If the requested resource is not `/callback`, return `httpMessageContext.doNothing()` to
allow the request processing to continue. You will see shortly how to use the authentication information when
triggering authentication and displaying web views.
Finally, note that the `@AutoApplySession` annotation has been added to allow the container to create
a session for the authenticated user.
To enable a user to log in, create a Servlet that will handle requests to the `/login` path.
The `LoginController` is responsible for redirecting the request to the proper authorization URL,
where the user can authenticate with Auth0. It uses the `AuthenticationController` from the Auth0 Java
MVC SDK to build the correct authorization URL, using the configuration values injected via
`Auth0AuthenticationConfig`. By default, this sample requests the `"openid profile email"`
scopes, to allow the application to retrieve basic profile information from the authenticated user. You can read
more about these scopes in the [OpenID
Connect Scopes](https://auth0.com/docs/scopes/current/oidc-scopes) documentation.
Once the user has entered their credentials and authorized the requested permissions, Auth0 will issue a request
to the `callbackUrl`, and include a `code` query parameter which can be exchanged for an ID
token and an access token. Recall that the `Auth0HttpAuthenticationMechanism` created above handles
this exchange so that it can notify the application container of authentication status. This allows the Servlet
that handles requests to the `/callback` path to simply forward the request on to the originally
requested resource prior to logging in, or simply redirect to the home page:
```java lines
// src/main/com/auth0/example/web/CallbackServlet.java
@WebServlet(urlPatterns = {"/callback"})
public class CallbackServlet extends HttpServlet {
@Override
public void doGet(HttpServletRequest request, HttpServletResponse response) throws IOException {
String referer = (String) request.getSession().getAttribute("Referer");
String redirectTo = referer != null ? referer : "/";
response.sendRedirect(redirectTo);
}
}
```
You can use the `Auth0JwtPrincipal` to get profile information for the authenticated user. The
`HomeServlet.java` code sample demonstrates how to use the claims on the [ID token](https://auth0.com/docs/tokens/id-token) to set profile data as a request
attribute.
You can then use that profile information in your view to display information about the user:
```xml lines
Sign up for an{" "}
Auth0 account
{" "}
or{" "}
console.log("log in")}>
log in
{" "}
to your existing account to integrate directly with your own tenant.
You need the following information:
* **Domain**
* **Client ID**
* **Client Secret**