Aller au contenu principal

Protégez votre API Vert.x Web avec le contrôle d’accès basé sur les rôles (RBAC) et la validation JWT

Ce guide vous aidera à mettre en œuvre l'autorisation pour sécuriser vos APIs Vert.x Web en utilisant le contrôle d’accès basé sur les rôles (RBAC) et les JSON Web Tokens (JWTs) émis par Logto.

Avant de commencer​

Vos applications clientes doivent obtenir des jetons d’accès (Access tokens) auprès de Logto. Si vous n'avez pas encore configuré l'intégration côté client, consultez nos Démarrages rapides pour React, Vue, Angular ou d'autres frameworks clients, ou consultez notre Guide machine à machine pour l'accès serveur à serveur.

Ce guide se concentre sur la validation côté serveur de ces jetons dans votre application Vert.x Web.

Une illustration montrant le focus de ce guide

Ce que vous allez apprendre​

  • Validation JWT : Apprenez à valider les jetons d’accès (Access tokens) et à extraire les informations d’authentification (Authentication)
  • Implémentation de middleware : Créez un middleware réutilisable pour la protection de votre API
  • Modèles de permissions : Comprenez et implémentez différents schémas d’autorisation (Authorization) :
    • Ressources API globales pour les points de terminaison à l’échelle de l’application
    • Permissions d’organisation pour le contrôle des fonctionnalités spécifiques à un locataire
    • Ressources API au niveau de l’organisation pour l’accès aux données multi-locataires
  • Intégration RBAC : Appliquez des permissions et des portées (Scopes) basées sur les rôles (Roles) dans vos points de terminaison API

Prérequis​

  • Dernière version stable de Java installée
  • Compréhension de base de Vert.x Web et du développement d’API web
  • Une application Logto configurée (voir Démarrages rapides si besoin)

Aperçu des modèles de permission​

Avant de mettre en place une protection, choisissez le modèle de permission qui correspond à l’architecture de votre application. Cela s’aligne avec les trois principaux scénarios d’autorisation de Logto :

RBAC des ressources API globales
  • Cas d’utilisation : Protéger les ressources API partagées à travers toute votre application (non spécifiques à une organisation)
  • Type de jeton : Jeton d’accès (Access token) avec audience globale
  • Exemples : APIs publiques, services principaux du produit, points de terminaison d’administration
  • Idéal pour : Produits SaaS avec des APIs utilisées par tous les clients, microservices sans isolation de locataire
  • En savoir plus : Protéger les ressources API globales

💡 Choisissez votre modèle avant de continuer – la mise en œuvre fera référence à l’approche choisie tout au long de ce guide.

Étapes de préparation rapide​

