Ajoutez la connexion à votre application Java EE

Ajoutez la connexion Auth0, la logout et le profil utilisateur à une application Web Java EE 8 à l’aide de l’API de sécurité Java EE 8

Utiliser l’IA pour intégrer Auth0

Si vous utilisez un assistant de codage IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter l’authentification Auth0 automatiquement en quelques minutes à l’aide d’Agent Skills.

Installation :

npx skills add auth0/agent-skills --skill auth0

Ensuite, demandez à votre assistant IA :

Add Auth0 authentication to my Java EE app

Votre assistant IA créera automatiquement votre application Auth0, récupérera les identifiants, ajoutera la dépendance du SDK Auth0 Java MVC Commons, configurera l’authentification avec l’API de sécurité Java EE 8 et mettra en œuvre les flux de connexion et de logout. Documentation complète sur Agent Skills →

Prérequis :

• Java Development Kit (JDK) 11 ou plus récent
• Apache Maven 3.x
• Un serveur d’applications compatible avec Java EE 8 (p. ex. WildFly 14+, Payara 5+ ou GlassFish 5+)
• Un compte Auth0 — inscrivez-vous gratuitement

​

Pour commencer

Auth0 vous permet d’ajouter rapidement l’authentification et d’accéder aux renseignements du profil utilisateur dans votre application. Ce guide explique comment intégrer Auth0 à toute application Java EE, nouvelle ou existante, à l’aide du SDK auth0-java-mvc-common et de l’API de sécurité Java EE 8.

1. Créer un nouveau projet

   Créez un nouveau projet Maven WAR :

   mvn archetype:generate \
     -DgroupId=com.auth0.example \
     -DartifactId=java-ee-auth0-app \
     -DarchetypeArtifactId=maven-archetype-webapp \
     -DinteractiveMode=false
   

   Accédez au dossier du projet :

   cd java-ee-auth0-app
   

   Créez les répertoires sources Java :

   mkdir -p src/main/java/com/auth0/example/security
   mkdir -p src/main/java/com/auth0/example/web
   mkdir -p src/main/webapp/WEB-INF/jsp
   
2. Installer le SDK Auth0

   Remplacez le contenu de votre pom.xml par le suivant :

   pom.xml

   <project xmlns="http://maven.apache.org/POM/4.0.0"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
            http://maven.apache.org/maven-v4_0_0.xsd">
       <modelVersion>4.0.0</modelVersion>
       <groupId>com.auth0.example</groupId>
       <artifactId>java-ee-auth0-app</artifactId>
       <packaging>war</packaging>
       <version>1.0-SNAPSHOT</version>
   
       <properties>
           <maven.compiler.source>11</maven.compiler.source>
           <maven.compiler.target>11</maven.compiler.target>
           <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
           <failOnMissingWebXml>false</failOnMissingWebXml>
           <version.wildfly>23.0.2.Final</version.wildfly>
       </properties>
   
       <dependencies>
           <dependency>
               <groupId>com.auth0</groupId>
               <artifactId>mvc-auth-commons</artifactId>
               <version>[1.0, 2.0)</version>
           </dependency>
           <dependency>
               <groupId>javax</groupId>
               <artifactId>javaee-api</artifactId>
               <version>8.0.1</version>
               <scope>provided</scope>
           </dependency>
           <dependency>
               <groupId>javax.security.enterprise</groupId>
               <artifactId>javax.security.enterprise-api</artifactId>
               <version>1.0</version>
               <scope>provided</scope>
           </dependency>
           <dependency>
               <groupId>com.fasterxml.jackson.core</groupId>
               <artifactId>jackson-databind</artifactId>
               <version>2.16.0</version>
           </dependency>
       </dependencies>
   
       <build>
           <finalName>java-ee-auth0-app</finalName>
           <plugins>
               <plugin>
                   <groupId>org.wildfly.plugins</groupId>
                   <artifactId>wildfly-maven-plugin</artifactId>
                   <version>4.2.0.Final</version>
                   <configuration>
                       <version>${version.wildfly}</version>
                       <javaOpts>
                           <javaOpt>-Djboss.http.port=8080</javaOpt>
                       </javaOpts>
                   </configuration>
               </plugin>
           </plugins>
       </build>
   </project>
   

   Les dépendances javaee-api et javax.security.enterprise-api sont provided, parce que le serveur d’applications Java EE 8 fournit leurs implémentations à l’exécution.

3. Configurez votre application Auth0

   Dashboard

   1. Accédez au Auth0 Dashboard et allez à Applications > Applications > Create Application.
   2. Entrez un nom pour votre application (p. ex., “My Java EE App”).
   3. Sélectionnez Regular Web Applications comme type d’application.
   4. Choisissez Create.
   5. Ouvrez l’onglet Settings.
   6. Prenez en note les valeurs Domain, Client ID et Client Secret.
   7. Faites défiler la page jusqu’à Application URIs et définissez :
      • Allowed Callback URLs : http://localhost:8080/callback
      • Allowed Logout URLs : http://localhost:8080/
   8. Choisissez Save Changes.

   Assurez-vous de configurer des connexions pour votre application afin que les utilisateurs puissent se connecter avec le fournisseur d’identité de leur choix.

