Tous les articles
Sécurité

Keycloak, OAuth2 et OIDC : sécuriser des API ouvertes aux partenaires

Clients dédiés, scopes métier, audience, rotation des clés et tests : la mise en œuvre complète avec Keycloak et Spring Boot.

Ibrahima Coundoul
18 novembre 2026 · 6 min de lecture

Ouvrir une API à des partenaires, c’est accepter que du code que vous ne maîtrisez pas appelle votre système d’information. La question n’est plus seulement « qui est connecté ? », mais « qui a le droit de faire quoi, sur quelles données, et pendant combien de temps ? ». Voici l’approche que j’applique sur ce type de projet, de la configuration de Keycloak jusqu’aux tests côté Spring Boot.

Le contexte

Chez un opérateur télécom, les applications métier exposent des API REST à deux publics : des équipes internes et des partenaires externes. Les deux consomment souvent les mêmes ressources, mais avec des droits très différents. Un modèle de sécurité trop grossier finit toujours de la même façon : soit on bloque les partenaires, soit on leur ouvre plus que nécessaire.

L’architecture cible tient en trois briques :

  1. Keycloak, serveur d’autorisation, qui émet les tokens.
  2. Les API Spring Boot, resource servers, qui valident les tokens et appliquent les règles d’accès.
  3. Le contrat OpenAPI, qui documente pour chaque route le scope exigé.

Séparer authentification et autorisation

OpenID Connect répond à la question de l’identité : qui est l’utilisateur. OAuth2 répond à celle de la délégation : à quoi ce client a droit. Mélanger les deux mène à des API qui inspectent des profils utilisateurs là où elles devraient simplement vérifier une permission.

Pour des échanges de machine à machine, sans utilisateur, le bon flux est client credentials : le partenaire s’authentifie avec ses propres identifiants et reçoit un token d’accès qui porte ses droits.

Configurer Keycloak : un client par partenaire

Dans un realm dédié (par exemple partners), chaque partenaire reçoit son propre client, configuré ainsi :

Réglage du client Valeur
Client authentication Activé (client confidentiel)
Service accounts roles Activé (flux client credentials)
Standard flow / Direct access grants Désactivés
Client authenticator Secret, ou mieux Signed JWT / certificat X.509

Un client par partenaire permet de révoquer, auditer et limiter chacun indépendamment. Le jour où un partenaire est compromis, on désactive son client sans toucher aux autres.

Pour les partenaires sensibles, je préfère l’authentification par JWT signé (private_key_jwt) ou par certificat client (mTLS) au simple secret : aucune donnée secrète ne circule, et la clé privée reste chez le partenaire.

Des scopes métier, pas des rôles fourre-tout

Les droits sont portés par des client scopes qui décrivent une action métier :

  • partners:read — consulter les données partenaires ;
  • partners:write — créer ou modifier ;
  • orders:read — consulter les commandes.

Chaque client reçoit uniquement les scopes dont il a besoin, en optional : il doit les demander explicitement. On évite ainsi les rôles du type admin ou api-user, qui finissent toujours par donner trop de droits.

Fixer l’audience et la durée de vie

Deux réglages sont souvent oubliés :

  • L’audience. Un mapper de type Audience ajoute l’identifiant de l’API (par exemple partners-api) dans le claim aud. Un token émis pour une autre API sera refusé.
  • La durée de vie. Un token d’accès court, de l’ordre de 5 minutes, limite la fenêtre d’exploitation d’un token volé. En client credentials, pas besoin de refresh token : le client en redemande un.

Ce que voit le partenaire

Le partenaire obtient un token en un appel :

curl -s -X POST \
  https://auth.example.com/realms/partners/protocol/openid-connect/token \
  -d grant_type=client_credentials \
  -d client_id=partner-acme \
  -d client_secret="$CLIENT_SECRET" \
  -d scope="partners:read"

Le token décodé contient tout ce dont l’API a besoin pour décider :

{
  "iss": "https://auth.example.com/realms/partners",
  "aud": "partners-api",
  "azp": "partner-acme",
  "scope": "partners:read",
  "exp": 1763470200
}

Valider les tokens côté Spring Boot

L’API devient un resource server. Elle valide la signature des JWT localement, avec les clés publiques de Keycloak, sans appel réseau à chaque requête :

spring:
  security:
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://auth.example.com/realms/partners
          audiences: partners-api

La propriété audiences (Spring Boot 3.2 et plus) rejette tout token dont le claim aud ne contient pas l’API. Les règles d’accès se déclarent ensuite par scope :

