Authentifier une API : clé d'API, Bearer, JWT et OAuth 2.0

Authentifier une API, c'est vérifier à chaque requête qui l'envoie, puisque HTTP ne garde aucun état entre deux appels. Le client joint une preuve à sa requête, le plus souvent dans l'en-tête Authorization : une clé d'API pour un programme partenaire, un jeton (souvent un JWT) pour un utilisateur, un jeton d'accès OAuth 2.0 pour une application tierce. Ce chapitre présente chaque mécanisme, son fonctionnement, ses pièges et les cas où le choisir.

Authentifier, puis autoriser

Deux questions différentes, posées dans cet ordre à chaque requête :

• l'authentification : qui es-tu ? L'API vérifie la preuve jointe à la requête. Échec : 401 Unauthorized ;
• l'autorisation : as-tu le droit de faire cette action sur cette ressource ? L'API compare l'identité aux règles : le rôle, le propriétaire de la ressource, l'état de la ressource. Échec : 403 Forbidden (ou 404 pour ne pas révéler l'existence).

Ce chapitre traite de la première question ; la seconde, où se cachent les failles les plus graves des API, est au chapitre 10. Les notions d'identification, d'authentification et d'autorisation sont détaillées dans le chapitre Identification, authentification, autorisation du cours Authentification.

Les mécanismes en un coup d'œil

Une règle s'applique à tous : tout passe en HTTPS. Une clé ou un jeton qui circule en clair est volé par le premier qui écoute le réseau.

HTTP Basic

Le client envoie l'identifiant et le mot de passe, séparés par deux-points et encodés en base64, à chaque requête :

GET /v1/fiches HTTP/1.1
Host: api.gsb.example
Authorization: Basic YXBwbGktcGFpZTpTM2NyM3QtUGFydDNuYWlyZQ==

YXBwbGktcGFpZTpTM2NyM3QtUGFydDNuYWlyZQ== se décode en appli-paie:S3cr3t-Part3naire. Le base64 est un encodage, pas un chiffrement : n'importe qui le décode en une ligne (atob(…) dans la console du navigateur). Basic est simple et universel, mais le mot de passe voyage à chaque requête, ne peut pas avoir de durée de vie courte et ne se combine pas avec une authentification multifacteur. On le réserve à des outils internes ou à des scripts, toujours en HTTPS.

La clé d'API

Une clé d'API est une longue chaîne aléatoire que l'API remet à une application cliente, en général celle d'un partenaire. L'application la joint à chaque requête :

GET /v1/fiches?etat=VA HTTP/1.1
Host: api.gsb.example
X-API-Key: gsb_live_9c1f2e7a4b6d8f0a3c5e7b9d1f3a5c7e

Une clé d'API identifie une application, pas une personne : elle dit « c'est le logiciel de paie du cabinet comptable », pas « c'est Lucas ». Elle a une longue durée de vie, ce qui impose des précautions :

• une clé par client, avec des droits limités à ce dont il a besoin (lecture seule des fiches validées, par exemple) ;
• stockée hachée côté serveur (avec SHA-256, la clé étant assez longue et aléatoire pour que le sel soit inutile), comme un mot de passe : une fuite de la base ne livre pas les clés utilisables. Un préfixe lisible (gsb_live_) aide à repérer une clé publiée par erreur dans un dépôt Git ;
• révocable et renouvelable sans interrompre le service : l'API accepte deux clés le temps de la transition ;
• jamais dans une URL (?api_key=…) : les URL sont enregistrées dans les journaux des serveurs et des proxys, dans l'historique et dans l'en-tête Referer ;
• jamais dans un front web ni une application mobile : ce sont des clients publics, qui ne peuvent rien garder secret (chapitre 8).

Le jeton porteur : se connecter une fois

Pour un utilisateur humain, on ne renvoie pas son mot de passe à chaque requête. Il se connecte une fois ; l'API lui remet un jeton de courte durée, qu'il présente ensuite à chaque appel.

La connexion :

POST /v1/auth/connexion HTTP/1.1
Host: api.gsb.example
Content-Type: application/json

{"login":"lmartin","motDePasse":"…"}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"accessToken":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3Iiwicm9sZSI6InZpc2l0ZXVyIiwiaWF0IjoxNzkzNjA2NDAwLCJleHAiOjE3OTM2MDczMDB9.a8ZshHZGh7E-8WGbfhx71TRtZuYh4itGWIpPi0G4Psg","tokenType":"Bearer","expiresIn":900,"refreshToken":"Xq7Lk2vR9pT4wZ8nB3mF6yH1cJ5sD0aE"}

Puis chaque requête porte le jeton dans l'en-tête Authorization, avec le mot Bearer (« porteur ») :

GET /v1/fiches HTTP/1.1
Host: api.gsb.example
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3Iiwicm9sZSI6InZpc2l0ZXVyIiwiaWF0IjoxNzkzNjA2NDAwLCJleHAiOjE3OTM2MDczMDB9.a8ZshHZGh7E-8WGbfhx71TRtZuYh4itGWIpPi0G4Psg

« Porteur » veut dire que quiconque possède le jeton est reconnu comme Lucas, comme un billet de train non nominatif. D'où les règles : HTTPS, durée de vie courte, jamais dans une URL ni dans un journal.

Sans jeton valide, l'API répond 401 avec un en-tête qui explique le problème (RFC 6750) :

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api", error="invalid_token", error_description="Le jeton a expiré"

Le jeton peut être opaque (une chaîne aléatoire que l'API retrouve dans sa base ou dans un cache) ou autoporteur, c'est-à-dire qu'il contient lui-même les informations sur l'utilisateur, signées : c'est le cas du JWT.

Le JWT : structure

Un JWT (JSON Web Token, RFC 7519, prononcé « jot ») se compose de trois parties encodées en base64url et séparées par des points : l'en-tête, la charge utile et la signature.

Décodé, le jeton de Lucas donne :

{ "alg": "HS256", "typ": "JWT" }

{ "sub": "7", "role": "visiteur", "iat": 1793606400, "exp": 1793607300 }

Les revendications (claims) normalisées les plus courantes :

role n'est pas normalisé : c'est une revendication propre à l'application, comme on peut en ajouter d'autres.

La signature est calculée sur les deux premières parties avec une clé que seul le serveur connaît. Deux familles d'algorithmes :

• symétriques (HS256, HMAC avec SHA-256) : la même clé secrète signe et vérifie. Simple, adapté quand c'est la même API qui émet et vérifie ;
• asymétriques (RS256, ES256) : une clé privée signe, une clé publique vérifie. Adapté quand un fournisseur d'identité émet les jetons et que plusieurs API les vérifient, sans jamais détenir la clé privée. Les clés publiques sont souvent publiées à une adresse /.well-known/jwks.json.

Le fonctionnement du HMAC et des signatures est expliqué dans le chapitre HMAC et signature numérique du cours de cryptographie.

Vérifier un JWT côté API

Toute la sécurité repose sur la vérification. Le middleware de l'API, ici en Node.js avec la bibliothèque jsonwebtoken :

const jwt = require('jsonwebtoken');

function authentifier(req, res, next) {
  const entete = req.headers.authorization ?? '';
  const [schema, jeton] = entete.split(' ');
  if (schema !== 'Bearer' || !jeton) {
    res.set('WWW-Authenticate', 'Bearer realm="api"');
    return res.status(401).type('application/problem+json').json({
      type: 'https://api.gsb.example/problemes/non-authentifie',
      title: 'Authentification requise',
      status: 401,
    });
  }
  try {
    req.utilisateur = jwt.verify(jeton, process.env.JWT_SECRET, {
      algorithms: ['HS256'],          // n'accepter que l'algorithme prévu
      issuer: 'https://api.gsb.example',
      audience: 'api-applifrais',
    });                               // verify contrôle aussi exp et nbf
    next();
  } catch {
    res.set('WWW-Authenticate', 'Bearer realm="api", error="invalid_token"');
    return res.status(401).type('application/problem+json').json({
      type: 'https://api.gsb.example/problemes/jeton-invalide',
      title: 'Jeton invalide ou expiré',
      status: 401,
    });
  }
}

Les contrôles à ne pas oublier, et les failles qu'ils évitent :

Les recommandations de l'IETF sur l'usage des JWT sont rassemblées dans la RFC 8725.

Jeton d'accès court, jeton de rafraîchissement

Un JWT ne se révoque pas facilement : il reste valable jusqu'à son exp, même si l'utilisateur se déconnecte ou est désactivé, puisque l'API ne consulte aucune base pour le vérifier. On limite le risque en combinant deux jetons :

• un jeton d'accès (access token) court (5 à 15 minutes), présenté à chaque requête ;
• un jeton de rafraîchissement (refresh token) long (quelques jours), présenté seulement à la route de rafraîchissement, et enregistré côté serveur, donc révocable.

Quand le jeton d'accès expire, le client reçoit 401, appelle POST /v1/auth/rafraichissement avec son jeton de rafraîchissement et obtient un nouveau jeton d'accès, sans redemander le mot de passe. Bonne pratique : à chaque rafraîchissement, l'API remet aussi un nouveau jeton de rafraîchissement et invalide l'ancien (la rotation). Si un ancien jeton est présenté une seconde fois, c'est qu'il a été volé : l'API révoque toute la session.

Où le front web garde-t-il ses jetons ? Dans localStorage, ils sont lisibles par tout script de la page, donc volés par la moindre faille XSS ; dans un cookie HttpOnly, Secure, SameSite, ils sont invisibles au JavaScript mais envoyés automatiquement, ce qui impose de se protéger du CSRF. Le compromis est détaillé dans le chapitre Sessions, cookies et JWT du cours Authentification.

OAuth 2.0 : déléguer un accès

OAuth 2.0 (RFC 6749) est un protocole d'autorisation déléguée : il permet à une application d'obtenir un jeton d'accès limité pour appeler une API, sans jamais connaître le mot de passe de l'utilisateur. Quatre rôles :

• le propriétaire de la ressource : l'utilisateur ;
• le client : l'application qui veut accéder à l'API ;
• le serveur d'autorisation : il authentifie l'utilisateur, recueille son consentement et délivre les jetons (Keycloak, Microsoft Entra ID, Google…) ;
• le serveur de ressources : l'API, qui vérifie le jeton d'accès à chaque requête.

Le jeton d'accès porte des portées (scopes) qui limitent ce qu'il permet : fiches:lecture, fiches:ecriture. L'API vérifie la portée en plus du rôle.

Deux flux suffisent à connaître aujourd'hui. Les recommandations de sécurité de l'IETF publiées en janvier 2025 (RFC 9700) écartent le flux implicite et le flux qui transmet le mot de passe au client.

Le flux du code d'autorisation avec PKCE, pour une application utilisée par une personne (front web, application mobile). Le client redirige l'utilisateur vers le serveur d'autorisation, qui l'authentifie et renvoie un code à usage unique ; le client échange ce code contre les jetons, en prouvant avec PKCE qu'il est bien celui qui a lancé la demande. Le détail pas à pas, avec ses paramètres, est dans le chapitre OAuth 2.0, OpenID Connect, SAML du cours Authentification.

Le flux des identifiants client (client credentials), pour un échange entre machines, sans utilisateur. Le logiciel de paie du cabinet comptable s'authentifie avec son identifiant et son secret, et obtient un jeton pour lui-même :

POST /oauth/token HTTP/1.1
Host: auth.gsb.example
Content-Type: application/x-www-form-urlencoded
Authorization: Basic YXBwbGktcGFpZTpTM2NyM3QtUGFydDNuYWlyZQ==

grant_type=client_credentials&scope=fiches%3Alecture

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{"access_token":"eyJhbGciOiJSUzI1NiIs…","token_type":"Bearer","expires_in":3600,"scope":"fiches:lecture"}

Le logiciel de paie appelle ensuite l'API avec Authorization: Bearer …, et redemande un jeton quand il expire. Par rapport à une clé d'API permanente, le jeton est court, limité à une portée, et la gestion des clients est centralisée dans le serveur d'autorisation.

Quel mécanisme choisir ?

Le sujet E7 SLAM 2025 de Nouvelle-Calédonie (cas Kirassur) combinait les deux premiers mondes : la société partenaire s'authentifiait avec sa clé d'API pour obtenir un jeton temporaire au nom d'un assuré, et l'assuré n'utilisait que ce jeton, jamais la clé. Le raisonnement est développé dans le chapitre API, jetons et authentification du cours E7 SLAM.

Exercices

function authentifier(req, res, next) {
  const jeton = req.query.token;
  const donnees = jwt.decode(jeton);
  if (!donnees) return res.status(403).send('Interdit');
  req.utilisateur = donnees;
  next();
}