4. Configurer l’authentification

   Mettez à jour votre web.xml pour stocker la configuration Auth0 en tant qu’entrées d’environnement JNDI. Remplacez les valeurs de l’espace réservé par le Domain, le Client ID et le Client Secret provenant des Application Settings de votre Auth0 Application. Créez un fichier jboss-web.xml pour configurer le domaine de sécurité JASPIC requis par la Java EE 8 Security API, un bean CDI Auth0AuthenticationConfig.java pour lire la configuration depuis JNDI, et un producteur CDI Auth0AuthenticationProvider.java pour construire l’AuthenticationController.

   N’incluez pas https:// dans la valeur auth0.domain. Utilisez uniquement le domaine et la région. Par exemple : dev-abc123.us.auth0.com.

5. Implement la sécurité Java EE

   La Java EE 8 Security API utilise HttpAuthenticationMechanism pour gérer l’authentification. Vous devez fournir des mises en œuvre personnalisées de plusieurs interfaces de sécurité. L’annotation @AutoApplySession permet au conteneur de créer une session pour l’utilisateur authentifié afin qu’il reste connecté d’une requête à l’autre.

6. Ajouter des fonctionnalités de connexion et de déconnexion

   Créez les servlets pour la connexion, le callback et la déconnexion. Le LoginServlet génère l’URL d’autorisation d’Auth0 et redirige l’utilisateur. Le CallbackServlet gère la redirection après l’authentification — Auth0AuthenticationMechanism intercepte d’abord cette requête pour échanger le code d’autorisation contre des jetons, donc le servlet n’a ensuite qu’à rediriger. Le LogoutServlet invalide la session et redirige vers le point de terminaison de déconnexion d’Auth0.

7. Créer l’interface utilisateur

   Créez les servlets et les pages JSP pour les vues d’accueil et de profil. Le HomeServlet vérifie la présence d’un principal authentifié et définit les claims du profil dans la requête. Le ProfileServlet affiche le profil de l’utilisateur et les claims JWT, ou redirige vers la connexion si l’utilisateur n’est pas authentifié.

8. Lancez votre application

   Compilez et exécutez l’application à l’aide du plugin Maven de WildFly :

   mvn clean wildfly:run
   

   Votre application devrait démarrer et afficher l’URL d’écoute :

   INFO  [org.jboss.as] WFLYSRV0025: WildFly started
   

   Ouvrez http://localhost:8080 dans votre navigateur. Cliquez sur le lien Login dans la barre de navigation. Vous serez redirigé vers la page de connexion Auth0. Après vous être authentifié, vous serez redirigé vers la page de profil, où vos informations utilisateur et vos claims JWT sont affichés.

   L’exemple utilise JSP et a été testé avec le serveur d’application WildFly. Vous devrez peut-être ajuster certaines étapes si vous utilisez un autre conteneur compatible avec Java EE 8.

Checkpoint

Vous devriez maintenant avoir une application Java EE protégée par Auth0, entièrement fonctionnelle, en cours d’exécution sur http://localhost:8080. Les utilisateurs peuvent se connecter, consulter leur profil et se déconnecter.

---

​

Utilisation avancée

Accéder aux renseignements du profil utilisateur

Auth0JwtPrincipal est accessible par request.getUserPrincipal() dans n’importe quel servlet. Le ProfileServlet montre comment accéder aux claims décodés du ID token :

Principal principal = request.getUserPrincipal();

if (principal instanceof Auth0JwtPrincipal) {
    Auth0JwtPrincipal auth0JwtPrincipal = (Auth0JwtPrincipal) principal;
    DecodedJWT idToken = auth0JwtPrincipal.getIdToken();

    String name = idToken.getClaim("name").asString();
    String email = idToken.getClaim("email").asString();
    String picture = idToken.getClaim("picture").asString();
    String sub = idToken.getSubject();
}

Claims courants disponibles dans le ID token :

• name — nom d’affichage complet de l’utilisateur
• email — adresse courriel de l’utilisateur
• picture — URL de la photo de profil de l’utilisateur
• sub — identificateur unique de l’utilisateur (ID utilisateur Auth0)

Personnaliser les paramètres de connexion

Ajoutez des paramètres personnalisés à l’URL d’autorisation lors de sa création dans votre LoginServlet :

src/main/java/com/auth0/example/web/LoginServlet.java

String authURL = authenticationController
        .buildAuthorizeUrl(request, response, callbackUrl)
        .withScope(config.getScope())
        .withAudience("https://your-api.example.com")
        .withParameter("screen_hint", "signup")
        .withParameter("ui_locales", "fr")
        .build();

Utilisez .withAudience() pour demander un jeton d’accès pour une API précise. Utilisez .withParameter() pour ajouter tout paramètre d’autorisation supplémentaire pris en charge par Auth0.

Stocker les jetons pour les appels d’API

Pour accéder aux jetons bruts pour les appels d’API, modifiez Auth0AuthenticationMechanism afin de stocker les jetons dans la session :