@Configuration
@EnableMethodSecurity
class SecurityConfig {

    @Bean
    SecurityFilterChain api(HttpSecurity http) throws Exception {
        return http
            .csrf(csrf -> csrf.disable()) // API sans session ni cookie
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .authorizeHttpRequests(auth -> auth
                .requestMatchers(HttpMethod.GET, "/api/partners/**").hasAuthority("SCOPE_partners:read")
                .requestMatchers("/api/partners/**").hasAuthority("SCOPE_partners:write")
                .anyRequest().authenticated())
            .oauth2ResourceServer(oauth -> oauth.jwt(Customizer.withDefaults()))
            .build();
    }
}

Par défaut, Spring transforme chaque valeur du claim scope en autorité SCOPE_…. Les règles restent lisibles et alignées sur le contrat.

Les scopes ne suffisent pas : contrôler la propriété des données

Un scope dit « ce client peut lire des commandes », pas « ce client peut lire ces commandes ». Le contrôle d’accès aux données se fait dans le code métier, à partir de l’identité du client portée par le token :

@GetMapping("/api/orders/{id}")
@PreAuthorize("hasAuthority('SCOPE_orders:read')")
OrderDto order(@PathVariable String id, @AuthenticationPrincipal Jwt jwt) {
    String partnerId = jwt.getClaimAsString("azp");
    return orders.findByIdAndPartner(id, partnerId)
                 .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
}

Renvoyer 404 plutôt que 403 pour une ressource qui appartient à un autre partenaire évite de confirmer qu’elle existe.

Documenter la sécurité dans le contrat

Le contrat OpenAPI décrit le flux et les scopes, et chaque opération déclare celui qu’elle exige :

components:
  securitySchemes:
    partnerOAuth:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/realms/partners/protocol/openid-connect/token
          scopes:
            partners:read: Consulter les données partenaires
            partners:write: Créer ou modifier les données partenaires
paths:
  /api/partners/{id}:
    get:
      security:
        - partnerOAuth: [partners:read]

Le partenaire sait exactement quel scope demander, et la revue de sécurité se fait en lisant le contrat.

Tester les règles d’accès

Les règles de sécurité se testent comme le reste du code. Avec spring-security-test, on simule un token sans démarrer Keycloak :

@Test
void refuse_l_ecriture_sans_le_scope_write() throws Exception {
    mvc.perform(post("/api/partners")
            .with(jwt().authorities(new SimpleGrantedAuthority("SCOPE_partners:read")))
            .contentType(MediaType.APPLICATION_JSON)
            .content("{}"))
       .andExpect(status().isForbidden());
}

Pour les tests d’intégration de bout en bout, un conteneur Keycloak lancé avec Testcontainers et un realm importé au démarrage reproduit fidèlement la production.

Penser à l’exploitation dès le départ

La sécurité d’une API partenaire se joue aussi après la mise en production :

  • Rotation des clés de signature. Keycloak publie ses clés publiques sur l’endpoint JWKS. Spring les met en cache et les recharge quand un token arrive avec un identifiant de clé (kid) inconnu : on peut donc faire tourner les clés sans interruption, en gardant l’ancienne active le temps que les tokens en circulation expirent.
  • Rotation des secrets clients, planifiée et coordonnée avec chaque partenaire.
  • Journalisation par client. L’identifiant azp est ajouté au contexte de log (MDC) et aux traces : chaque appel est attribuable à un partenaire.
  • Limitation de débit par client, au niveau de la passerelle d’API, pour qu’un partenaire mal configuré ne dégrade pas le service des autres.

Le jour où un partenaire signale un comportement anormal, ces éléments permettent de répondre en minutes plutôt qu’en jours.

Un bon modèle de sécurité se lit dans le contrat de l’API : chaque route dit quel scope elle exige.

Ce que j’en retiens

  • Un client Keycloak par partenaire, authentifié de préférence par JWT signé ou certificat.
  • Des scopes métier fins, demandés explicitement et documentés dans le contrat OpenAPI.
  • Une audience vérifiée, des tokens de quelques minutes et des clés qui tournent.
  • Un contrôle de propriété des données dans le code, en plus des scopes.
  • Des règles d’accès testées automatiquement, comme n’importe quelle règle métier.

Cet article vous a été utile ? Partagez-le.

Portrait d'Ibrahima Coundoul
Ibrahima Coundoul

Architecte et développeur backend senior Java / Spring Boot, 14 ans sur des systèmes critiques en télécoms, banque et mobilité. Basé à Dakar.

Voir mon profil

Autres articles