Techland

OAuth 2.1 - une évolution pas si anodine

Thu, 25 Dec 2025 15:10:00 +0100

Oauth 2.1 est encore en draft mais l’on peut déjà voir les évolutions qui arriveront par rapport à OAuth 2.0. OAuth 2.1 est décrit comme une consolidation des bonnes pratiques et des extensions ajoutées à OAuth 2.0. Nous allons parler d’une fonctionnalité en particulier qui à mon sens est un gros plus, mais n’est, pourtant pas du tout mis en avant.

Les nouveautés de OAuth 2.1

Sur le site de la spécification les principaux changements mis en avant sont les suivants :

PKCE est maintenant requis pour tous les clients OAuth utilisant le flow Authorization Code
Les Redirect URIs doivent être comparées avec une égalité parfaite. Plus de wildcard (*)
L’ Implicit grant (response_type=token) est supprimé de la spécification
Le Resource Owner Password Credentials grant est supprimé de la spécification
Les Bearer token ne sont plus utilisables dans les paramètres des URIs.
Les Refresh tokens pour les clients publics doivent être soit must contraint par l’expéditeur soit utilisable une unique fois.
Les définitions de clients publics et confidentiels ont été simplifiés et ne font plus référence qu’à la possession ou non d’une accréditation par le client.

Comme je le disais en intro, cela ne fait que pérenniser des bonnes pratiques déjà employées avec OAuth2.

Header WWW-Authenticate, le header qui change tout.

Une nouveauté qui pourrait presque passer inaperçu mais qui change pour moi beaucoup de chose est la section 5.3.1. The WWW-Authenticate Response Header Field.

Le concept est qu’en cas d’échec lors de l’appel d’un endpoint, une réponse avec un code 401/403 est renvoyé et un header WWW-Authenticate doit ajouté à la réponse. Ce Header peut avoir les attributs suivants :

realm: Le royaume gérant les authorizations pour le serveur de ressource
scope: La liste des scopes requis pour accéder au endpoint demandé
error: Un code d’erreur. Les valeurs possibles sont invalid_request,invalid_token, insufficient_scope
error_description: Une description de l’erreur
error_uri: Un lien permettant d’avoir de plus amples information sur l’erreur

Par exemple en cas de code 401 pour une requète sans token :

1
2

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="https://auth.example.com"

Ou avec un token expiré :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="https://auth.example.com",
                  error="invalid_token",
                  error_description="The access token expired"

Dans le cas où le token est valide, mais ne dispose pas des scopes suffisants :

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer realm="https://auth.example.com",
                  error="insufficient_scope",
                  error_description="Bearer token is missing required scopes"
                  scope="openid user-list user-add"

Ces apports à priori anodins permettent de découpler complétement un client des serveurs de ressource d’un point de vue autorisation d’accès. Le serveur de ressource est maintenant capable d’indiquer auprès de quel royaume demander un token et quels scopes celui-ci doit contenir pour être valide.

Cela permet de rendre complétement dynamique la gestion des droits sans avoir à redéployer une mise à jour des clients. Ceux-ci iront automatiquement chercher les nouveaux scopes nécessaire.

La spécification ne précise pas comment le serveur de ressource récupère la liste des scopes à renseigner dans le token. Le plus simple est de passer par un système de convention. Ainsi le endpoint POST /users aura besoin du scope user-add. une autre solution est d’avoir un endpoint exposé par le serveur d’autorisation que le serveur de ressource pourrait interroger pour connaitre la liste des scopes nécessaire pour un endpoint.

Dans le deuxième cas, un manque de standardisation entre les serveurs d’autorisation se fera rapidement ressentir et on se tournera volontiers vers une extension OAuth, appelée UMA 2, répondant justement à ces problématiques et proposant le même mécanisme de header WWW-Authenticate.

---
config:
  noteAlign: left
---
sequenceDiagram
    autonumber
    participant Client
    participant ResourceServer
    participant AuthorizationServer
    Client->>ResourceServer: Initial request without token or with missing scope
    alt Requesting scope to AS
      ResourceServer->>AuthorizationServer: Ask for required scopes
      AuthorizationServer->>ResourceServer: Send Required scopes
    else Handling required scope locally
      ResourceServer->>ResourceServer: compute scopes via convention or configuration
    end
    ResourceServer->>Client: 403 - WWW-Autenticate header (realm + scope + error)
    Note left of ResourceServer: HTTP/1.1 403 Forbidden 

 WWW-Authenticate: Bearer realm="https://auth.example.com",
 error="insufficient_scope",
error_description="Bearer token is missing required scopes"
scope="openid user-list user-add"
    Client->>AuthorizationServer: Ask for a token with required scope
    AuthorizationServer->>Client: Check Rights and send token with requested scopes
    Client->>ResourceServer: Send request with token with needed scopes
    ResourceServer->>Client: Send requested data

Conclusion

OAuth 2.1 est une évolution attendue de longue date et tirant profit des bonnes pratiques et l’expérience d’OAuth2. L’apport du header WWW-Autenticate de manière standard dans la spécification permet d’envisager une réduction de la maintenance des applications grâce à une prise en compte dynamique des changements d’autorisations des serveurs de ressources.

Conditional Authenticator personnalisé avec Keycloak

Sun, 10 Aug 2025 12:00:00 +0100

Dans Keycloak, quand vous avez besoin de personnalisé un flow de connexion suivant certaines conditions non prévue de base par Keycloak (User configured et User Attribute), la manière de procéder est d’implémenter un ConditionalAuthenticator

Prérequis

Nous allons avoir besoin des dépendances suivantes :

<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-server-spi</artifactId>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-server-spi-private</artifactId>
</dependency>
<dependency>
    <groupId>org.keycloak</groupId>
    <artifactId>keycloak-services</artifactId>
</dependency>

Création de la factory

Keycloak utilise le mécanisme Java standard des SPIs pour définir ses providers. Nous devons donc créer notre factory permettant à Keycloak d’initialiser notre provider.

public class CustomConditionalAuthenticatorFactory implements ConditionalAuthenticationFactory {

	public static final String PROVIDER_ID= "custom-authenticator";
	
	public static final String CONFIG_CONDITION = "foo";
	
	private static final AuthenticationExecutionModel.Requirement[] REQUIREMENT_CHOICES = {
                AuthenticationExecutionModel.Requirement.REQUIRED,
                AuthenticationExecutionModel.Requirement.DISABLED
        };
        
        Override
        public void init(Config.Scope scope) {}

        @Override
        public void postInit(KeycloakSessionFactory keycloakSessionFactory) {}

        @Override
        public void close() {}

        @Override
        public String getId() {
                return PROVIDER_ID;
        }

        @Override
        public String getDisplayType() {
                return "Condition - Custom Authenticator";
        }

        @Override
        public boolean isConfigurable() {
                return true;
        }

        @Override
        public AuthenticationExecutionModel.Requirement[] getRequirementChoices() {
                return REQUIREMENT_CHOICES;
        }

        @Override
        public boolean isUserSetupAllowed() {
                return false;
        }

        @Override
        public String getHelpText() {
                return "Flow is executed if condition is validated.";
        }

        @Override
        public List<ProviderConfigProperty> getConfigProperties() {
                ProviderConfigProperty condition = new ProviderConfigProperty();
                condition.setName(CONFIG_CONDITION);
                condition.setLabel("Custom Condition");
                condition.setHelpText("Set a value to be validated");
                condition.setType(STRING_TYPE);
                condition.setDefaultValue("");
        }

        @Override
        public ConditionalAuthenticator getSingleton() {
                return CustomConditionalAuthenticator.SINGLETON;
        }
}

Nombre de méthodes ne sont pas utilisées pour un authenticator conditionnel. Notre factory est en charge de l’instanciation du provider et de la gestion de la configuration dans l’interface de Keycloak. Dans notre cas, nous avons une condition de type String ayant pour nom foo. Notre factory définie aussi le type d’exécution possible. Ici, nous laisser le choix pour l’état Disabled ou Required. La méthode getConfigurationProvider est utilisée pour permettre la configuration du provider depuis l’interface d’administration de Keycloak.

Création du provider

Le provider est la classe contenant la logique de notre implémentation.

public class CustonContidionalAuthenticator implements ConditionalAuthenticator {

    private static final Logger logger = Logger.getLogger(ThreatmetrixConditionalAuthenticator.class);
    
    @Override
    public boolean matchCondition(AuthenticationFlowContext context ) {
    	Map<String, String> config = context.getAuthenticatorConfig().getConfig();
    	if (!config.containsKey(CustomConditionalAuthenticatorFactory.CONFIG_CONDITION)) {
            throw new AuthenticationFlowException(AuthenticationFlowError.valueOf("Missing url for Threatmetrix configuration."));
        }
        String condition = config.get(CustomConditionalAuthenticatorFactory.CONFIG_CONDITION);
        
	return evaluate(condition)
    }
    
    @Override
    public void action(AuthenticationFlowContext authenticationFlowContext) {}

    @Override
    public boolean requiresUser() {}

    @Override
    public void setRequiredActions(KeycloakSession keycloakSession, RealmModel realmModel, UserModel userModel) {}

