Formations — 1 037 leçons en français

Accueil › Spring Boot › API stateless : JWT et OAuth2 Resource Server

API stateless : JWT et OAuth2 Resource Server

Spring Securityintermediaire

Pour une API stateless, consommée par des clients qu'on ne contrôle pas forcément (application mobile, SPA, autre service), le couple session + cookie est mal adapté : il faudrait partager l'état de session entre toutes les instances du serveur. La solution largement adoptée est le JWT : un jeton signé, auto-suffisant, que le client envoie à chaque requête dans l'en-tête Authorization: Bearer <jwt>.

Spring Security ne fabrique pas ces jetons lui-même dans ce rôle : il joue le rôle de resource server, qui se contente de vérifier un jeton émis par un fournisseur d'identité externe (Keycloak, Auth0, Okta, Azure AD…).

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-oauth2-resource-server</artifactId>
</dependency>
spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://mon-fournisseur.exemple.com/realms/boutique
@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http
        .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
        .authorizeHttpRequests(auth -> auth
            .requestMatchers("/api/public/**").permitAll()
            .anyRequest().authenticated()
        )
        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()));
    return http.build();
}

Avec issuer-uri seul, Spring Security va chercher automatiquement les clés publiques nécessaires à la vérification de la signature. Aucun filtre « fait maison » n'est nécessaire.

Les termes à connaître

JWT (JSON Web Token)

Jeton composé de trois parties séparées par des points et encodées en Base64Url : en-tête.charge utile.signature. L'en-tête décrit l'algorithme de signature, la charge utile (« payload ») contient des informations (« claims ») comme l'émetteur ou l'expiration, la signature garantit que le jeton n'a pas été modifié.

SessionCreationPolicy.STATELESS

Politique de session qui indique à Spring Security de ne jamais créer ni utiliser de session HTTP. Chaque requête est authentifiée indépendamment, à partir du jeton qu'elle transporte.

spring-boot-starter-oauth2-resource-server

Dépendance qui ajoute le support « resource server » de Spring Security : valider un jeton (JWT le plus souvent) envoyé par un client, sans gérer soi-même la connexion des utilisateurs.

issuer-uri / jwk-set-uri

Propriétés spring.security.oauth2.resourceserver.jwt.issuer-uri (l'identifiant de l'émetteur, ex. une URL Keycloak) et ...jwk-set-uri (l'adresse où récupérer les clés publiques de vérification). Avec issuer-uri, Spring Security peut découvrir automatiquement les autres informations, dont jwk-set-uri, via un point de découverte standard.

http.oauth2ResourceServer(...)

Méthode de configuration DSL sur HttpSecurity qui active la validation des jetons entrants : http.oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults())).

Scope → SCOPE_

Par défaut, chaque scope présent dans le claim scope (ou scp) d'un JWT est converti en une autorité Spring Security préfixée par SCOPE_ (le scope read devient l'autorité SCOPE_read), utilisable avec hasAuthority("SCOPE_read").

Authorization: Bearer

En-tête HTTP par lequel le client transmet le jeton à chaque requête : Authorization: Bearer <jwt>. « Bearer » (porteur) signifie que quiconque possède le jeton peut l'utiliser, d'où l'importance de le transmettre uniquement en HTTPS et de ne jamais le logger.

Lire l'explication détaillée et faire le quiz →

Cette page présente la partie essentielle de la leçon. Les exemples commentés, les pièges courants et les trois questions de quiz sont dans l'application.