src/main/java/com/auth0/example/security/Auth0AuthenticationMechanism.java

if (isCallbackRequest(httpServletRequest)) {
    try {
        Tokens tokens = authenticationController.handle(
                httpServletRequest, httpServletResponse);

        httpServletRequest.getSession().setAttribute(
                "accessToken", tokens.getAccessToken());

        Auth0JwtCredential auth0JwtCredential =
                new Auth0JwtCredential(tokens.getIdToken());
        CredentialValidationResult result =
                identityStoreHandler.validate(auth0JwtCredential);
        return httpMessageContext.notifyContainerAboutLogin(result);
    } catch (IdentityVerificationException e) {
        return httpMessageContext.responseUnauthorized();
    }
}

Récupérez ensuite le jeton d’accès lors d’un appel à une API protégée :

String accessToken = (String) request.getSession().getAttribute("accessToken");
URL url = new URL("https://your-api.example.com/data");
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestProperty("Authorization", "Bearer " + accessToken);

Se connecter à une organisation

Configurez le AuthenticationController avec un ID ou un nom d’organisation afin de limiter la connexion à une Auth0 Organization précise :

src/main/java/com/auth0/example/security/Auth0AuthenticationProvider.java

@Produces
public AuthenticationController authenticationController(Auth0AuthenticationConfig config) {
    JwkProvider jwkProvider = new JwkProviderBuilder(config.getDomain()).build();
    return AuthenticationController.newBuilder(
                    config.getDomain(), config.getClientId(), config.getClientSecret())
            .withJwkProvider(jwkProvider)
            .withOrganization("org_YOUR_ORG_ID")
            .build();
}

Le SDK valide automatiquement le claim org_id ou org_name dans le ID token pour s’assurer qu’il correspond à l’organisation configurée.

---

​

Ressources supplémentaires

SDK Java MVC Auth0

Code source et suivi des problèmes

Référence de l’API (JavaDoc)

Documentation détaillée de l’API

Forum de la communauté

Obtenez de l’aide auprès de la communauté Auth0

Exemple d’application Java EE

Exemple d’application complet sur GitHub

---

​

Problèmes courants

Erreur de non-correspondance du state au callback

Si vous recevez une erreur a0.invalid_state après la connexion, le cookie de state est introuvable ou ne correspond pas au state renvoyé par Auth0.

Vérifiez que :

• Votre URL de callback dans le Auth0 Dashboard correspond exactement à l’URL générée par votre application, y compris le numéro de port et le protocole.
• Votre navigateur ne bloque pas les cookies tiers.
• Aucun reverse proxy ni middleware ne supprime les en-têtes Set-Cookie des réponses.

Assurez-vous d’utiliser la version à trois arguments de buildAuthorizeUrl et de handle, qui utilise un stockage du state basé sur les cookies :

// Correct — utilise des cookies pour le state
authenticationController.buildAuthorizeUrl(request, response, callbackUrl)
authenticationController.handle(httpServletRequest, httpServletResponse)

Beans CDI non détectés

Si vous voyez des erreurs liées à des échecs d’injection ou à des beans introuvables, assurez-vous que :

• Votre serveur d’applications prend en charge CDI 2.0 (qui fait partie de Java EE 8)
• Toutes les classes de sécurité (Auth0AuthenticationConfig, Auth0AuthenticationProvider, Auth0JwtIdentityStore, Auth0AuthenticationMechanism) sont annotées avec @ApplicationScoped
• src/main/webapp/WEB-INF/jboss-web.xml existe et que le domaine de sécurité jaspitest y est configuré

src/main/webapp/WEB-INF/jboss-web.xml

<jboss-web>
    <security-domain>jaspitest</security-domain>
    <context-root>/</context-root>
</jboss-web>

Le domaine de sécurité jaspitest est requis pour que WildFly active l’intégration JASPIC (Java Authentication SPI for Containers), dont dépend l’API de sécurité Java EE 8.

Compatibilité du serveur d’applications

Ce Quickstart utilise l’espace de noms javax (Java EE 8). Si vous utilisez un serveur ayant migré vers l’espace de noms jakarta (Jakarta EE 9+), comme WildFly 27+ ou Payara 6+, le code ne pourra ni être compilé ni s’exécuter.

Utilisez un serveur compatible avec Java EE 8 :

• WildFly 14 à 26
• Payara 5
• GlassFish 5
• Open Liberty avec les fonctionnalités Java EE 8

---

​

Exemple d’application

Un exemple d’application Java EE intégrée à Auth0 est offert sur GitHub :

Exemple d’application Java EE

Comprend des exemples de login, de logout, de profil utilisateur et plus encore.

Clonez et exécutez :

git clone https://github.com/auth0-samples/auth0-java-ee-sample.git
cd auth0-java-ee-sample/01-Login

Mettez à jour les paramètres de configuration d’Auth0 dans src/main/webapp/WEB-INF/web.xml, puis exécutez :

./mvnw clean wildfly:run

Accédez à http://localhost:8080 dans votre navigateur et cliquez sur Login pour tester.

---