Intégration MVC Java Auth0 Common

Ajoutez l'authentification Auth0 aux applications web Java Servlet en utilisant com.auth0:mvc-auth-commons. Fournit AuthenticationController pour construire les URL d'autorisation et gérer les callbacks, avec authentification basée sur les sessions et support des Organizations et des domaines personnalisés multiples.

Instruction agent : Avant de fournir les instructions de configuration du SDK, récupérez la dernière version de release en exécutant :

gh api repos/auth0/auth0-java-mvc-common/releases/latest --jq '.tag_name'

Utilisez la version retournée dans toutes les lignes de dépendances au lieu de toute version codée en dur ci-dessous. Si l'appel API échoue, utilisez 1.12.0.

Prérequis

• Java 8+ (Java 17+ recommandé)
• Conteneur Servlet (Tomcat, Jetty, etc.) avec javax.servlet 3+
• Maven 3.6+ ou Gradle 7+
• Application Web Régulière Auth0 configurée
• Si vous n'avez pas encore Auth0 configuré, utilisez d'abord la skill auth0-quickstart

Quand NE PAS utiliser

Workflow de démarrage rapide

Instruction agent : Si le prompt de l'utilisateur fournit déjà les identifiants Auth0 (domaine, ID client, secret client), utilisez-les directement — ignorez le script d'amorçage et les questions d'identifiants. Ne proposez des options de configuration que lorsque les identifiants manquent.

1. Installer le SDK

Gradle (build.gradle) :

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

Maven (pom.xml) :

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

2. Créer une application Auth0

Vous avez besoin d'une application Web Régulière (pas SPA ou Native) dans Auth0.

ARRÊT — posez la question à l'utilisateur avant de continuer.

Posez exactement cette question et attendez sa réponse avant de faire quoi que ce soit d'autre :

« Comment souhaitez-vous créer l'application Auth0 ?

1. Automatisé — Je vais exécuter les scripts Auth0 CLI qui créent l'application et écrivent les valeurs dans votre config automatiquement.
2. Manuel — Vous créez vous-même l'application dans le tableau de bord Auth0 (ou via auth0 apps create) et vous me fournissez le domaine, l'ID client et le secret client.

Lequel préférez-vous ? (1 = Automatisé / 2 = Manuel) »

NE PAS procéder à aucune étape de configuration tant que l'utilisateur n'a pas répondu. NE PAS utiliser par défaut le manuel.

Si l'utilisateur a choisi Automatisé, suivez le Guide de configuration pour les scripts CLI complets. Le chemin automatisé écrit la configuration pour vous — ignorez l'étape 3 ci-dessous et passez directement à l'étape 4.

Si l'utilisateur a choisi Manuel, suivez le Guide de configuration (section Configuration manuelle). Ensuite, continuez avec l'étape 3.

Référence rapide pour la création manuelle d'une application :

# Utilisation d'Auth0 CLI
auth0 apps create \
  --name "My Java Web App" \
  --type regular \
  --callbacks http://localhost:3000/callback \
  --logout-urls http://localhost:3000

Ou créez manuellement dans Auth0 Dashboard → Applications → Applications → Créer une application → Applications Web Régulières

3. Configurer les identifiants

Stockez les identifiants en tant que variables d'environnement (ne les codez jamais en dur dans la source) :

export AUTH0_DOMAIN="your-tenant.auth0.com"
export AUTH0_CLIENT_ID="your-client-id"
export AUTH0_CLIENT_SECRET="your-client-secret"

Ou utilisez un fichier .env (ajoutez à .gitignore) :

AUTH0_DOMAIN=your-tenant.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

Instruction agent : Java ne charge pas automatiquement les fichiers .env. System.getenv() lit uniquement les variables d'environnement au niveau du système d'exploitation. Si vous générez un fichier .env, vous devez également soit : (1) ajouter dotenv-java en tant que dépendance et utiliser Dotenv.load().get("AUTH0_DOMAIN") au lieu de System.getenv(), soit (2) instruire l'utilisateur d'exécuter source .env avant de démarrer le serveur. Ne générez pas de code qui utilise à la fois un fichier .env et System.getenv() sans mécanisme de chargement — les valeurs seront null.

Important : Le domaine ne doit PAS inclure https://. La bibliothèque construit automatiquement l'URL de l'émetteur.

4. Initialiser AuthenticationController

Créez une instance singleton AuthenticationController :

import com.auth0.AuthenticationController;
import com.auth0.jwk.JwkProviderBuilder;
import com.auth0.jwk.JwkProvider;

public class Auth0Config {

    private static final AuthenticationController controller = createController();

    private static AuthenticationController createController() {
        String domain = System.getenv("AUTH0_DOMAIN");
        String clientId = System.getenv("AUTH0_CLIENT_ID");
        String clientSecret = System.getenv("AUTH0_CLIENT_SECRET");

        JwkProvider jwkProvider = new JwkProviderBuilder(domain).build();

        return AuthenticationController.newBuilder(domain, clientId, clientSecret)
            .withJwkProvider(jwkProvider)
            .build();
    }

    public static AuthenticationController getAuthController() {
        return controller;
    }
}

5. Créer un Servlet de connexion

