Vérifier une clé de votre wakapp
Protéger les routes de votre wakapp avec les clés wsk_ des organismes clients : introspection auprès de Wakastart, contrôle des droits et de l'organisme.
- Duration
- 30 min
This page has not been translated yet and is shown in French.
Quand un organisme client appelle l'API de votre wakapp avec une clé wsk_, votre wakapp demande à Wakastart ce que vaut cette clé : c'est l'introspection. Ce guide protège une route de votre wakapp par un droit, avec le kit Wakastart ou à la main.
Important
Les clés API des wakapps sont en cours de déploiement : l'opération POST /api/app-keys/introspect ne répond pas encore. Ce guide décrit le fonctionnement prévu.
Avant de commencer
- Votre wakapp dispose de sa clé
sk_dans un secret de son serveur (voir Stocker une clé en sécurité). Elle doit appartenir au même environnement que les clés que vos clients présenteront. - Votre catalogue de droits contient les droits que vos routes exigent, par exemple
formations.read(voir Définir les droits de votre application). - Votre serveur tourne sous Node.js 20 ou plus si vous utilisez le kit.
Appeler l'introspection
Envoyez le secret reçu dans le corps, et authentifiez l'appel avec la clé sk_ de votre wakapp dans x-api-key, sans en-tête Authorization. Wakastart en déduit votre application et votre environnement.
curl -s -X POST "https://api.wakastart.app/api/app-keys/introspect" \
-H "x-api-key: sk_test_exemple" \
-H "Content-Type: application/json" \
-d '{ "secret": "wsk_exemple3kTq9" }'const res = await fetch("https://api.wakastart.app/api/app-keys/introspect", {
method: "POST",
headers: { "x-api-key": process.env.WAKASTART_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({ secret: "wsk_exemple3kTq9" }),
signal: AbortSignal.timeout(5000),
});
const key = await res.json();Réponse attendue pour une clé valide (200) :
{
"active": true,
"key_id": "K7hq2P",
"type": "TECHNICAL",
"owner": null,
"customer": { "wid": "ALPHA1", "name": "Organisme Alpha" },
"app": "APPEX1",
"env": "prod",
"rights": ["formations.read", "participants.invite"],
"exp": null
}Pour toute autre clé, la réponse est { "active": false }, toujours en 200 et sans autre champ : clé inconnue, révoquée, expirée, suspendue, d'une autre application, d'un autre environnement, ou dont l'organisme n'a plus l'application. N'essayez pas d'en deviner la raison.
Les champs sont décrits dans la référence API. Retenez surtout :
rights: les droits effectifs, déjà croisés avec les droits actuels de l'utilisateur pour une clé liée ;customer: l'organisme de la clé, auquel vous limitez toutes vos requêtes ;key_id: l'identifiant public de la clé, à écrire dans vos journaux à la place du secret.
Appliquer la réponse
- Refusez l'appel avec un
401siactivene vaut pastrue. - Refusez avec un
403si un droit exigé par la route manque dansrights. - Limitez toutes vos lectures et écritures à
customer.wid. L'organisme vient de la clé, jamais d'un paramètre de la requête du client. - Appliquez vos propres limites de débit par client et le cloisonnement de ses données : ils restent l'affaire de votre wakapp.
Ne gardez aucune réponse positive en cache
Chaque appel d'un client entraîne une introspection : c'est ce qui rend la révocation immédiate. Vous pouvez en revanche garder une réponse négative une dizaine de secondes, indexée par l'empreinte SHA-256 du secret et jamais par le secret lui-même, pour ne pas relayer un essai de secrets en masse.
Refusez quand Wakastart ne répond pas
Si l'introspection échoue (délai dépassé, erreur réseau, réponse inattendue), refusez l'appel du client avec un 503. Ne laissez jamais passer une clé faute de réponse, et ne gardez pas cet échec en cache.
Protéger une route avec le kit
Le kit @wakastellar/wakastart-keys fait l'introspection, applique ces règles de cache et protège vos routes par droit.
Note
Le kit n'est pas encore publié sur npm. Il est fourni sous forme de module autonome, sans dépendance au reste de votre code, sur demande au support Wakastart : copiez-le dans votre backend. Les exemples importent le nom du futur paquet ; avec le module copié, remplacez-le par son chemin.
| Entrée | Contenu | Dépendances |
|---|---|---|
@wakastellar/wakastart-keys | Client, contexte, types, erreurs | Aucune |
@wakastellar/wakastart-keys/express | Middleware requireAppKey | Aucune |
@wakastellar/wakastart-keys/nest | Décorateur RequireAppKey, garde, module | @nestjs/common, @nestjs/core, rxjs |
Configurez-le par des variables d'environnement de votre serveur :
| Variable | Rôle | Défaut |
|---|---|---|
WAKASTART_API_URL | URL de base de l'API publique, sans /api : https://api.wakastart.app | Obligatoire |
WAKASTART_API_KEY | Clé sk_ de votre wakapp. Jamais dans le code, jamais dans une variable exposée au navigateur | Obligatoire |
WAKASTART_APP_WID | Facultatif : WID de votre application. Le kit refuse alors en plus toute clé dont l'introspection renvoie une autre application | — |
WAKASTART_TIMEOUT_MS | Délai d'attente de chaque appel à Wakastart, en millisecondes | 5000 |
Sans WAKASTART_API_URL ou WAKASTART_API_KEY, toutes les clés sont refusées avec un 503 ; le reste de votre wakapp n'est pas affecté.
import { Controller, Get } from "@nestjs/common";
import { CurrentAppKey, RequireAppKey } from "@wakastellar/wakastart-keys/nest";
import type { AppKeyPrincipal } from "@wakastellar/wakastart-keys";
@Controller("formations")
export class FormationsController {
constructor(private readonly formations: FormationsService) {}
@Get()
@RequireAppKey("formations.read")
list(@CurrentAppKey() key: AppKeyPrincipal) {
// Toujours limité à l'organisme de la clé
return this.formations.findAll(key.customer.wid);
}
}import { requireAppKey } from "@wakastellar/wakastart-keys/express";
app.get("/api/formations", requireAppKey("formations.read"), (req, res) => {
res.json(listFormations(req.appKey.customer.wid));
});req.appKey (ou @CurrentAppKey()) contient wid, type, customer, rights, owner, app, env et exp. Le secret n'y figure pas.
Le kit répond à vos clients ainsi :
| Cas | Statut | message |
|---|---|---|
Pas d'en-tête Authorization: Bearer | 401, avec WWW-Authenticate: Bearer | APP_KEY_MISSING |
| Clé inconnue, révoquée, expirée, d'une autre application ou d'un autre environnement | 401 | APP_KEY_INVALID |
| Droit manquant | 403, avec details.missing | APP_KEY_RIGHTS_MISSING |
| Wakastart injoignable, délai dépassé, réponse inattendue | 503 | WAKASTART_UNAVAILABLE |
Protéger une route sans le kit
Le contrat s'applique aussi à la main. Exemple de middleware Express :
import type { NextFunction, Request, Response } from "express";
export function requireAppKey(...required: string[]) {
return async (req: Request, res: Response, next: NextFunction) => {
const auth = req.headers.authorization;
if (!auth?.startsWith("Bearer ")) {
return res.status(401).json({ statusCode: 401, message: "APP_KEY_MISSING" });
}
let key: { active: boolean; rights?: string[]; customer?: { wid: string } };
try {
const r = await fetch(`${process.env.WAKASTART_API_URL}/api/app-keys/introspect`, {
method: "POST",
// Clé sk_ de la wakapp, et surtout pas d'en-tête Authorization
headers: { "x-api-key": process.env.WAKASTART_API_KEY!, "Content-Type": "application/json" },
body: JSON.stringify({ secret: auth.slice(7) }),
signal: AbortSignal.timeout(5000),
});
if (!r.ok) throw new Error(`Wakastart ${r.status}`);
key = await r.json();
} catch {
// On refuse quand on ne peut pas vérifier
return res.status(503).json({ statusCode: 503, message: "WAKASTART_UNAVAILABLE" });
}
if (key.active !== true) {
return res.status(401).json({ statusCode: 401, message: "APP_KEY_INVALID" });
}
const missing = required.filter((code) => !key.rights!.includes(code));
if (missing.length) {
return res.status(403).json({ statusCode: 403, message: "APP_KEY_RIGHTS_MISSING", details: { missing } });
}
res.locals.appKey = key; // aucune mise en cache de cette réponse
next();
};
}Vérifier le résultat
Appelez votre route avec une clé de test qui porte le droit, puis sans le droit :
curl -s -o /dev/null -w "%{http_code}\n" "https://mon-app.exemple.fr/api/formations" \
-H "Authorization: Bearer wsk_exemple3kTq9"Réponse attendue : 200 avec la clé qui porte formations.read, 403 avec une clé qui ne le porte pas, 401 après la révocation de la clé dans la console.
Bonnes pratiques
- Journalisez le
key_id, jamais le secret ni son empreinte. - N'envoyez la clé du client à Wakastart que dans le corps de l'introspection.
- Documentez pour vos clients l'en-tête attendu (
Authorization: Bearer <clé>) et les droits de votre catalogue utiles à chaque route.