Ajouter l’authentification à votre application Java EE

Utilisez l’IA pour intégrer Auth0

Si vous utilisez un assistant de programmation par IA comme Claude Code, Cursor ou GitHub Copilot, vous pouvez ajouter automatiquement l’authentification Auth0 en quelques minutes à l’aide des agent skills.Installer :

npx skills add auth0/agent-skills --skill auth0-quickstart --skill auth0-java-mvc-common

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 au 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 déconnexion. Documentation complète sur les agent skills →

Prérequis :

Java Development Kit (JDK) 11 ou une version ultérieure
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

Commencer

Auth0 vous permet d’ajouter rapidement l’authentification à votre application et d’accéder aux renseignements du profil utilisateur. 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.

Créer un nouveau projet

Générez 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 source 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

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, car le serveur d’applications Java EE 8 fournit leurs implémentations à l’exécution.

Configurez votre application Auth0

Auth0 Dashboard

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

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

Configurer l’authentification

Mettez à jour votre web.xml pour stocker la configuration Auth0 sous forme d’entrées d’environnement JNDI. Remplacez les valeurs fictives par le Domaine, l’ID client et le Secret client figurant dans les paramètres de l’application Auth0. Créez un fichier jboss-web.xml pour configurer le domaine de sécurité JASPIC requis par l’API de sécurité Java EE 8, 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.

Implémenter la sécurité Java EE

L’API de sécurité de Java EE 8 utilise HttpAuthenticationMechanism pour gérer l’authentification. Vous devez fournir des implémentations personnalisées de plusieurs interfaces de sécurité. L’annotation @AutoApplySession permet au conteneur de créer une session pour l’utilisateur authentifié afin que celui-ci reste connecté d’une requête à l’autre.

Ajouter les fonctionnalités de connexion et de déconnexion

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

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 revendications de profil sur la requête. Le ProfileServlet affiche le profil et les revendications JWT de l’utilisateur, ou redirige vers la page de connexion si l’utilisateur n’est pas authentifié.

Lancez votre application

Générez et exécutez l’application à l’aide du plugin Maven 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 d’Auth0. Après l’authentification, vous serez redirigé vers la page de profil, où s’affichent les renseignements sur l’utilisateur et les claims JWT.

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

Point de vérificationVous devriez maintenant avoir une application Java EE entièrement fonctionnelle, protégée par Auth0, qui s’exécute à l’adresse http://localhost:8080. Les utilisateurs peuvent ouvrir une session, consulter leur profil et fermer leur session.

Utilisation avancée

Accéder aux informations du profil utilisateur

Auth0JwtPrincipal est accessible via request.getUserPrincipal() dans n’importe quel servlet. ProfileServlet montre comment accéder aux claims décodées de l’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 courantes disponibles dans l’ID Token :

name — nom complet affiché de l’utilisateur
email — adresse courriel de l’utilisateur
picture — URL de la photo de profil de l’utilisateur
sub — identifiant 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 de l’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 AuthenticationController avec un ID ou un nom d’organisation afin de restreindre la connexion à une Organisation Auth0 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 la claim org_id ou org_name dans l’ID Token pour s’assurer qu’elle correspond à l’organisation configurée.

Ressources supplémentaires

SDK Java MVC d'Auth0

Code source et suivi des problèmes

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

Documentation détaillée de l’API

Forum communautaire

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 :

L’URL de callback configurée dans l’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 proxy inverse 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 le stockage du state dans des 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 indiquant 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 qui a migré vers l’espace de noms jakarta (Jakarta EE 9+), comme WildFly 27+ ou Payara 6+, le code ne pourra ni se compiler ni s’exécuter.Utilisez un serveur compatible Java EE 8 :

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

Application exemple

Une application Java EE exemple intégrée à Auth0 est offerte sur GitHub :

Application Java EE exemple

Comprend des exemples de connexion, de déconnexion, 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 valeurs 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, puis cliquez sur Login pour faire un test.

​Commencer

​Utilisation avancée

​Ressources supplémentaires

SDK Java MVC d'Auth0

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

Forum communautaire

Exemple d’application Java EE

​Problèmes courants

​Application exemple

Application Java EE exemple

Commencer

Utilisation avancée

Ressources supplémentaires

Problèmes courants

Application exemple