    @Override
    public void close() {}

matchCondition est la seule méthode utilisée. Elle permet d’évaluer si la condition sera positive ou négative. Pour simplifier le code, notre implémentation appelle la méthode evaluate en charge d’évaluer notre condition. C’est ici que sera définir le traitement souhaité pour l’implémentation.

Référencement de notre provider dans Keycoak

Il ne nous reste plus qu’à référencer notre provider dans Keycloak en créant le fichier resources/META-INF/services/org.keycloak.authentication.AuthenticationFactory avec le FQDN de notre factory.

`1`	`org.techland.keycloak.provider.CustomConditionalAuthenticatorFactory`

Conclusion

Le création d’un authenticator personnalisé est simple et ne demande que l’implémentation de deux classes, la factory et le provider. Une fois le jar créé, il suffit de le déposer dans le dossier /opt/keycloak/providers puis de se rendre dans le menu Authentication et sélectionner un flow personnalisé pour ajouter notre nouvelle condition.

Injection de token oauth2 dans des tests JUnit

Thu, 19 Jun 2025 17:23:12 +0200

Lorsque l’on développe des tests API, il arrive fréquemment de devoir s’authentifier pour effectuer l’appel. Réécrire le code permettant de récupérer un token valide est non seulement fastidieux, source d’erreur, mais également une mauvaise pratique en termes de maintenabilité. Nous allons voir comment injecter un token valide directement en paramètre de test JUnit de manière à pouvoir l’utiliser simplement là où cela est nécessaire.

Introduction

Une solution couramment mise en place pour répondre à cette problématique est de créer une méthode utilitaire permettant de récupérer le token suivant le flow de connexion supporté par l’application. Cette méthode sera probablement définie dans une classe utils ou common, noyée au milieu de nombreuses autres méthodes. Cette classe étant elle-même sûrement dans un package util totalement générique. Les problématiques sont très bien expliqué dans cet article. Je vous propose donc de voir comment mettre en œuvre le mécanisme d’extension JUnit pour réaliser proprement une injection de token dans chaque test, le nécessitant.

JUnit Extension

Les extensions JUnit est une fonctionnalité apparue avec JUnit 5 permettant de modifier le comportant de JUnit lors de l’exécution des tests. La documentation est très bien faite, je vous invite à la lire. Une extension s’utilise via une annotation spéciale @ExtendWith sur une classe de test, un champ de classe, un paramètre de constructeur, dans une méthode de tests ou sur les méthodes annotées @BeforeAll, @AfterAll, @BeforeEach, and @AfterEach.

Exemple pour une classe :

1
2

@ExtendWith(MyExtension.class)
class MyTestClass {}

Ou un test en particulier

class MyTestClass {

  @Test
  @ExtendWith(MyExtension.class)
  void myTest() {}
}

BearerParameterExtension

Il existe plusieurs types d’extensions proposées par JUnit. Nous allons utiliser une extension implémentant l’interface ParameterResolver. Cette interface définie une extension permettant d’injecter une valeur lorsque qu’un test demande un paramètre spécifique dans la signature de sa méthode. Dans notre cas, notre test va demander un token en paramètre.

1
2
3

void MyTest(Token token){

}

Un objet Token est passé ici à la place d’un simple String afin de permettre à notre extension de différencier notre token de n’importe quel autre paramètre de type String.

Voici maintenant le code de l’extension :

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharset;

import org.junit.jupiter.api.extension.ExtensionContext;
import org.junit.jupiter.api.extension.ParameterContext;
import org.junit.jupiter.api.extension.ParameterResolutionException;
import org.junit.jupiter.api.extension.ParameterResolver;

import com.fasterxml.jackson.databind.ObjectMapper;

public class BearerParameterResolver implements ParameterResolver {

  @Overrride
  public boolean supportsParameter(ParameterContext parameterContext, ExtensionContext extensionContext) throws ParameterResolutionException {
    return parameterContext.getParameter().getType().equals(Token.class)
  }

  @Override
  public Object resolverParameter(ParameterContext parameterContext, ExtensionContext extensionContext) throws ParameterResolutionException {
    return parameterContext.findAnnotation(ClientCredential.class).map(annotation -> {
      String realm = annotation.realm();
      String clientId = annotation.clientId();
      String clientSecret = annotation.clientSecret();

      try {
        String token = authenticate(realm, clientId, clientSecret);
        return new Token(token);
      } catch (IOException | InterruptedException e) {
        throw new ParameterResolutionException("Failed to authenticate with Keycloak", e);
      }
    })
  }

  private String authenticate(String realm, String cleintId, String clientSecret) throws IOException, InterruptionException {
    String tokenUrl = Env.KEYCLOAK_URL + "/realms/" + realm + "/protocol/openid-connect/token";
    String body = "grant_type=client_credentials"
      + "&client_id=" + URLEncoder.encode(clientId, StandardCharset.UTF_8)
      + "&client_secret=" + URLEncoder.encode(clientSecret, StandardCharset.UTF_8);

    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create(tokenUrl))
      .header("Content-Type", "application/x-www-form-urlencoded")
      .POST(HttpRequest.BodyPublishers.ofString(body))
      .build();

    HttpClient client = HttpClient.newHttpClient();
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());

    ObjectMapper mapper = new ObjectMapper();
    TokenResponse tokenResponse = objectMapper.readValue(response.body(), TokenResponse.class);
    return tokenResponse.access_token;
  }
}

Plusieurs points à préciser ici :

Notre extension utilise une annotation à appliquer sur le paramètre du test pour configurer l’injection.
L’authorization provider utilisé ici est Keycloak. J’utilise donc le concept de realm pour reconstruire dynamiquement l’URL du token provider dans la méthode authenticate. Une implémentation plus générique demanderait l’URL du token endpoint mais je préfère garder l’annotation la plus concise possible.
La méthode authenticate va faire l’authentification et récupérer le token. C’est l’équivalent de notre méthode utilitaire dont je parlais en début d’article.

Utilisation de l’extension

En reprenant l’exemple du test ci-dessus, nous pouvons utiliser l’extension de la manière suivante :

import static io.restassured.RestAssured.*;

@ExtendWith(BearerParameterResolver.class)
class MyTestClass {

  @Test
  
  void myTest(@ClientCredential(clientId = "myClientId", clientSecret = "mySecret", realm = "myRealm") Token token) {
    given()
      .body("...")
      .contentType("application/json")
      .auth().preemptive().oauth2(token.getValue())
    .when()
      .post("...")
    .then()
      .statusCode(200)
  }
}

Nous pouvons donc maintenant simplement injecter des tokens valides dans nos tests. Ici, nous l’utilisons via restAssured pour effectuer une requête POST sur notre API en étant authentifié.

Point à améliorer

Le code n’est pas parfait. Voici quelques points à améliorer selon moi :

Prendre en compte, plusieurs flow de connection via différentes annotations (@ClientCredentials, @DirectGrant, @AuthorizationCode…)
Remplacer la classe Env par un chargement des variables via fichiers de configuration par environnement
Dans le test, trouver un autre moyen que de passer en dur le secret à l’annotation

Conclusion

Le système d’extension de JUnit permet d’injecter facilement des objets en paramètre des tests. L’injection de dépendance permet de découpler la logique de préparation des données nécessaires à l’exécution du test de celle purement fonctionnelle. Cela apporte une plus grande lisibilité et une maintenance facilitée. D’autres extensions existent avec JUnit pour, par exemple agir sur le cycle de vie des tests et permettre de démarrer automatiquement des conteneurs docker, importer des données dans une base… .

Annexe