Configurer les ressources & permissions Logto​

  1. Créer une ressource API : Rendez-vous sur Console → Ressources API et enregistrez votre API (par exemple, https://api.votreapp.com)
  2. Définir les permissions : Ajoutez des portées comme read:products, write:orders – voir Définir des ressources API avec des permissions
  3. Créer des rôles globaux : Rendez-vous sur Console → Rôles et créez des rôles qui incluent vos permissions API – voir Configurer des rôles globaux
  4. Attribuer des rôles : Attribuez des rôles aux utilisateurs ou applications M2M qui ont besoin d'accéder à l'API
Nouveau sur le RBAC ?:

Commencez avec notre guide du contrôle d’accès basé sur les rôles (RBAC) pour des instructions d'installation étape par étape.

Mettez à jour votre application cliente​

Demandez les portées appropriées dans votre client :

Le processus consiste généralement à mettre à jour la configuration de votre client pour inclure un ou plusieurs des éléments suivants :

  • Paramètre scope dans les flux OAuth
  • Paramètre resource pour l'accès à la ressource API
  • organization_id pour le contexte d'organisation
Avant de coder:

Assurez-vous que l'utilisateur ou l'application M2M que vous testez s'est vu attribuer les rôles ou rôles d'organisation appropriés incluant les permissions nécessaires pour votre API.

Initialiser votre projet API​

Pour initialiser un nouveau projet Vert.x Web, vous pouvez créer un projet Maven manuellement :

pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<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/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>your-api-name</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <vertx.version>4.5.0</vertx.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>io.vertx</groupId>
            <artifactId>vertx-web</artifactId>
            <version>${vertx.version}</version>
        </dependency>
        <dependency>
            <groupId>io.vertx</groupId>
            <artifactId>vertx-auth-jwt</artifactId>
            <version>${vertx.version}</version>
        </dependency>
        <dependency>
            <groupId>io.vertx</groupId>
            <artifactId>vertx-web-client</artifactId>
            <version>${vertx.version}</version>
        </dependency>
    </dependencies>
</project>

Créez un serveur Web Vert.x de base :

src/main/java/com/example/MainVerticle.java
package com.example;

import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.handler.BodyHandler;

public class MainVerticle extends AbstractVerticle {

    @Override
    public void start(Promise<Void> startPromise) throws Exception {
        Router router = Router.router(vertx);

        router.route().handler(BodyHandler.create());

        router.get("/hello").handler(ctx -> {
            ctx.response()
                .putHeader("content-type", "text/plain")
                .end("Hello from Vert.x Web!");
        });

        vertx.createHttpServer()
            .requestHandler(router)
            .listen(3000, http -> {
                if (http.succeeded()) {
                    startPromise.complete();
                    System.out.println("Serveur HTTP démarré sur le port 3000");
                } else {
                    startPromise.fail(http.cause());
                }
            });
    }
}
src/main/java/com/example/Application.java
package com.example;

import io.vertx.core.Vertx;

public class Application {
    public static void main(String[] args) {
        Vertx vertx = Vertx.vertx();
        vertx.deployVerticle(new MainVerticle());
    }
}
remarque:

Consultez la documentation Vert.x Web pour plus de détails sur la configuration des routes, des gestionnaires et d'autres fonctionnalités.

Initialiser les constantes et utilitaires​

Définissez les constantes et utilitaires nécessaires dans votre code pour gérer l’extraction et la validation du jeton. Une requête valide doit inclure un en-tête Authorization sous la forme Bearer <jeton d’accès (access token)>.

AuthorizationException.java
public class AuthorizationException extends RuntimeException {
    private final int statusCode;

    public AuthorizationException(String message) {
        this(message, 403); // Par défaut à 403 Interdit
    }

    public AuthorizationException(String message, int statusCode) {
        super(message);
        this.statusCode = statusCode;
    }

    public int getStatusCode() {
        return statusCode;
    }
}

Récupérer les informations sur votre tenant Logto​

Vous aurez besoin des valeurs suivantes pour valider les jetons émis par Logto :

  • URI JSON Web Key Set (JWKS) : L’URL vers les clés publiques de Logto, utilisée pour vérifier les signatures JWT.
  • Émetteur (Issuer) : La valeur attendue de l’émetteur (l’URL OIDC de Logto).

Commencez par trouver l’endpoint de votre tenant Logto. Vous pouvez le trouver à différents endroits :

  • Dans la Console Logto, sous Paramètres → Domaines.
  • Dans les paramètres de toute application que vous avez configurée dans Logto, Paramètres → Endpoints & Credentials.

Récupérer depuis l’endpoint de découverte OpenID Connect​

Ces valeurs peuvent être récupérées depuis l’endpoint de découverte OpenID Connect de Logto :

https://<your-logto-endpoint>/oidc/.well-known/openid-configuration

Voici un exemple de réponse (autres champs omis pour plus de clarté) :

{
  "jwks_uri": "https://your-tenant.logto.app/oidc/jwks",
  "issuer": "https://your-tenant.logto.app/oidc"
}

Puisque Logto ne permet pas de personnaliser l’URI JWKS ou l’émetteur (Issuer), vous pouvez coder ces valeurs en dur dans votre code. Cependant, cela n’est pas recommandé pour les applications en production, car cela peut augmenter la charge de maintenance si une configuration change à l’avenir.

  • URI JWKS : https://<your-logto-endpoint>/oidc/jwks
  • Émetteur (Issuer) : https://<your-logto-endpoint>/oidc

Valider le jeton et les permissions​

Après avoir extrait le jeton et récupéré la configuration OIDC, validez les éléments suivants :

  • Signature : Le JWT doit être valide et signé par Logto (via JWKS).
  • Émetteur (Issuer) : Doit correspondre à l’émetteur de votre tenant Logto.
  • Audience (Audience) : Doit correspondre à l’indicateur de ressource de l’API enregistré dans Logto, ou au contexte d’organisation si applicable.
  • Expiration : Le jeton ne doit pas être expiré.
  • Permissions (Portées / scopes) : Le jeton doit inclure les portées requises pour votre API / action. Les portées sont des chaînes séparées par des espaces dans la revendication scope.
  • Contexte d’organisation : Si vous protégez des ressources API au niveau organisation, validez la revendication organization_id.

Consultez JSON Web Token pour en savoir plus sur la structure et les revendications des JWT.

À vérifier selon chaque modèle de permission​

  • Revendication Audience (aud) : Indicateur de ressource API
  • Revendication Organisation (organization_id) : Non présent
  • Portées (permissions) à vérifier (scope) : Permissions de ressource API

Pour les permissions d’organisation hors API, le contexte d’organisation est représenté par la revendication aud (par exemple, urn:logto:organization:abc123). La revendication organization_id n’est présente que pour les jetons de ressource API au niveau organisation.
astuce:

Validez toujours à la fois les permissions (portées / scopes) et le contexte (audience, organisation) pour sécuriser les API multi-tenant.

Ajouter la logique de validation​

Nous utilisons différentes bibliothèques JWT selon le framework. Installez les dépendances requises :

Ajoutez à votre pom.xml :

<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web</artifactId>
</dependency>
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-auth-jwt</artifactId>
</dependency>
<dependency>
    <groupId>io.vertx</groupId>
    <artifactId>vertx-web-client</artifactId>
</dependency>
JwtAuthHandler.java
import io.vertx.core.Future;
import io.vertx.core.Handler;
import io.vertx.core.Vertx;
import io.vertx.core.json.JsonArray;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.auth.jwt.JWTAuth;
import io.vertx.ext.auth.jwt.JWTAuthOptions;
import io.vertx.ext.web.RoutingContext;
import io.vertx.ext.web.client.WebClient;
import java.util.List;
import java.util.ArrayList;

public class JwtAuthHandler implements Handler<RoutingContext> {

    private final JWTAuth jwtAuth;
    private final WebClient webClient;
    private final String expectedIssuer;
    private final String jwksUri;

    public JwtAuthHandler(Vertx vertx) {
        this.webClient = WebClient.create(vertx);
        this.jwtAuth = JWTAuth.create(vertx, new JWTAuthOptions());

        // N'oubliez pas de définir ces variables d'environnement dans votre déploiement
        this.expectedIssuer = System.getenv("JWT_ISSUER");
        this.jwksUri = System.getenv("JWKS_URI");

        // Récupérer le JWKS et configurer l'authentification JWT
        fetchJWKS().onSuccess(jwks -> {
            // Configurer le JWKS (simplifié - vous pourriez avoir besoin d'un parseur JWKS approprié)
        });
    }

    @Override
    public void handle(RoutingContext context) {
        String authHeader = context.request().getHeader("Authorization");
        if (authHeader == null || !authHeader.startsWith("Bearer ")) {
            context.response()
                .setStatusCode(401)
                .putHeader("Content-Type", "application/json")
                .end("{\"error\": \"Authorization header missing or invalid\"}");
            return;
        }

        String token = authHeader.substring(7);
        jwtAuth.authenticate(new JsonObject().put("jwt", token))
            .onSuccess(user -> {
                try {
                    JsonObject principal = user.principal();
                    verifyPayload(principal);
                    context.put("auth", principal);
                    context.next();
                } catch (AuthorizationException e) {
                    context.response()
                        .setStatusCode(e.getStatusCode())  // Utiliser le code d'état de l'exception
                        .putHeader("Content-Type", "application/json")
                        .end("{\"error\": \"" + e.getMessage() + "\"}");
                } catch (Exception e) {
                    context.response()
                        .setStatusCode(401)
                        .putHeader("Content-Type", "application/json")
                        .end("{\"error\": \"Invalid token\"}");
                }
            })
            .onFailure(err -> {
                context.response()
                    .setStatusCode(401)
                    .putHeader("Content-Type", "application/json")
                    .end("{\"error\": \"Invalid token: " + err.getMessage() + "\"}");
            });
    }

    private Future<JsonObject> fetchJWKS() {
        return webClient.getAbs(this.jwksUri)
            .send()
            .map(response -> response.bodyAsJsonObject());
    }

    private void verifyPayload(JsonObject principal) {
        // Vérifier l'émetteur manuellement pour Vert.x
        String issuer = principal.getString("iss");
        if (issuer == null || !expectedIssuer.equals(issuer)) {
            throw new AuthorizationException("Invalid issuer: " + issuer);
        }

        // Implémentez ici votre logique de vérification supplémentaire basée sur le modèle de permission
        // Utilisez les méthodes utilitaires ci-dessous pour l'extraction des revendications
    }

    // Méthodes utilitaires pour Vert.x JWT
    private List<String> extractAudiences(JsonObject principal) {
        JsonArray audiences = principal.getJsonArray("aud");
        if (audiences != null) {
            List<String> result = new ArrayList<>();
            for (Object aud : audiences) {
                result.add(aud.toString());
            }
            return result;
        }
        return List.of();
    }

    private String extractScopes(JsonObject principal) {
        return principal.getString("scope");
    }

    private String extractOrganizationId(JsonObject principal) {
        return principal.getString("organization_id");
    }
}

Selon votre modèle de permission (Permission), implémentez la logique de vérification appropriée :

// Vérifiez que la revendication d'audience (Audience) correspond à votre indicateur de ressource API
List<String> audiences = extractAudiences(token); // Extraction spécifique au framework
if (!audiences.contains("https://your-api-resource-indicator")) {
    throw new AuthorizationException("Audience invalide");
}

// Vérifiez les portées (Scopes) requises pour les ressources API globales
List<String> requiredScopes = Arrays.asList("api:read", "api:write"); // Remplacez par vos portées requises réelles
String scopes = extractScopes(token); // Extraction spécifique au framework
List<String> tokenScopes = scopes != null ? Arrays.asList(scopes.split(" ")) : List.of();

if (!tokenScopes.containsAll(requiredScopes)) {
    throw new AuthorizationException("Portée insuffisante");
}

Les méthodes utilitaires pour extraire les revendications (Claims) sont spécifiques au framework. Consultez les détails d'implémentation dans les fichiers de validation spécifiques au framework ci-dessus.

Appliquer le middleware à votre API​

Appliquez maintenant le middleware à vos routes API protégées.

MainVerticle.java
import io.vertx.core.AbstractVerticle;
import io.vertx.core.Promise;
import io.vertx.core.json.JsonObject;
import io.vertx.ext.web.Router;
import io.vertx.ext.web.RoutingContext;

public class MainVerticle extends AbstractVerticle {

    @Override
    public void start(Promise<Void> startPromise) throws Exception {
        Router router = Router.router(vertx);

        // Appliquer le middleware aux routes protégées
        router.route("/api/protected*").handler(new JwtAuthHandler(vertx));
        router.get("/api/protected").handler(this::protectedEndpoint);

        vertx.createHttpServer()
            .requestHandler(router)
            .listen(8080, result -> {
                if (result.succeeded()) {
                    startPromise.complete();
                } else {
                    startPromise.fail(result.cause());
                }
            });
    }

    private void protectedEndpoint(RoutingContext context) {
        // Accéder au principal JWT directement depuis le contexte
        JsonObject principal = context.get("auth");
        if (principal == null) {
            context.response()
                .setStatusCode(500)
                .putHeader("Content-Type", "application/json")
                .end("{\"error\": \"JWT principal not found\"}");
            return;
        }

        String scopes = principal.getString("scope");
        JsonObject response = new JsonObject()
            .put("sub", principal.getString("sub"))
            .put("client_id", principal.getString("client_id"))
            .put("organization_id", principal.getString("organization_id"))
            .put("scopes", scopes != null ? scopes.split(" ") : new String[0])
            .put("audience", principal.getJsonArray("aud"));

        context.response()
            .putHeader("Content-Type", "application/json")
            .end(response.encode());
    }
}

Tester votre API protégée​

Obtenir des jetons d’accès (Access tokens)​

Depuis votre application cliente :
Si vous avez configuré une intégration client, votre application peut obtenir automatiquement les jetons. Extrayez le jeton d’accès (access token) et utilisez-le dans les requêtes API.

Pour tester avec curl / Postman :

  1. Jetons utilisateur : Utilisez les outils développeur de votre application cliente pour copier le jeton d’accès depuis le localStorage ou l’onglet réseau.

  2. Jetons machine à machine : Utilisez le flux d’identifiants client (client credentials flow). Voici un exemple non normatif utilisant curl :

    curl -X POST https://your-tenant.logto.app/oidc/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=client_credentials" \
      -d "client_id=your-m2m-client-id" \
      -d "client_secret=your-m2m-client-secret" \
      -d "resource=https://your-api-resource-indicator" \
      -d "scope=api:read api:write"

    Vous devrez peut-être ajuster les paramètres resource et scope selon votre ressource API (API resource) et vos permissions ; un paramètre organization_id peut également être requis si votre API est liée à une organisation.

astuce:

Besoin d’inspecter le contenu du jeton ? Utilisez notre décodificateur JWT pour décoder et vérifier vos JWT.

Tester les points de terminaison protégés​

Requête avec jeton valide
curl -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
  http://localhost:3000/api/protected

Réponse attendue :

{
  "auth": {
    "sub": "user123",
    "clientId": "app456",
    "organizationId": "org789",
    "scopes": ["api:read", "api:write"],
    "audience": ["https://your-api-resource-indicator"]
  }
}
Jeton manquant
curl http://localhost:3000/api/protected

Réponse attendue (401) :

{
  "error": "Authorization header is missing"
}
Jeton invalide
curl -H "Authorization: Bearer invalid-token" \
  http://localhost:3000/api/protected

Réponse attendue (401) :

{
  "error": "Invalid token"
}

Tests spécifiques au modèle de permission​

Scénarios de test pour les API protégées par des portées globales :

  • Portées valides : Testez avec des jetons qui incluent les portées API requises (par exemple, api:read, api:write)
  • Portées manquantes : Attendez-vous à une réponse 403 Interdit si le jeton ne contient pas les portées requises
  • Audience incorrecte : Attendez-vous à une réponse 403 Interdit si l’audience ne correspond pas à la ressource API
# Jeton sans les portées requises - attendre 403
curl -H "Authorization: Bearer token-without-required-scopes" \
  http://localhost:3000/api/protected

Pour aller plus loin​

RBAC en pratique : Mettre en œuvre une autorisation sécurisée pour votre application

Construire une application SaaS multi-locataires : Guide complet de la conception à la mise en œuvre