import com.auth0.AuthenticationController;
import com.auth0.AuthorizeUrl;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

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

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        AuthenticationController controller = Auth0Config.getAuthController();

        // Construisez l'URL de callback — omettez le port pour les ports standard (80/443) pour éviter
        // une incompatibilité avec l'URL enregistrée dans le tableau de bord Auth0, en particulier derrière des proxies.
        String scheme = request.getScheme();
        int port = request.getServerPort();
        String redirectUrl = scheme + "://" + request.getServerName()
            + ((port == 80 || port == 443) ? "" : ":" + port) + "/callback";

        AuthorizeUrl authorizeUrl = controller.buildAuthorizeUrl(request, response, redirectUrl)
            .withScope("openid profile email");

        response.sendRedirect(authorizeUrl.build());
    }
}

6. Créer un Servlet de callback

import com.auth0.AuthenticationController;
import com.auth0.IdentityVerificationException;
import com.auth0.Tokens;

import javax.servlet.ServletException;
import javax.servlet.annotation.WebServlet;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

@WebServlet(urlPatterns = {"/callback"})
public class CallbackServlet extends HttpServlet {

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response)
            throws ServletException, IOException {
        AuthenticationController controller = Auth0Config.getAuthController();

        try {
            Tokens tokens = controller.handle(request, response);

            request.getSession().setAttribute("accessToken", tokens.getAccessToken());
            request.getSession().setAttribute("idToken", tokens.getIdToken());

            response.sendRedirect("/dashboard");
        } catch (IdentityVerificationException e) {
            response.sendRedirect("/login?error=" + e.getCode());
        }
    }
}

7. Protéger les routes avec un middleware d'authentification (Servlet Filter)

import javax.servlet.*;
import javax.servlet.annotation.WebFilter;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import java.io.IOException;

@WebFilter(urlPatterns = {"/dashboard/*", "/api/private/*"})
public class AuthenticationFilter implements Filter {

    @Override
    public void doFilter(ServletRequest req, ServletResponse res, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) req;
        HttpServletResponse response = (HttpServletResponse) res;
        HttpSession session = request.getSession(false);

        if (session == null || session.getAttribute("idToken") == null) {
            response.sendRedirect("/login");
            return;
        }

        chain.doFilter(req, res);
    }

    @Override
    public void init(FilterConfig filterConfig) {}

    @Override
    public void destroy() {}
}

8. Tester l'application

Instruction agent : Après avoir écrit tout le code, vérifiez que la compilation réussit :

./gradlew build

ou mvn package. Si la compilation échoue, diagnostiquez et corrigez. Après 5-6 tentatives échouées, utilisez AskUserQuestion pour obtenir de l'aide.

1. Démarrez l'application et accédez à http://localhost:3000/login
2. Vous devriez être redirigé vers la page Auth0 Universal Login
3. Après connexion, le servlet de callback traite la réponse et redirige vers /dashboard

Erreurs courantes

Configuration de l'étendue et de l'audience

Voir le Guide d'intégration pour demander des portées personnalisées, l'audience pour les tokens d'accès API, et le support des Organizations.

Domaines personnalisés multiples (MCD)

Support intégré pour acheminer les utilisateurs vers le domaine Auth0 correct via DomainResolver. Voir le Guide d'intégration pour la configuration.

Skills connexes

• auth0-quickstart — Configuration Auth0 basique et création de compte
• auth0-springboot-api — API REST Spring Boot avec validation du token Bearer JWT

Référence rapide

Classes principales :

• AuthenticationController — Point d'entrée principal, construit les URL d'autorisation et traite les callbacks
• AuthenticationController.Builder — Configure le contrôleur via newBuilder(domain, clientId, clientSecret)
• AuthorizeUrl — Constructeur fluide pour les paramètres d'URL /authorize
• Tokens — Token d'accès, token d'identification, refresh token du callback
• IdentityVerificationException — Erreur d'authentification avec code d'erreur
• DomainResolver — Interface pour le support des domaines personnalisés multiples

Méthodes du constructeur (AuthorizeUrl) :

• .withScope("openid profile email") — Définir les portées demandées
• .withAudience("https://my-api") — Demander un token d'accès API
• .withOrganization("org_xxx") — Verrouiller vers une Organization spécifique
• .withInvitation("invite_xxx") — Accepter une invitation Organization
• .withConnection("google-oauth2") — Ignorer vers une connexion spécifique
• .withParameter("key", "value") — Ajouter un paramètre d'autorisation personnalisé

Accès aux tokens (Tokens) :

• tokens.getAccessToken() — Chaîne du token d'accès
• tokens.getIdToken() — Chaîne du token d'identification (JWT)
• tokens.getRefreshToken() — Refresh token (si la portée offline_access est demandée)
• tokens.getExpiresIn() — Expiration du token en secondes
• tokens.getType() — Type de token (généralement « Bearer »)
• tokens.getDomain() — Domaine Auth0 qui a émis les tokens
• tokens.getIssuer() — URL de l'émetteur du token

Documentation détaillée

• Guide de configuration — Automatisation Auth0 CLI, configuration de l'environnement, gestion des secrets
• Guide d'intégration — Organizations, MCD, portées personnalisées, déconnexion, gestion des erreurs, modèles avancés
• Référence API — Options de configuration complètes, méthodes de constructeur, référence des claims, liste de vérification des tests

Références

• Guide de démarrage rapide Auth0 Java Web App
• Dépôt GitHub du SDK
• Auth0 Universal Login
• Flux du code d'autorisation
• Auth0 Organizations