Pour référence voici les classes Token et `TokenResponse utiliser dans le code ci-dessus :

public class Token {

  private String value;

  public Token(String token) {
    this.value = value;
  }

  public String getValue() {
    return value;
  }
}

public class TokenResponse {
  @JsonProperty("access_token")
  public String accessToken;
  @JsonProperty("expires_in")
  public int expiresIn;
  @JsonProperty("refresh_expires_in")
  public String refreshExpiresIn;
  @JsonProperty("token_type")
  public String tokenType;
  @JsonProperty("not-before-policy")
  public String not_before_policy;
  public String scope;
}

Quarkus Extension Dev Service Personnalisé - Partie III

Fri, 11 Oct 2024 15:07:03 +0200

Dans le précédent article, nous avons vu comment lancer automatiquement un conteneur exposant une API et relié à sa propre base de données grâce à une extension Quarkus. Nous allons maintenant voir comment communiquer avec cette api depuis notre application principale.

Pour appeler une API, il nous faut son URL !

Dans le précédent article, nous avions sauvegardé l’URL d’accès à notre API dans un RunningDevService. Nous allons maintenant utiliser cette URL pour permettre d’injecter cette valeur dans notre application principale. Pour ce faire, nous allons créer une nouvelle classe nommée DemoClientApiProcessor :

@BuildSteps(onlyIf = { GlobalDevServicesConfig.Enabled.class })
public class DemoClientApiProcessor {

    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    public void createSDK(List<DevServicesResultBuildItem> devServicesResultBuildItem, DemoServiceRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
        // Retrieve config set Inside DemoExtensionProcessor
        String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(DemoServiceContainer.CONTAINER_NAME))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("Can't find Demo-service url"))
                .getConfig().get("url");

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(DemoConfig.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createConfig("http://"+apiUrl))
                .done());
    }


    @BuildStep
    public void addSDKBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans, BuildProducer<AdditionalIndexedClassesBuildItem> additionalIndexedClasses) {
        additionalBeans.produce(new AdditionalBeanBuildItem(DemoService.class));
        additionalIndexedClasses.produce(new AdditionalIndexedClassesBuildItem(DemoService.class.getName()));
    }
}

La méthode createSDK annotée avec @BuildStep, prend en paramètre une liste de DevServicesResultBuildItem. Quarkus appellera donc cette méthode après l’instanciation de nos conteneurs de base de données et d’API. Les autres paramètres sont un DemoServiceRecorder et un BuildProducerde SyntheticBeanBuildItem. Le fonctionnement des recorders et syntheticBean a déjà été couvert dans un autre article. En résumé, On récupère l’URL de l’API depuis object devServicesResultBuildItem et on construit un DemoConfig contenant cette URL qui sera injectable.

Le recorder est définie comme suit :

package info.techland.demo.extension.runtime;

import io.quarkus.runtime.RuntimeValue;
import io.quarkus.runtime.annotations.Recorder;



@Recorder
public class DemoServiceRecorder {

    public RuntimeValue<DemoConfig> createConfig(String url) {
        return new RuntimeValue<>(new DemoConfig(url));
    }
}

Le recorder est défini dans le package runtime de notre extension. Son rôle est d’instancier notre objet DemoConfig avec l’URL passé en paramètre de manière que Quarkus puisse enregistrer le Bytecode en résultant.

package info.techland.demo.extension.runtime;

import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class DemoConfig {

    private String url;

    // Only for CDI injection
    @SuppressWarnings("unused")
    private DemoConfig() {}

    public DemoConfig(String url) {
        this.url = url;
    }

    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }
}

Notre DemoConfig est juste un Bean contenant l’URL de notre API une fois déployé comme devService.

@BuildStep
public void addSDKBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans, BuildProducer<AdditionalIndexedClassesBuildItem> additionalIndexedClasses) {
    additionalBeans.produce(new AdditionalBeanBuildItem(DemoService.class));
    additionalIndexedClasses.produce(new AdditionalIndexedClassesBuildItem(DemoService.class.getName()));
}

Cette étape permet de déclarer notre syntheticBean comme injectable dans notre application finale.

Construire un RestClient dans notre application.

Nous avons maintenant une instance de DemoConfig qui est injectable dans n’importe quelle classe de notre application principale. Commençons par créer une interface pour notre RestClient dans notre application principale afin d’appeler notre API Demo.

package info.techland.demo.app;


@Path("/api")
public interface DemoService {

    @GET
    Set<Demo> fetchAll();
}

/**
 * Somewhere in our principal application...
 */
@Path("")
public class AppResource {

    private DemoConfig demoConfig;
    private final DemoService demoService;

    public AppResource(DemoConfig demoConfig) {
        this.demoConfig = demoConfig;

        demoService = QuarkusRestClientBuilder.newBuilder()
            .baseUri(URI.create(demoConfig.getUrl()))
            .build(ExtensionsService.class);
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Set<Demo> fetchDemo() {
        return this.demoService.fetch();
    }
}

Dans notre application principale, nous injections notre objet DemoConfig contenant l’URL de notre API et nous nous en servons pour configurer un RestClient de manière programmatique. Notre méthode fetchDemo retourne un Set d’object Demo qui est un simple POJO. Notre application principale est maintenant reliée à notre API et le tout de manière automatique. Mais cela peut encore être amélioré. Et si notre RestClient n’était pas créé par notre application principale, mais par notre extension et injectable comme notre DemoConfig ?

Migrer le RestClient dans notre extension

Pour faire cela, c’est assez simple. Dans un premier temps nous allons déplacer notre classe DemoService dans notre extension, dans le package runtime. Ensuite, nous allons créer une classe DemoResource en charge de créer notre RestClient.

package info.techland.demo.extension.runtime;

import io.quarkus.rest.client.reactive.QuarkusRestClientBuilder;
import io.smallrye.mutiny.Uni;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;

import java.net.URI;
import java.util.List;

@Path("/")
public class DemoResource {

    private DemoService demoService;

    // Only for CDI injection
    @SuppressWarnings("unused")
    private DemoResource() {
    }

    public DemoResource(String url) {
        this.demoService = QuarkusRestClientBuilder.newBuilder()
                .baseUri(URI.create(url))
                .build(DemoService.class);
    }

    @GET
    public Set<Demo> fetchAsync() {
        return demoService.fetchAsync();
    }
}

Le POJO Demo est aussi déplacé dans notre extension afin disponible dans n’importe quelle application utilisant notre extension.

Ensuite dans notre DemoServiceRecorder, nous allons ajouter l’instanciation de notre DemoResource :

@Recorder
public class DemoServiceRecorder {

    public RuntimeValue<DemoResource> createSDK(String url) {
        return new RuntimeValue<>(new DemoResource(url));
    }

    public RuntimeValue<DemoConfig> createConfig(String url) {
        return new RuntimeValue<>(new DemoConfig(url));
    }
}

Dernière étape, configurer Quarkus pour injecter notre DemoResource via un SyntheticBean dans notre DemoClientApiProcessor :

@BuildSteps(onlyIf = { GlobalDevServicesConfig.Enabled.class })
public class DemoClientApiProcessor {

    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    public void createSDK(List<DevServicesResultBuildItem> devServicesResultBuildItem, DemoServiceRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
        // Retrieve config set Inside DemoExtensionProcessor
        String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(DemoServiceContainer.CONTAINER_NAME))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("Can't find Demo-service url"))
                .getConfig().get("url");

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(DemoConfig.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createConfig("http://"+apiUrl))
                .done());

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(DemoResource.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createSDK("http://"+apiUrl))
                .done());
    }


    @BuildStep
    public void addSDKBeans(BuildProducer<AdditionalBeanBuildItem> additionalBeans, BuildProducer<AdditionalIndexedClassesBuildItem> additionalIndexedClasses) {
        additionalBeans.produce(new AdditionalBeanBuildItem(DemoService.class));
        additionalIndexedClasses.produce(new AdditionalIndexedClassesBuildItem(DemoService.class.getName()));
    }

    /**
     * A jandex file is mandatory by the maven-quarkus-plugin to resolve CDI dependency in the package phase.
     * At runtime, we need to remove this beans because we provide our own via syntheticBean
     * @param buildExclusionsBuildItemBuildProducer Producer for beans that will be excluded
     */
    @BuildStep
    public void removeJandexDemoBean(BuildProducer<ExcludedTypeBuildItem> buildExclusionsBuildItemBuildProducer) {
        buildExclusionsBuildItemBuildProducer.produce(new ExcludedTypeBuildItem(DemoConfig.class.getName()));
        buildExclusionsBuildItemBuildProducer.produce(new ExcludedTypeBuildItem(DemoResource.class.getName()));
    }
}

Notre RestClient est maintenant utilisable via injection d’un DemoResource dans notre application. Reprenons le code de notre AppResource qui est maintenant beaucoup plus simple :

@Path("")
public class AppResource {

    private final DemoResource demoResource;

    public AppResource(DemoResource demoResource) {
        this.demoResource = demoResource;
    }

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    public Set<Demo> fetchDemo() {
        return this.demoResource.fetch();
    }
}

Conclusion

Voilà qui conclue notre série d’articles sur l’utilisation des extensions Quarkus pour développeur des devs services personnalisés. Pour les consommateurs de nos API, l’utilisation est grandement simplifiée. Un simple import Maven suffit. Un SDK est disponible rendant l’appelle à notre API très simple. Et les évolutions de notre service sont maintenant aussi simple que la mise à jour de la dépendance Maven dans le projet. Lors d’un changement dans notre API cela pourra possiblement être réalisé de manière transparente par le SDK et sinon sera détectable à la compilation via un changement de signature de méthode Java.

Quarkus Extension Dev Service Personnalisé - Partie II

Thu, 10 Oct 2024 15:07:03 +0200

Dans le précédent article, nous avons vu comment lancer une base de données automatiquement grâce à une extension Quarkus. Nous allons maintenant voir comment démarrer notre service de la même manière et lui faire utiliser la base de données que nous venons de déployer. Je ne reviendrai pas sur les points abordés dans le précédent article. Je vous invite donc à le lire avant de continuer.

On prend les mêmes et on recommence.

La création de notre conteneur pour notre service se passe de la même manière que la base de données. On va donc commencer par ajouter les configurations nécessaires à notre DevServicesConfig :

    /**
     * The container image name to use, for container based DevServices providers.
     * If you want to use a specific version of demo, use:
     * {@code demo:<version>}.
     */
    @WithDefault("scandinave/demo")
    String imageName();

    /**
     * Optional fixed port the dev service will listen to.
     * <p>
     * If not defined, the port will be chosen randomly.
     */
    OptionalInt port();

    /**
     * The value of the {@code quarkus-dev-service-demo} label attached to the started container.
     * This property is used when {@code shared} is set to {@code true}.
     * In this case, before starting a container, Dev Services for Demo looks for a container with the
     * {@code quarkus-dev-service-demo} label set to the configured value. 
     * If found, it will use this container instead of starting a new one. Otherwise, it
     * starts a new container with the {@code quarkus-dev-service-demo} label set to the specified value.
     * <p>
     */
    @WithDefault("demo")
    String serviceName();

    /**
     * Environment variables that are passed to the container.
     */
    Map<String, String> containerEnv();

On commence par ajouter une option pour le nom de l’image docker qui servira à démarrer notre conteneur. De cette manière, l’utilisateur pourra choisir une version spécifique s’il le souhaite. Le port est par défaut aléatoire, mais pourra également être précisé. Enfin, le label appliqué au conteneur pourra aussi être personnalisé.

DemoExtensionProcessor

Dans notre DemoExtensionProcessor, nous ajoutons le code permettant d’initialiser le conteneur de notre service.

  @BuildSteps(onlyIf = {GlobalDevServicesConfig.Enabled.class})
  public class DemoExtensionProcessor {
  
    /** stuff from previous article 
     * ...
     */

    private static volatile RunningDevService demoApiDevService;

    @BuildStep
    public void createContainer(DockerStatusBuildItem dockerStatusBuildItem,
                                List<DevServicesSharedNetworkBuildItem> devServicesSharedNetworkBuildItem,
                                DemoBuildTimeConfig buildTimeConfig,
                                GlobalDevServicesConfig devServicesConfig,
                                BuildProducer<DevServicesResultBuildItem> devServicesResult) {

      runningConfiguration = buildTimeConfig.devservices();

      try {
           // DemoApiRunningDevService newAPIDevService = startDemoContainer...
           DemoApiRunningDevService newAPIDevService = startDemoContainer(
                    dockerStatusBuildItem,
                    !devServicesSharedNetworkBuildItem.isEmpty(),
                    devServicesConfig.timeout.orElse(Duration.of(0, ChronoUnit.SECONDS)),
                    runningConfiguration,
                    newDatabaseDevService,
                    errors
            );
          // Get the RunningDevService instance.
          demoApiDevService = newAPIDevService.getRunningDevService();
      } catch (Throwable t) {
          throw new RuntimeException(t);
      }
      Log.info("Dev Services for Demo started.");

      devServicesResult.produce(demoApiDevService.toBuildItem());
    }
  }

Notre méthode startDemoContainer prends en plus en paramètre le résultat de l’appel à la méthode startDatabaseContainer qui contient une instance d’un DevRunningDevService. Dans ce dernier, nous avions enregistré l’URL d’accès à notre base de données. Je vous avais dit que cela servirait plus tard.

return new DevServicesResultBuildItem.RunningDevService(feature, databaseContainer.getContainerId(), databaseContainer::close,
        Map.of(
            "url", databaseContainer.getHost() + ":" + databaseContainer.getPort(),
            "url-internal", databaseContainer.getContainerName().substring(1) + ":" + POSTGRES_INTERNAL_PORT
        )
);

startDemoContainer


private DemoApiRunningDevService startDemoContainer(DockerStatusBuildItem dockerStatusBuildItem, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, DemoDatabaseRunningDevService runningService, List<String> errors) {
    if (!devServicesConfig.enabled()) {
        // explicitly disabled
        Log.debug("Not starting Dev Services for Demo as it has been disabled in the config");
        return null;
    }


    if (!dockerStatusBuildItem.isDockerAvailable()) {
        Log.warn("Please get a working docker instance");
        errors.add("Please get a working docker instance");
        return null;
    }

    String dbUrl = Optional.ofNullable(runningService.getRunningDevService().getConfig()).orElseThrow(() -> new IllegalStateException("Database does not start properly")).get("url-internal");

    final Optional<ContainerAddress> maybeExistingContainer = demoAPIDevModeContainerLocator.locateContainer(
            devServicesConfig.serviceName(),
            devServicesConfig.shared(),
            LaunchMode.current());

    String imageName = devServicesConfig.imageName();
    DockerImageName dockerImageName = DockerImageName.parse(imageName).asCompatibleSubstituteFor(imageName);


    return maybeExistingContainer
            .map(existingContainer -> new DemoApiRunningDevService(new RunningDevService(DemoApiContainer.CONTAINER_NAME, existingContainer.getId(),
                    null, Map.of("url", existingContainer.getHost() + ":" + existingContainer.getPort()))))
            .orElseGet(() -> new DemoApiRunningDevService(useSharedNetwork, timeout, devServicesConfig, dbUrl, dockerImageName, runningService));
}

On commence par les mêmes vérifications concernant la présence de docker et l’activation des dev services puis nous récupérons l’URL interne docker de connexion à la base de données depuis notre instance de RunningDevService. La méthode vérifie ensuite si autre conteneur existe déjà grâce à un nouveau ContainerLocator:

`1`	`private static final ContainerLocator demoAPIDevModeContainerLocator = new ContainerLocator(DemoApiContainer.DEV_SERVICE_LABEL, DEMO_INTERNAL_PORT);`

Si un conteneur de notre service est déjà lancé, alors la méthode retourne un RunningDevService avec les informations du conteneur existant. Sinon un nouveau RunningDevService pour le nouveau conteneur est retourné. Ce nouveau RunningDevService prend en paramètre l’URL de notre base de données.

DemoApiRunningDevService

public class DemoApiRunningDevService {

    private DemoApiContainer demoContainer;
    private final DevServicesResultBuildItem.RunningDevService runningDevServiceSupplier;

    public DemoApiRunningDevService(boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, String dbUrl, DockerImageName
            dockerImageName, DemoDatabaseRunningDevService runningService) {
        runningDevServiceSupplier = this.run(useSharedNetwork, timeout, devServicesConfig, dbUrl, dockerImageName, runningService);
    }

    public DemoApiRunningDevService(DevServicesResultBuildItem.RunningDevService runningDevService) {
        runningDevServiceSupplier = runningDevService;
        demoContainer = null;
    }


    public DevServicesResultBuildItem.RunningDevService run(boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, String dbUrl, DockerImageName dockerImageName, DemoDatabaseRunningDevService runningService) {
        if (devServicesConfig.port().isPresent()) {
            try (DemoApiContainer container = new DemoApiContainer(dockerImageName, devServicesConfig.port().getAsInt(), useSharedNetwork, devServicesConfig.shared(), devServicesConfig.serviceName())) {
                demoContainer = container;
            }
        } else {
            try (DemoApiContainer container = new DemoApiContainer(dockerImageName, useSharedNetwork, devServicesConfig.shared(), devServicesConfig.serviceName())) {
                demoContainer = container;
            }
        }

        Optional.ofNullable(timeout).ifPresent(demoContainer::withStartupTimeout);
        demoContainer.withEnv(devServicesConfig.containerEnv());


        demoContainer.withEnv("POSTGRES_USER", devServicesConfig.db().username());
        demoContainer.withEnv("POSTGRES_PASSWORD", devServicesConfig.db().password());
        demoContainer.withEnv("DB_URL", dbUrl + "/" + devServicesConfig.db().name());
        if (runningService.getDatabaseContainer().isPresent()) { // Wait for database container to start. If container is null, it means that a database was already started so no need to wait.
            demoContainer.withNetwork(runningService.getDatabaseContainer().get().getNetwork());
            demoContainer.dependsOn(runningService.getDatabaseContainer().get());
        }

        demoContainer.start();

        return new DevServicesResultBuildItem.RunningDevService(DemoApiContainer.CONTAINER_NAME, demoContainer.getContainerId(),
                demoContainer::close, Map.of("url", demoContainer.getHost() + ":" + demoContainer.getPort()));

    }

    public Optional<GenericContainer<DemoApiContainer>> getDatabaseContainer() {
        return Optional.ofNullable(demoContainer);
    }

    public DevServicesResultBuildItem.RunningDevService getRunningDevService() {
        return runningDevServiceSupplier;
    }
}

Notre classe définit deux constructeurs. Un renvoyant juste le RunningDevService existant dans le cas où le conteneur existe déjà. Le deuxième, créant un nouveau RunningDevService. Notre méthode run commence par vérifier si un port est précisé dans la configuration du dev-service. Si c’est le cas, notre conteneur sera démarré sur ce port, sinon, un port aléatoire disponible sera alloué (comportement par défaut).

Une fois l’instance de notre DemoApiConteneur créée, nous le configurons en lui passant les variables d’environnement qu’il attend grâce à la méthode withEnv. Nous utilisons pour cela notre devServiceConfig pour récupérer les identifiants de connexion à la base de données puis l’URL passée en paramètre. Ensuite, nous configurons le conteneur sur le même réseau que la base de données et pour attendre que celle-ci ait fini de démarrer.

Enfin, nous retournons notre RunninDevService contenant l’ID de notre conteneur ainsi que de la configuration contenant l’URL d’accès à notre API qui nous sera également utile pour la suite.

DemoApiContainer

Il ne nous reste plus qu’à voir la classe DemoApiContainer pour finir ce second post sur la création d’un DevService avec Quarkus.

import io.quarkus.devservices.common.ConfigureUtil;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

public class DemoApiContainer extends GenericContainer<DemoApiContainer> {

    public static final String CONTAINER_NAME = "demo";
    public static final String DEV_SERVICE_LABEL="quarkus-dev-service-demo";
    private final Integer exposedPort;
    public static final int DEMO_INTERNAL_PORT = 8600;
    private final boolean useSharedNetwork;
    private final String serviceName;
    private String hostname;
    private final boolean sharedContainer;

    public DemoApiContainer(DockerImageName image, boolean useSharedNetwork, boolean isShared, String serviceName) {
        this(image, null, useSharedNetwork, isShared, serviceName);
    }

    public DemoApiContainer(DockerImageName image, Integer exposedPort, boolean useSharedNetwork, boolean isShared, String serviceName) {
        super(image);
        this.exposedPort = exposedPort;
        this.useSharedNetwork = useSharedNetwork;
        this.sharedContainer = isShared;
        this.serviceName = serviceName;


    }

    @Override
    protected void configure() {
        super.configure();

        if (this.useSharedNetwork) {
            hostname = ConfigureUtil.configureSharedNetwork(this, "demo");
        }

        if(this.exposedPort != null) {
          addFixedExposedPort(this.exposedPort, DEMO_INTERNAL_PORT);
          if(useSharedNetwork) {
              // expose random port for which we are able to ask Testcontainers for the actual mapped port at runtime
              // as from the host's perspective Testcontainers actually expose container ports on random host port
              addExposedPort(DEMO_INTERNAL_PORT);
          }
        } else {
            addExposedPort(DEMO_INTERNAL_PORT);
        }

        withLabel(DEV_SERVICE_LABEL, serviceName);

        // Tell the dev service how to know the container is ready
        waitingFor(Wait.forLogMessage(".*demo.*started.*", 1));
    }

    @Override
    public String getHost() {
        if(this.useSharedNetwork) {
            return hostname;
        }
        return super.getHost();
    }

    public int getPort() {
        if (useSharedNetwork) {
            return DEMO_INTERNAL_PORT;
        }
        if (exposedPort != null) {
            return exposedPort;
        }
        return getFirstMappedPort();
    }
}

Je ne m’attarderai pas sur cette classe qui est identique à celle de notre DemoDatabaseContainer. Seule l’attente de l’événement indiquant la fin du démarrage du processus dans le conteneur est différente. Ici, nous attendons un log dans notre application contenant les mots demo et started

Conclusion

Notre extension lance maintenant un service “dockerisé” avec sa base de données. Le tout configuré automatiquement pour fonctionner ensemble. Comme nous avions déjà inclus l’extension lors de la précédente étape, nous n’avons rien de plus à faire pour profiter de cette mise à jour.

Dans un prochain article, nous verrons comment dialoguer avec notre API grâce à l’URL sauvegardée dans notre RunningDevService et comment fournir un SDK permettant d’exploiter cette API via une simple injection de dépendances dans notre application cliente.

Quarkus Extension Dev Service Personnalisé - Partie I

Tue, 08 Oct 2024 22:34:03 +0200

Aujourd’hui, on s’attaque à un gros morceau avec un cas d’usage non documenté par Quarkus, mais qui est vraiment très pratique. Quarkus propose des extensions avec des “dev services”. Ces extensions, une fois incluses dans votre projet, lancent des services automatiquement au démarrage du projet en mode dev. Nous allons voir comment créer notre propre “dev service” pour nos applications Quarkus. L’idée est de fournir une extension pour chacun de nos services afin de les rendre utilisables facilement par des tiers.

Cas d’usage

Imaginons une entreprise avec plusieurs projets et plusieurs équipes. Il arrive souvent que des services soient communs à plusieurs projets. Deux solutions sont généralement mises en place.

Une instance de dev partagée
Un docker compose à lancer en parallèle du projet en mode dev.

La première solution implique une administration compliquée avec une gestion des données entres plusieurs équipes. Si une équipe casse le service, cela impact les autres équipes. Lors d’une mise à jour, l’ensemble des équipes sont également impactées.

La seconde solution est plus flexible, les services s’exécutant sur le poste du développeur. Cependant, cela implique une étape supplémentaire au lancement du projet en mode dev. Cela pose aussi la question de la mise à jour du docker compose.

Un “dev service” permet de résoudre ces problèmes. Distribuer sous la forme d’une extension Maven, ils peuvent être maintenus à jour via l’utilisation d’un bom Maven. Quarkus les démarrent automatiquement au démarrage du projet, éliminant le besoin de gérer manuellement des conteneurs docker.

L’extension

Notre extension devra pouvoir démarrer un service Quarkus avec sa base de données. L’extension devra permettre d’exécuter le service avec des paramètres par défaut et de permettre de les personnaliser.

Commençons par créer l’extension via la commande :

1
2
3

mvn io.quarkus.platform:quarkus-maven-plugin:3.14.4:create-extension -N \
    -DgroupId=info.techland \
    -DextensionId=demo-extension

Cela va nous créer une extension avec l’arborescence suivante :

demo-extension
|__ deployment
|__ integration-tests
|__ runtime
|__ pom.xml

À la fin l’architecture de notre extension ressemblera au schéma suivant :

Schéma de notre extension pour la base de données

Création de la base de données de notre dev service

Notre service a besoin d’une base de données pour fonctionner. Nous allons donc configurer notre extension pour lancer une base de données dans un conteneur Docker. Avant cela commençons par créer quelques configurations pour notre extension afin de la rendre personnalisable.

DemoExtensionBuildTimeConfig

package info.techland.demo.extension.deployment;

import io.quarkus.runtime.annotations.ConfigPhase;
import io.quarkus.runtime.annotations.ConfigRoot;
import io.smallrye.config.ConfigMapping;


@ConfigMapping(prefix = "quarkus.demo")
@ConfigRoot(phase = ConfigPhase.BUILD_TIME)
public interface DemoExtensionBuildTimeConfig {

    /**
     * Dev services configuration.
     */
    DevServicesConfig devservices();

}

Cette classe enregistre le point d’entrée de la configuration de notre dev service. Notre configuration sera accessible dans l’application.properties sous la clé quarkus.demo.

DevServiceConfig

package info.techland.demo.extension.deployment;

import java.util.Map;

import io.quarkus.runtime.annotations.ConfigGroup;
import io.smallrye.config.WithDefault;

@ConfigGroup
public interface DevServicesConfig {

    /**
     * If DevServices has been explicitly enabled or disabled. DevServices is generally enabled
     * by default, unless there is an existing configuration present.
     * <p>
     * When DevServices is enabled Quarkus will attempt to automatically configure and start
     * a demo instance when running in Dev or Test mode and when Docker is running.
     */
    @WithDefault("true")
    boolean enabled();


    /**
     * Indicates if the demo server managed by Quarkus Dev Services is shared.
     * When shared, Quarkus looks for running containers using label-based service discovery.
     * If a matching container is found, it is used, and so a second one is not started.
     * Otherwise, Dev Services for demo starts a new container.
     * <p>
     * The discovery uses the {@code quarkus-dev-service-redis} label.
     * The value is configured using the {@code service-name} property.
     * <p>
     * Container sharing is only used in dev mode.
     */
    @WithDefault("true")
    boolean shared();

    /**
     * The value of the {@code quarkus-dev-service-demo} label attached to the started container.
     * This property is used when {@code shared} is set to {@code true}.
     * In this case, before starting a container, Dev Services for demo looks for a container with the
     * {@code quarkus-dev-service-demo} label
     * set to the configured value. If found, it will use this container instead of starting a new one. Otherwise, it
     * starts a new container with the {@code quarkus-dev-service-demo} label set to the specified value.
     * <p>
     * This property is used when you need multiple shared demo servers.
     */
    @WithDefault("demo")
    String serviceName();

    /**
     * Environment variables that are passed to the container.
     */
    Map<String, String> containerEnv();

    /**
     * Configuration for the postgresql database use by demo service.
     * @return The database configuration
     */
    DatabaseConfig db();
}

Cette classe configure notre dev service avec l’accès à la configuration de notre base de données du dev service. La configuration de notre base de données sera accessible sous la clé quarkus.dev.db. Chaque entrée à une valeur par défaut afin de permettre l’utilisation de l’extension sans configuration particulière.

DatabaseConfig

package info.techland.demo.extension.deployment;

import io.quarkus.runtime.annotations.ConfigGroup;
import io.smallrye.config.WithDefault;

import java.util.Map;
import java.util.OptionalInt;

@ConfigGroup
public interface DatabaseConfig {

    /**
     * The database password used by the demo service.
     */
    @WithDefault("demo")
    String username();

    /**
     * The database password used by the demo service.
     */
    @WithDefault("demo")
    String password();

    /**
     * The database name used by the demo service
     */
    @WithDefault("demo")
    String name();

    /**
     * The number of reactive connection to use.
     */
    @WithDefault("20")
    int reactiveMaxSize();

    /**
     * The port used by the database.
     * @return The database port
     */
    OptionalInt port();

    /**
     * Name of the postgresql image to use to start the database
     * @return The image name.
     */
    @WithDefault("docker.io/postgres")
    String imageName();

    /**
     * Environment variables that are passed to the container.
     */
    Map<String, String> containerEnv();
}

La configuration de la base de données contient les informations de connexion à la base de données PostgreSQL utilisée par défaut. Encore une fois, nous privilégions les conventions sur la configuration en appliquant des valeurs par défaut.

DemoExtensionProcessor

Pour demander à Quarkus de démarrer un conteneur, nous allons devoir configurer notre DemoExtensionProcessor. Commençons par ajouter une méthode createContainer qui fera office de @BuildStep pour démarrer et configurer notre conteneur.

  @BuildSteps(onlyIf = {GlobalDevServicesConfig.Enabled.class})
  public class DemoExtensionProcessor {
  
    /**
     * The current configuration. either from running container instance or an instance that is about to start.
     */
    private static volatile DevServicesConfig runningConfiguration;
    private static volatile RunningDevService demoDatabaseDevService;

    @BuildStep
    public void createContainer(DockerStatusBuildItem dockerStatusBuildItem,
                                List<DevServicesSharedNetworkBuildItem> devServicesSharedNetworkBuildItem,
                                DemoBuildTimeConfig buildTimeConfig,
                                GlobalDevServicesConfig devServicesConfig,
                                BuildProducer<DevServicesResultBuildItem> devServicesResult) {

      runningConfiguration = buildTimeConfig.devservices();

      try {
          List<String> errors = new ArrayList<>();
          DemoDatabaseRunningDevService newDatabaseDevService = startDatabaseContainer(
                  dockerStatusBuildItem,
                  !devServicesSharedNetworkBuildItem.isEmpty(),
                  devServicesConfig.timeout.orElse(Duration.of(0, ChronoUnit.SECONDS)),
                  runningConfiguration,
                  errors
          );


          // Get the RunningDevService instance.
          demoDatabaseDevService = newDatabaseDevService.getRunningDevService();
      } catch (Throwable t) {
          throw new RuntimeException(t);
      }
      Log.info("Dev Services for Demo started.");

      // Call to toBuildItem method to get the DevServicesResultBuildItem need by the BuildStep producer.
      devServicesResult.produce(demoDatabaseDevService.toBuildItem());
    }
  }

Notre méthode se voit injecter les builds items suivants :

DockerStatusBuildItem : Permet de récupérer le statut d’une instance docker
DevServicesSharedNetworkBuildItem : Détermine si les conteneurs sont démarrés sur un réseau partagé
DemoBuildTimeConfig : La configuration de notre extension
GlobalDevServicesConfig : La configuration globale des devservices fournie par Quarkus
DevServicesResultBuildItem : Le buildItem à produire pour référencer notre conteneur auprès de Quarkus

Notre méthode appelle ensuite la méthode startDatabaseContainer chargée de créer une instance de DemoDatabaseRunningDevService. Cette dernière est en charge de fournir un RunningDevService, via devServicesResult.produce(demoDatabaseDevService.toBuildItem()), qui sera retourné par notre @BuildStep pour demander à Quarkus de lancer un conteneur.

startDatabaseContainer


private DemoDatabaseRunningDevService startDatabaseContainer(DockerStatusBuildItem dockerStatusBuildItem, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, List<String> errors) {
    if (!devServicesConfig.enabled()) {
        // explicitly disabled
        Log.debug("Not starting Dev Services for Demo as it has been disabled in the config");
        return null;
    }


    if (!dockerStatusBuildItem.isDockerAvailable()) {
        Log.warn("Please get a working docker instance");
        errors.add("Please get a working docker instance");
        return null;
    }

    final Optional<ContainerAddress> maybeExistingContainer = demoDBDevModeContainerLocator.locateContainer(
            devServicesConfig.serviceName() + "_db",
            devServicesConfig.shared(),
            LaunchMode.current());

    // Get the image name from the configuration.
    String imageName = devServicesConfig.db().imageName();
    DockerImageName dockerImageName = DockerImageName.parse(imageName).asCompatibleSubstituteFor(imageName);

    return maybeExistingContainer
            .map(existingContainer -> new DemoDatabaseRunningDevService(new RunningDevService(DemoDatabaseContainer.CONTAINER_NAME, existingContainer.getId(),
                    null, Map.of("url", existingContainer.getHost() + ":" + existingContainer.getPort()))))
            .orElseGet(() -> new DemoDatabaseRunningDevService(DemoDatabaseContainer.CONTAINER_NAME, useSharedNetwork, timeout, devServicesConfig,
                    dockerImageName, devServicesConfig.serviceName() + "_db"));
}

On commence par quelques vérifications. Si les devservices sont désactivés de manière globale, on annule le lancement et si docker n’est pas disponible, on retourne une erreur. La méthode vérifie ensuite si un autre conteneur existe déjà. Cela peut être le cas, si deux services Quarkus utilise la même extension. Cela se fait grâce à un ContainerLocator:

`1`	`private static final ContainerLocator demoDBDevModeContainerLocator = new ContainerLocator(DemoDatabaseContainer.DEV_SERVICE_LABEL, POSTGRES_INTERNAL_PORT);`

Si un conteneur de notre base de données est déjà lancé, alors la méthode retourne un RunningDevService avec les informations du conteneur existant. Sinon un nouveau RunningDevService pour le nouveau conteneur est retourné.

DemoDatabaseRunningDevService

public class DemoDatabaseRunningDevService {

    private DemoDatabaseContainer databaseContainer;
    private final DevServicesResultBuildItem.RunningDevService runningDevServiceSupplier;

    public DemoDatabaseRunningDevService(String feature, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, DockerImageName
            dockerImageName, String serviceName) {
        runningDevServiceSupplier = this.run(feature, useSharedNetwork, timeout, devServicesConfig, dockerImageName, serviceName);
    }

    public DemoDatabaseRunningDevService(DevServicesResultBuildItem.RunningDevService runningDevService) {
        runningDevServiceSupplier = runningDevService;
        databaseContainer = null;
    }

    public DevServicesResultBuildItem.RunningDevService  run(String feature, boolean useSharedNetwork, Duration timeout, DevServicesConfig devServicesConfig, DockerImageName
            dockerImageName, String serviceName) {

        if(devServicesConfig.db().port().isPresent()) {
            databaseContainer = new DemoDatabaseContainer(dockerImageName, devServicesConfig.db().port().getAsInt(), useSharedNetwork, serviceName);
        } else {
            databaseContainer = new DemoDatabaseContainer(dockerImageName, useSharedNetwork, serviceName);
        }

        Optional.ofNullable(timeout).ifPresent(databaseContainer::withStartupTimeout);
        databaseContainer.withEnv(devServicesConfig.db().containerEnv());


        databaseContainer.withEnv("POSTGRES_USER", devServicesConfig.db().username());
        databaseContainer.withEnv("POSTGRES_PASSWORD", devServicesConfig.db().password());
        databaseContainer.withEnv("POSTGRES_DB",devServicesConfig.db().name());
        databaseContainer.withNetwork(useSharedNetwork ? Network.SHARED : Network.newNetwork());
        databaseContainer.start();

        return new DevServicesResultBuildItem.RunningDevService(feature, databaseContainer.getContainerId(),
                databaseContainer::close,
                Map.of(
                    "url", databaseContainer.getHost() + ":" + databaseContainer.getPort(),
                    "url-internal", databaseContainer.getContainerName().substring(1) + ":" + POSTGRES_INTERNAL_PORT
                )
        );

    }

    public Optional<GenericContainer<DemoDatabaseContainer>> getDatabaseContainer() {
        return Optional.ofNullable(databaseContainer);
    }

    public DevServicesResultBuildItem.RunningDevService getRunningDevService() {
        return runningDevServiceSupplier;
    }
}

Une fois l’instance de notre DemoDatabaseConteneur créée, nous le configurons en lui passant les variables d’environnement qu’il attend grâce à la méthode withEnv. Vient ensuite la configuration du réseau docker utilisé. Dans le cas où l’utilisateur à expressement spécifié que les conteneurs devait être attachés au réseau partagé créé par TestContainer, nous utilisons la méthode withNetwork avec la valeur Network.SHARED. Dans le cas contraire, un nouveau réseau est créé pour le conteneur.

Enfin, nous retournons notre RunninDevService contenant l’ID de notre conteneur ainsi que de la configuration qui nous sera utile par la suite.

DemoDatabaseContainer

Il ne nous reste plus qu’à voir la classe DemoDatabaseContainer pour finir ce premier post sur la création d’un DevService avec Quarkus.

import io.quarkus.devservices.common.ConfigureUtil;
import org.testcontainers.containers.GenericContainer;
import org.testcontainers.containers.wait.strategy.Wait;
import org.testcontainers.utility.DockerImageName;

public class DemoDatabaseContainer extends GenericContainer<DemoDatabaseContainer> {


    public static final String CONTAINER_NAME="demo-db";
    private static final String DEV_SERVICE_LABEL="quarkus-dev-service-db";
    private final String serviceName;
    private final Integer fixedExposedPort;
    public final static int POSTGRES_INTERNAL_PORT = 5432;
    private final boolean useSharedNetwork;
    private String hostname;

    public DemoDatabaseContainer(DockerImageName image, boolean useSharedNetwork, String serviceName) {
        this(image, null, useSharedNetwork, serviceName);
    }

    public DemoDatabaseContainer(DockerImageName image, Integer exposedPort, boolean useSharedNetwork, String serviceName) {
        super(image);
        this.fixedExposedPort = exposedPort;
        this.useSharedNetwork = useSharedNetwork;
        this.serviceName = serviceName;
    }

    @Override
    protected void configure() {
        super.configure();

        if (this.useSharedNetwork) {
            hostname = ConfigureUtil.configureSharedNetwork(this, "demo");
            return;
        }

        if(this.fixedExposedPort != null) {
          addFixedExposedPort(this.fixedExposedPort, POSTGRES_INTERNAL_PORT);
        } else {
            addExposedPort(POSTGRES_INTERNAL_PORT);
        }

        withLabel(DEV_SERVICE_LABEL, serviceName);

        super.setWaitStrategy(Wait.forListeningPorts(POSTGRES_INTERNAL_PORT));
    }

    @Override
    public String getHost() {
        if(this.useSharedNetwork) {
            return hostname;
        }
        return super.getHost();
    }

    public int getPort() {
        if (useSharedNetwork) {
            return POSTGRES_INTERNAL_PORT;
        }
        if (fixedExposedPort != null) {
            return fixedExposedPort;
        }
        return getFirstMappedPort();
    }
}

Cette classe étend de GenericContainer et contient la configuration utilisée par TestContainer pour démarrer notre conteneur Docker. Dans la méthode configure, on commence par regarder si le conteneur doit utiliser le Shared Network. Si c’est le cas ConfigureUtil.configureSharedNetwork se charge de tout configurer correctement. Dans le cas contraire, on configure le port (fixe ou aléatoire), on ajoute un label et on précise sur quel port écouter pour savoir quand le service a terminé de démarrer.

Conclusion

Notre extension de base de données est maintenant fonctionnelle. Cette dernière fournit une implémentation d’un GénericContainer au travers d’un RunningDevService à notre DemoExtensionProcessor. Le tout est personnalisable via la configuration classique de Quarkus. Il nous suffit d’inclure l’extension dans une application quarkus via un import Maven pour avoir la base de données démarrée en parallèle.

Dans un prochain article, nous verrons comment lancer un service dans son propre conteneur utilisant cette base de données pour exposer une API à notre application Quarkus.

Backstage oidc Provider

Wed, 25 Sep 2024 08:40:03 +0200

Backstage est un formidable outil de tableau de bord pour les développeurs. Son système de plugin le rends particulièrement flexible. Cependant la configuration de ces plugins peut s’avérer fastidueuse. Backstage est en constante évolution, ce qui fait que la documentation à parfois du mal à suivre. C’est le cas depuis la migration vers le nouveau Backend system. Backstage dispose de plusieurs plugin permettant de se connecter à la majorité des providers d’identité via OIDC. Toutefois, si vous souhaitez connecter backstage à un provider personnalisé comme un Keycloak d’entreprise la documentation n’est pas vraiment clair. C’est ce que nous allons voir dans ce post.

Création du plugin

Backstage fournis un provider OIDC mais pas de plugin prêt à l’emploi. Nous allons devoir créer un module pour étendre le plugin Auth de backstage avec notre support de OIDC. Nous utilisons la CLI de backstage pour cela

1
2
3

backstage-cli new --select backend-module
# ? Enter the ID of the plugin [required] : auth
# ? Enter the ID of the module [required] : oidc

Backstage à maintenant générer une structure de plugin dans le dossier plugins/auth-backend-module-oidc. Commençons par ajouter la dépendences au provider OIDC fournis par Backstage

1
2

cd plugins/auth-backend-module-oidc
yarn add @backstage/plugin-auth-backend-module-oidc-provider

Une fois cela fait, dans le fichier src/module.ts, remplacer le contenu par le suivant:

import { oidcAuthenticator } from '@backstage/plugin-auth-backend-module-oidc-provider';
import { authProvidersExtensionPoint, createOAuthProviderFactory } from '@backstage/plugin-auth-node'
import {
  coreServices,
  createBackendModule,
} from '@backstage/backend-plugin-api';
import { DEFAULT_NAMESPACE, stringifyEntityRef } from '@backstage/catalog-model';

export const authModuleOidc = createBackendModule({
  pluginId: 'auth',
  moduleId: 'oidc',
  register(reg) {
    reg.registerInit({
      deps: { logger: coreServices.logger, providers: authProvidersExtensionPoint },
      async init({ logger, providers }) {
        logger.info('Registering OIDC provider!');
        providers.registerProvider({
          providerId: 'sso-auth-provider',
          factory: createOAuthProviderFactory({
            authenticator: oidcAuthenticator,
            async signInResolver(info, ctx) {
              const userRef = stringifyEntityRef({
                kind: 'User',
                name: info.result.fullProfile.userinfo.sub,
                namespace: DEFAULT_NAMESPACE
              });
              return ctx.issueToken({
                claims: {
                  sub: userRef, // The user's own identity
                  ent: [userRef], // A list of identities that the user claims ownership through
                }
              });
            }
          })
        });
      },
    });
  },
});

Notre plugin est maintenant opérationel. Vérifions que le module est bien activé dans packages/backend/index.ts. La ligne suivant doit être présente :

`1`	`backend.add(import('backstage-plugin-auth-backend-module-oidc'))`

Configuration de l’Api Factory

Nous allons maintenant référencer le plugin comme API d’autentification dans le front. Pour cela ajouter le code suivant dans le fichier packages/app/src/apis.ts :

import {
  AnyApiFactory,
  ApiRef,
  BackstageIdentityApi,
  configApiRef,
  createApiFactory,
  createApiRef,
  discoveryApiRef,
  oauthRequestApiRef,
  OpenIdConnectApi,
  ProfileInfoApi,
  SessionApi,
} from '@backstage/core-plugin-api';
import { OAuth2 } from '@backstage/core-app-api';

export const oidcAuthApiRef: ApiRef <
  OpenIdConnectApi & // The OIDC API that will handle authentification
  ProfileInfoApi & // Profile API for requesting user profile info from the auth provider in question
  BackstageIdentityApi & // Backstage Identity API to handle and associate the user profile with backstage identity
  SessionApi // Sesssion API, to handle the session the user will have while logged in
> = createApiRef({
  id: 'sso-auth-provider' // Can be anything as long as it doesn't conflict with other API ref IDs
})

export const apis: AnyApiFactory[] = [
  createApiFactory({
    api: oidcAuthApiRef,
    deps: {
      discoveryApi: discoveryApiRef,
      oauthRequestApi: oauthRequestApiRef,
      configApi: configApiRef
    },
    factory: ({ discoveryApi, oauthRequestApi, configApi }) => Oauth2.create({
      configApi,
      discoveryApi,
      oauthRequestApi,
      provider: {
        id: 'sso-auth-provider',
        title: 'Enterprise SSO',
        icon: () => null
      },
      environment: configApi.getOptionalString('auth.environment'),
      defaultScopes: ['openId', 'profile', 'email'],
      popupOptions: {
        size: {
          // fullscreen: true
          // or specify popup width and height
          width: 1000,
          height: 1000,
        }
      }
    })
  }),
  // Other createApiFactory
]

Ajout du bouton de connexion dans l’interface

Allons maintenant dans le fichier packages/app/src/App.tsx pour ajouter le bouton de connexion à backstage.

import { apis, oidcAuthApiRef } from './apis';
import { configApiRef, useApi } from '@backstage/core-plugin-api';

const app = createApp({
  // Other stuff...
  components: {
    SignInPage: props => (<SignInPage {...props} auto providers={ useApi(configApiRef).getString('auth.environment') === 'development' ? ['guest'] : [{
      id: 'sso-auth-provider',
      title: 'Enterprise SSO',
      message: 'Sign in with Enterprise SSO',
      apiRef: oidcAuthApiRef
    }]}/>)
  }
  // Other stuff...
})

Ajoutez la configuration suivante dans votre fichier app-config.local.yaml:

1
2

auth:
  environment: development

et dans le fichier app-config.production.yaml

auth:
  environment: production
  providers:
    guest: {}
    sso-auth-provider:
      production:
        metadataUrl: ${AUTH_REALM_URL}/.well-known/openid-configuration
        clientId: ${AUTH_MY_CLIENT_ID}
        clientSecret: ${AUTH_MY_CLIENT_SECRET}

Avec la configuration ci-dessus, l’authentification se fera comme guest en mode developement et via SSO en mode production. Pour plus d’information, vous pouvez consulter la documentation officielle

Félicitation votre application backstage supporte maintenant la connexion via OIDC. Jetez également un œil à l’intégration Keycloak pour l’import automatique des utilisateurs et des groupes dans Backstage.

Quarkus Extension Synthetic Build Item

Sun, 07 Jul 2024 12:29:05 +0200

Dans le précédent post sur le buildItem AdditionalBeanBuildItem, nous avons vu comment référencer un bean au gestionnaire de dépendance ARC. Cela est très pratique, mais dans certains cas, nous voulons pouvoir que le gestionnaire injecte une instance spécifique d’un bean déjà configuré. L’AdditionalBeanBuildItem ne prenant qu’une classe de bean en paramètre, il ne peut pas être utilisé pour cela. C’est ici qu’intervient le SyntheticBeanBuildItem

Cas d’usage.

Imaginons que votre extension souhaite fournir une configuration sous forme d’un bean injectable pour aller communiquer avec une API tierce. Il va falloir dire à Quarkus quelle instance de bean injecter et avec quelles valeurs.

SyntheticBeanBuildItem

Le nom de ce buildItem n’est pas très parlant et j’ai mis pas mal de temps à comprendre à quoi il pouvait bien servir. En résumé, il s’agit d’un AdditionalBeanBuildItem prenant une instance de classe au lieu d’une classe en paramètre. Cela le rend très puissant. Pour produire une instance de classe, il va tout d’abord falloir fournir cette instance sous la forme d’un Recorder.

Recorder

Commençons par créer notre Bean de configuration d’API dans le module runtime de notre extension :

@ApplicationScoped
public class Config {

    private String url;

    // Only for CDI injection during mvn package phase
    @SuppressWarnings("unused")
    private Config() {}

    public Config(String url) {
        this.url = url;
    }

    public String getUrl() {
        return url;
    }

    public void setUrl(String url) {
        this.url = url;
    }
}

Notre bean doit être “CDI compatible”. Pour cela, il doit comporter un constructeur par défaut ainsi que des accesseurs. Dans notre cas, nous utilisons un constructeur par défaut privé pour que la classe ne puisse pas être utilisée d’une manière non prévue. Le plugin maven quarkus vérifie la présence des Bean injectable lors de la phase de package. Sans ce constructeur par défaut le build de notre projet plante avec une erreur Unsatisfied dependency. Nous définissons notre bean en scope @ApplicationScoped pour que la même instance soit toujours injectée.

Créons maintenant le recorder pour notre classe Config :

@Recorder
public class ConfigRecorder {

    public RuntimeValue<Config> createConfig(String url) {
        return new RuntimeValue<>(new Config(url));
    }
}

Lorsque qu’un recorder est déclaré, Quarkus va exécuter le recorder lors de la phase de build et enregistrer le bytecode produit par ce recorder. Lors de la phase de runtime, quarkus fournira se bytecode directement au lieu d’avoir à le recalculer dynamiquement. Cela permet d’accélérer grandement le temps de démarrage. Dans notre exemple, le recorder retourne un object RuntimeValue<Config> contenant l’instance de notre configuration. Ce RuntimeValue sera consommer par notre SyntheticBeanBuildItem.

BuildStep

    @Record(ExecutionTime.RUNTIME_INIT)
    @BuildStep
    public void createConfig(List<DevServicesResultBuildItem> devServicesResultBuildItem, ConfigRecorder recorder, BuildProducer<SyntheticBeanBuildItem> syntheticBeanBuildItemBuildProducer) {
        // Retrieve config set Inside ApiContainer
        String apiUrl = devServicesResultBuildItem.stream().filter(devService -> devService.getName().equals(ApiContainer.CONTAINER_NAME))
                .findFirst()
                .orElseThrow(() -> new IllegalStateException("Can't find api url"))
                .getConfig().get("url");

        syntheticBeanBuildItemBuildProducer.produce(SyntheticBeanBuildItem.configure(ConfigRecorder.class)
                .unremovable()
                .setRuntimeInit()
                .runtimeValue(recorder.createConfig("http://"+apiUrl))
                .done());
    }

Pour configurer notre syntheticBuildItem nous utilisons une méthode annotée avec @Record(ExecutionTime.RUNTIME_INIT). Ici, le ExecutionTime.STATIC_INIT ne fonctionnera pas, car notre recorder ne sera pas encore disponible. Ensuite, nous récupérons notre URL d’API via un DevServicesResultBuildItem dont nous parlerons dans un prochain article. Une fois l’url de l’API récupérée, nous construisons notre SyntheticBeanBuildItem avec notre recorder. La méthode unremovable s’assure que notre instance de bean ne sera pas supprimer par Quarkus lors de la compilation de notre extension même si ce bean n’est pas utilisé. Sans cela, notre bean ne sera pas accessible dans le module maven important notre extension. Comme nous avons utilisé @Record(ExecutionTime.RUNTIME_INIT), nous informons Quarkus que notre instance de bean sera disponible lors de la phase RuntimeInit grâce à la méthode setRuntimeInit. Enfin, nous passons l’instance de notre bean de config à la méthode runtimeValue pour finir d’initialiser notre SyntheticBeanBuildItem.

Si vous n’avez pas le contrôle sur la classe du bean produit, vous pouvez ajouter un qualifier manquant via la méthode .addQualifier(ApplicationScoped.class)

Injection du Bean

Dans un projet important notre extension :

<dependency>
    <groupId>org.example</groupId>
    <artifactId>example-extension</artifactId>
    <version>1.0-SNAPSHOT</version>
</dependency>

Nous pouvons maintenant injecter notre Bean de configuration pour l’utiliser :

public class MyClassExample {

    private final Config config;

    public MyClassExample(Config config) {
        this.config = config;
    }
}

## Conclusion

Un SyntheticBeanBuildItem est le pendant dynamique de l’AdditionalBeanBuildItem. Il utilise un Recorder pour enregistrer le bytecode produit par notre instance lors de la phase de Build de quarkus. Ce bytecode sera fournis tel quel lors de l’exécution de l’application afin d’accélérer son démarrage.

Test JUnit avec un mock de Keycloak

Wed, 29 May 2024 07:55:31 +0200

J’ai récemment dû implémenter une bibliothèque permettant de valider un JWT dans le cadre d’une authentification OIDC avec Keycloak. Afin de tester que ma bibliothèque fonctionnait correctement au niveau de la partie validation du token, j’ai dû générer un token signé. Ma bibliothèque utilise la bibliothèque de Keycloak pour la vérification. Celle de keycloak fait appel au well-known pour récupérer les informations sur la clé RSA qui a servi à signer les tokens. Voyons un peu comment faire tout cela sans avoir à démarrer et à configurer un Keycloak entier juste pour des tests.

Mock de keycloak

Pour commencer, nous allons devoir mock l’appel au endpoint well-known de Keycloak réalisé par la bibliothèque. Pour cela, nous allons utiliser MockServer. Commençons par ajouter la dépendance à notre pom.xml.

<dependency>
    <groupId>org.mock-server</groupId>
    <artifactID>mockserver-netty</artifactId>
    <version>5.15.0</version>
    <scope>test</scope>
</dependency>

Une fois, ceci fait, on va configurer le mock server pour exposer un endpoint well-known à la place de keycloak.

Class OIDCTest {

    private static ClientAndServer mockServer;
    private static final int KEYCLOAK_PORT=8080

    @BeforeAll
    public static void beforeAll() {
        mockServer = ClientAndServer.startClientAndServer(KEYCLOAK_PORT);
        MockServerClient mockServerClient = new MockServerClient("localhost", KEYCLOAK_PORT);
        mockServerClient.when(HttpRequest.request()
                .withMethod("GET")
                .withPath("/realms/exemple/.well-known/openid-configuration")
                .withHeader("accept", "application/json"))
            .respond(HttpResponse.response()
                .withStatusCode(200)
                .withBody("{ \"jwks_uri\": \"http://localhost:8080/realms/example/protocol/openid-connect/certs\","
                + "\"authorization_endpoint\": \"http://localhost:8080/realms/example/protocol/openid-connect/auth\","
                + "\"issuer\": \"http://localhost:8080/realms/example\","
                + "\"token_endpoint\": \"http://localhost:8080/realms/example/protocol/openid-connect/token\","
                + "\"userinfo_endpoint\": \"http://localhost:8080/realms/example/protocol/openid-connect/userinfo\","
                + "\"end_session_endpoint\": \"http://localhost:8080/realms/example/protocol/openid-connect/logout\""
                + "}"));
    }

    @AfterAll
    public static void afterAll() {
        mockServer.stop();
    }
}

On commence par instancier le mock server sur le port utilisé par défaut par Keycloak. Ensuite, nous utilisons le client de ce mock pour configurer le serveur. En cas de requête sur l’endpoint well-known de Keycloak, nous demandons au mock de répondre avec un JSON contenant les principaux endpoints de la norme OIDC. Même si finalement, nous n’utilisons que l’endpoint jwks_uri, la bibliothèque Keycloak vérifie l’existence des autres endpoints.

Il nous faut maintenant mock l’appel à l’endpoint jwks_uri afin de permettre à la bibliothèque de Keycloak de récupérer les informations de la signature utilisé pour les tokens. Pour cela, on ajoute dans le beforeAll:


    RSAKey rsaJWK = getRsaKey();

    X509Certificate cert = getX509Certificate(rsaJWK);

    getPrivateKey(rsaJWK, cert);

    JWK jwk = getJwk(rsaJWK, cert);

    mockServerClient
        .when(HttpRequest.request()
            .withMethod("GET")
            .withPath("/realms/example/protocol/openid-connect/certs"))
        .respond(HttpResponse.response()
            .withStatusCode(200)
            .withBody(generateKCCertsJson(jwk.toJSONString())));

Génération du certificat et des clés

Voyons à présent comment sont implémenté les méthodes getRsaKey(), getX509Certificate(rsaJWK), getPrivateKey(rsaJWK, cert) et getJwk(rsaJWK, cert). Pour cela, nous allons utiliser la bibliothèque nimbus-jose :

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactID>nimbus-jose-jwt</artifactId>
    <version>9.39.1</version>
    <scope>test</scope>
</dependency>

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactID>oauth2-oidc-sdk</artifactId>
    <version>11.12</version>
    <scope>test</scope>
</dependency>


    /**
   * Create a JWK with a random ID
   *
   * @return The new JSON Web Key with 2048 RSA key
   * @throws JOSEException Something wrong happen during RSA key generation
   */
  private static RSAKey getRsaKey() throws JOSEException {

    return new RSAKeyGenerator(2048)
        .keyID(OIDCFilterTest.KEY_ID)
        .keyUse(KeyUse.SIGNATURE)
        .generate();
  }

  /**
   * Generate a self signed certificate
   * @param rsaJWK The Json Web Key
   * @return A self-signed certificate.
   */
  private static X509Certificate getX509Certificate(RSAKey rsaJWK) throws OperatorCreationException, IOException, JOSEException {
    return X509CertificateUtils.generateSelfSigned(
        new Issuer("http://localhost:8080"),
        Date.from(Instant.now().minus(1, ChronoUnit.DAYS)),
        Date.from(Instant.now().plus(1, ChronoUnit.DAYS)),
        rsaJWK.toRSAPublicKey(),
        rsaJWK.toRSAPrivateKey());
  }

  @SuppressWarnings("deprecation")
  private static void getPrivateKey(RSAKey rsaJWK, X509Certificate cert) throws CertificateEncodingException, JOSEException {
    // Create private key from the certificate
    privateJWK = new RSAKey.Builder(rsaJWK)
        .x509CertChain(Collections.singletonList(Base64.encode(cert.getEncoded())))
        .x509CertThumbprint(rsaJWK.computeThumbprint())
        .build();
  }

  @SuppressWarnings("deprecation")
  private static JWK getJwk(RSAKey rsaJWK, X509Certificate cert) throws CertificateEncodingException, JOSEException {
    return new RSAKey.Builder(rsaJWK)
        .keyUse(KeyUse.SIGNATURE)
        .keyID(KEY_ID)
        .issueTime(new Date())
        .algorithm(algorithm)
        .x509CertChain(Collections.singletonList(Base64.encode(cert.getEncoded())))
        .x509CertThumbprint(rsaJWK.computeThumbprint())
        .x509CertSHA256Thumbprint(rsaJWK.computeThumbprint())
        .build();
  }

Le code est assez parlant de lui-même. On commence par générer un combo clé privée/publique en RSA 2048. Nous utilisons ces clés pour générer un certificat X509 auto signé. On utilise ensuite ce certificat pour générer des clés asymétriques pour la signature des tokens.

À noter que le certificat X509 à une validité de 1 jour ici. Pour des tests, cela est amplement suffisant. Nous ajoutons le paramètre x509CertThumbprint qui est déprécié, car Keycloak le génère également.

Il nous reste à exposer ces informations au format JSON. La méthode generateKCCErtsJSON s’en charge :

private static String generateKCCertsJson(String key) {
    JSONObject keyObject = new JSONObject(key);

    JSONObject root = new JSONObject();
    JSONArray keys = new JSONArray();
    keys.put(keyObject);
    root.put("keys", keys);
    return root.toString();
  }

Keycloak pouvant exposer plusieurs clés, la méthode se contente de créer un tableau keys dans lequel sont insérées les informations générées précédemment.

Génération du token

Il ne nous reste plus qu’à générer un JWT signé par notre clé issue du certificat X509 exposé par notre mockServer.

    // Create RSA-signer with the private key
    JWSSigner signer = new RSASSASigner(privateJWK);

    JWSHeader header = new Builder(JWSAlgorithm.RS256)
        .type(JOSEObjectType.JWT)
        .keyID(KEY_ID)
        .build();
    JWTClaimsSet payload = new JWTClaimsSet.Builder()
        .issuer("http://localhost:8080/realms/example")
        .audience("myService")
        .subject("myApp")
        .claim("typ", "Bearer")
        .expirationTime(Date.from(Instant.now().plusSeconds(300)))
        .notBeforeTime(Date.from(Instant.now().minusSeconds(120)))
        .build();

    JWSObject jwsObject = new JWSObject(header, payload.toPayload());

    // Compute the RSA signature
    jwsObject.sign(signer);
    String token = jwsObject.serialize();

Le fichier de configuration Keycloak keycloak.json permettant de valider ce token est le suivant :

{
    "realms": "example",
    "auth-server-url": "http://localhost:8080",
    "ssl-required": "external",
    "resource": "myService",
    "verify-token-audience": true,
    ...
}

Conclusion

C’est terminer. Cela fait pas mal de code pour juste signer et validé un jeton. La bibliothèque nimbus nous aide fortement dans cette tâche. Les tests de sécurité sont maintenant beaucoup plus rapides à exécuter. Même si nous démarrons un serveur netty, cela n’est rien comparé à un serveur Keycloak dans une image docker. Petit bonus, le serveur mock permet en plus de voir l’ensemble des requêtes exécutées avec leurs paramètres. Pratique pour débugguer.

Quarkus Extension Additional Application Archive Marker Build Item

Thu, 29 Feb 2024 11:23:22 +0100

On continue avec les différentes manières d’indexer des Beans via une extension Quarkus avec l’AdditionalApplicationArchiveMarkerBuildItem. Ce build item permet en quelques sorts de faire en une seule étape ce que fait la combinaison CombinedIndexBuildItem et AdditionalBeanBuildItem.

Comme son nom l’indique ce build item permet d’indiquer à Quarkus des fichiers Marker supplémentaire à prendre en compte au moment du scan du classpath. Par défaut Quarkus va indexer l’ensemble des Beans dans les archives possédant un fichier beans.xml, jandex.idx ou config properties. Ce build item permet de déclarer des fichiers Marker supplémentaire pour déclencher l’indexation.

@BuildStep()
void addMarker(BuildProducer<AdditionalApplicationArchiveMarkerBuildItem> producer) {
    producer.produce(new AdditionalApplicationArchiveMarkerBuildItem("my/package/Foo/markerFile.ext"));
}

Dans cet exemple, Quarkus va indexer l’ensemble des beans contenu dans les archives ayant le fichier my/package/Foo/markerFile.ext. On utilise ici la notation / et non celle pointée(.) pour les packages. Le nom d’un package peu aussi est spécifié.

Conclusion

L’AdditionalApplicationArchiveMarkerBuildItem est un build item très puissant, mais à utiliser avec parcimonie. En effet, il peut très rapidement conduire à l’inclusion de Bean non voulu dans l’index Quarkus. De ce point de vue le combo CombinedIndexBuildItem et AdditionalBeanBuildItem offre plus de contrôle.