Protéger votre API avec un middleware

Chaque SDK serveur fournit un middleware léger qui protège votre API à l'aide des jetons d'accès KeenAuth : net/http en Go, Express et Fastify en Node.js, et Django, Flask et FastAPI en Python. Il s'appuie sur le vérificateur de jetons et n'ajoute aucune logique propre aux jetons.

Ce que fait le middleware

• Lit le jeton dans l'en-tête Authorization, avec le schéma Bearer ou DPoP. Un jeton passé dans la query de l'URL (?access_token=) est toujours refusé, car les URL finissent dans les journaux et les en-têtes Referer. Une requête contenant plusieurs en-têtes Authorization ou plusieurs identifiants est également refusée.
• Vérifie DPoP. Avec le schéma DPoP, l'en-tête de preuve DPoP, la méthode de la requête et l'URL absolue de la requête (l'URL publique de base configurée suivie du chemin de la requête) sont transmis au vérificateur. Un jeton lié à DPoP envoyé avec le schéma Bearer est rejeté, tout comme le schéma DPoP employé avec un jeton qui n'est pas lié à DPoP.
• Vérifie les exigences de la route : les scopes requis (tous) et, éventuellement, une authentification renforcée : valeurs acr acceptables et âge maximal de la connexion (RFC 9470).
• Interroge le cache de révocation, si vous en configurez un, pour savoir si le jeton a été révoqué.
• Attache les revendications vérifiées à la requête : protect.ClaimsFrom(ctx) en Go, req.auth avec Express et Fastify, request.auth avec Django, g.auth avec Flask, et la valeur retournée par la dépendance avec FastAPI.
• Répond aux échecs avec le challenge standard WWW-Authenticate et un petit corps application/problem+json. La réponse ne contient jamais le jeton ni la valeur d'une revendication, et le middleware ne les journalise jamais.

Go (net/http)

Le package protect n'utilise que la bibliothèque standard et fonctionne avec tout routeur acceptant un http.Handler.

import (
	"github.com/keenauth/keenauth-go/protect"
	"github.com/keenauth/keenauth-go/verify"
)

v, err := verify.New(verify.Config{
	Issuer:   "https://acme.eu.keenauth.app",
	Audience: "https://api.acme.example",
})
if err != nil {
	return err
}
m, err := protect.New(v, protect.Options{
	PublicBaseURL:       "https://api.acme.example",
	ResourceMetadataURL: "https://api.acme.example/.well-known/oauth-protected-resource",
})
if err != nil {
	return err
}

mux := http.NewServeMux()
mux.Handle("GET /orders", m.Require(protect.Requirement{Scopes: []string{"orders:read"}})(http.HandlerFunc(
	func(w http.ResponseWriter, r *http.Request) {
		claims, _ := protect.ClaimsFrom(r.Context())
		fmt.Fprintln(w, claims.Subject)
	})))

age := 10 * time.Minute
mux.Handle("POST /payouts", m.Require(protect.Requirement{
	Scopes:        []string{"payouts:write"},
	AcceptableACR: []string{"urn:idp:acr:mfa"},
	MaxAuthAge:    &age,
})(payoutsHandler))

m.Handler(next) protège un handler avec un jeton valide et sans exigence supplémentaire. Require provoque un panic au démarrage si un scope n'est pas un jeton de scope valide, comme le fait http.ServeMux pour un motif invalide.

Node.js (Express et Fastify)

Le middleware se trouve dans le sous-chemin @keenauth/node/middleware. Express et Fastify ne sont pas des dépendances du SDK.

import { createVerifier } from "@keenauth/node";
import { createProtector, expressAuth, fastifyAuth } from "@keenauth/node/middleware";

const verifier = createVerifier({ issuer: "https://acme.eu.keenauth.app", audience: "https://api.acme.example" });
const protector = createProtector(verifier, { publicBaseUrl: "https://api.acme.example" });

// Express
app.get("/orders", expressAuth(protector, { scopes: ["orders:read"] }), (req, res) => {
  res.json({ sub: req.auth.subject });
});

// Fastify
fastify.decorateRequest("auth", null);
fastify.get("/orders", { preHandler: fastifyAuth(protector, { scopes: ["orders:read"] }) }, async (request) => {
  return { sub: request.auth.subject };
});

L'authentification renforcée utilise { acceptableAcr: ["urn:idp:acr:mfa"], maxAuthAgeSeconds: 600 }. En TypeScript, typez la requête avec AuthenticatedRequest (exporté par le sous-chemin) pour lire req.auth.

Python (Django, Flask, FastAPI)

Installez l'extra correspondant à votre framework : pip install "keenauth-python[django]", "keenauth-python[flask]" ou "keenauth-python[fastapi]". Le framework n'est importé que par son propre module d'adaptation.

from keenauth.middleware import Protector
from keenauth.verify import Verifier, VerifierConfig

verifier = Verifier(VerifierConfig(issuer="https://acme.eu.keenauth.app", audience="https://api.acme.example"))
protector = Protector(verifier, public_base_url="https://api.acme.example")

Django :

from django.http import JsonResponse
from keenauth.middleware.django import protect

@protect(protector, scopes=["orders:read"])
def orders(request):
    return JsonResponse({"sub": request.auth.subject})

Flask :

from flask import g
from keenauth.middleware.flask import protect

@app.get("/orders")
@protect(protector, scopes=["orders:read"])
def orders():
    return {"sub": g.auth.subject}

FastAPI :

from fastapi import Depends, FastAPI
from keenauth.middleware.fastapi import RequireAuth, install
from keenauth.verify import AccessClaims

app = FastAPI()
install(app)

@app.get("/orders")
def orders(claims: AccessClaims = Depends(RequireAuth(protector, scopes=["orders:read"]))):
    return {"sub": claims.subject}

install(app) enregistre le handler qui écrit le corps de problème et un en-tête WWW-Authenticate par challenge. L'authentification renforcée utilise acceptable_acr=["urn:idp:acr:mfa"], max_auth_age=timedelta(minutes=10).

L'URL publique de base (obligatoire)

Une preuve DPoP indique l'URL appelée par le client (htu). Le middleware compare cette valeur à l'URL publique de base que vous configurez (PublicBaseURL, publicBaseUrl, public_base_url), suivie du chemin de la requête. Renseignez l'adresse utilisée par vos clients, par exemple https://api.acme.example ou https://acme.example/api. Ce paramètre est obligatoire : la création du middleware sans lui échoue au démarrage avec une erreur de configuration, même si vos clients n'envoient que des jetons Bearer.

Le middleware ne construit jamais cette URL à partir de l'en-tête Host de la requête ni des en-têtes X-Forwarded-*, et en Python il n'utilise pas l'URL de requête propre au framework, même si le framework ou le serveur est configuré pour faire confiance aux en-têtes transmis. Ces valeurs sont choisies par le client : si votre API est servie sous deux noms d'hôte, une preuve établie pour l'un d'eux pourrait sinon être rejouée sur l'autre. Derrière un répartiteur de charge ou un proxy inverse, l'URL publique de base indique aussi au middleware le schéma, l'hôte et le préfixe de chemin que voient les clients. L'URL publique de base doit utiliser https, sauf pour localhost, 127.0.0.1 et [::1] (RFC 6750 §5.3) ; le schéma et l'hôte sont comparés sans tenir compte de la casse, et un port par défaut (:443, :80) est ignoré, aussi bien dans l'URL de base que dans le htu de la preuve.

Réponses

Le challenge utilise le schéma employé par le client. Lorsque vous renseignez l'URL des métadonnées de ressource, chaque challenge 401 contient resource_metadata (RFC 9728). Le corps contient type, title, status, code et un detail fixe ; il n'indique jamais pourquoi un jeton était invalide. Pour vos journaux, transmettez un callback d'erreur (OnError, onError, on_error) : il reçoit l'erreur du vérificateur, qui ne contient aucune valeur de jeton ni de revendication. Ne journalisez pas vous-même les en-têtes Authorization ou DPoP.

Cache de révocation (token.revoked)

Un jeton d'accès JWT reste valide jusqu'à son expiration. Pour rejeter plus tôt les jetons révoqués, traitez le webhook token.revoked et enregistrez son sélecteur dans un cache de révocation que le middleware consulte. Les SDK incluent un cache en mémoire : protect.NewMemoryRevocationCache (Go), createMemoryRevocationCache (Node.js) et MemoryRevocationCache (Python).

Un sélecteur désigne un identifiant de jeton (jti), une session (sid), un utilisateur (sub), une organisation (org_id), une application (client_id), ou les couples organisation + utilisateur et application + utilisateur. Un sélecteur jti révoque ce jeton. Les autres sélecteurs révoquent tous les jetons émis avant le not_before de l'événement ; les jetons émis plus tard sont acceptés. Les marqueurs sont conservés 24 heures et 1 minute par défaut, soit la durée de vie maximale possible d'un jeton d'accès plus la dérive d'horloge.

cache := protect.NewMemoryRevocationCache(0, nil)
m, _ := protect.New(v, protect.Options{PublicBaseURL: "https://api.acme.example", Revocation: cache})

// Dans votre handler de webhook token.revoked vérifié :
err := cache.Revoke(protect.Selector{SessionID: "ses_…"}, notBefore)

Le cache en mémoire appartient à un seul processus. Si votre API tourne sur plusieurs instances, implémentez l'interface du vérificateur de révocation sur un stockage partagé. Si le cache ne peut pas répondre, le middleware refuse la requête avec un 503.

Tests

Utilisez le kit de test hors ligne pour émettre des jetons dans vos tests de middleware. Le kit ne fournit pas d'assistant de preuve DPoP ; signez une preuve dans votre test avec la bibliothèque cryptographique du langage.