Aller au contenu

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.

GuideDéveloppeurBêta
Durée
30 min
Voir en Markdown

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.
Chargement du schéma…

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.

Bash
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" }'
TypeScript
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) :

JSON
{
  "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

  1. Refusez l'appel avec un 401 si active ne vaut pas true.
  2. Refusez avec un 403 si un droit exigé par la route manque dans rights.
  3. 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.
  4. 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éeContenuDépendances
@wakastellar/wakastart-keysClient, contexte, types, erreursAucune
@wakastellar/wakastart-keys/expressMiddleware requireAppKeyAucune
@wakastellar/wakastart-keys/nestDécorateur RequireAppKey, garde, module@nestjs/common, @nestjs/core, rxjs

Configurez-le par des variables d'environnement de votre serveur :

VariableRôleDéfaut
WAKASTART_API_URLURL de base de l'API publique, sans /api : https://api.wakastart.appObligatoire
WAKASTART_API_KEYClé sk_ de votre wakapp. Jamais dans le code, jamais dans une variable exposée au navigateurObligatoire
WAKASTART_APP_WIDFacultatif : WID de votre application. Le kit refuse alors en plus toute clé dont l'introspection renvoie une autre application—
WAKASTART_TIMEOUT_MSDélai d'attente de chaque appel à Wakastart, en millisecondes5000

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é.

TypeScript
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);
  }
}
TypeScript
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 :

CasStatutmessage
Pas d'en-tête Authorization: Bearer401, avec WWW-Authenticate: BearerAPP_KEY_MISSING
Clé inconnue, révoquée, expirée, d'une autre application ou d'un autre environnement401APP_KEY_INVALID
Droit manquant403, avec details.missingAPP_KEY_RIGHTS_MISSING
Wakastart injoignable, délai dépassé, réponse inattendue503WAKASTART_UNAVAILABLE

Protéger une route sans le kit

Le contrat s'applique aussi à la main. Exemple de middleware Express :

TypeScript
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 :

Bash
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.

Voir aussi