Vérifier la signature d’un Open Badge en Node.js, Python et Go

Trois exemples de code fonctionnels (Node, Python, Go) pour récupérer un justificatif Open Badge signé, résoudre la clé publique de l’émetteur et vérifier la signature JWS.

Nacho Coll Par Mis à jour 10 min de lecture
Trois exemples de code fonctionnels (Node, Python, Go) pour récupérer un justificatif Open Badge signé, résoudre la clé publique de l’émetteur et vérifier la signature JWS.

Si vous délivrez des justificatifs, l’essentiel du travail de vérification se fait sans vous : un bénéficiaire partage un lien, un employeur clique dessus, et la page de vérification fait le reste. Mais tôt ou tard, quelqu’un pose une question plus pointue : « Comment savoir que ce fichier a vraiment été signé par vous, et qu’il n’a pas été modifié après coup ? » Cette question trouve sa réponse dans une signature numérique, et la vérifier demande environ quinze lignes de code dans n’importe quel langage courant.

Ce tutoriel vous montre, étape par étape, comment vérifier un justificatif Open Badges 3.0 signé et délivré via https://badges.ninja, en Node.js, Python et Go. Vous n’avez besoin d’exécuter rien de tout cela pour délivrer des justificatifs. C’est destiné à celles et ceux qui veulent auditer le système, créer un outil de vérification interne, ou simplement comprendre ce que « vérifiable » signifie concrètement.

Ce que vous vérifiez réellement

Il existe deux couches de vérification dans Open Badges, et mieux vaut les distinguer.

La vérification hébergée correspond au modèle Open Badges 2.0. L’attribution possède une URL publique, et quiconque l’ouvre voit l’émetteur, le badge, l’identité hachée du bénéficiaire et le statut. La confiance vient du fait que les données sont servies depuis le domaine de l’émetteur lui-même. Si vous pouvez atteindre la page sur https://badges.ninja, le justificatif est authentique. Aucun code ni aucune signature n’est nécessaire.

La vérification de signature correspond au modèle Open Badges 3.0, construit sur les W3C Verifiable Credentials. Le justificatif est empaqueté sous forme de jeton signé : on peut donc le contrôler hors ligne, des années plus tard, même s’il a été copié dans un portefeuille ou joint à un e-mail. La confiance vient des mathématiques : le jeton porte une signature que seul le détenteur de la clé privée de l’émetteur a pu produire.

Sur https://badges.ninja, chaque attribution est disponible sous les deux formes. Cet article traite de la seconde. Pour comprendre la différence entre les deux versions, lisez Open Badges v2 vs v3, et pour une visite guidée du JSON hébergé, consultez le tour d’horizon du JSON-LD Open Badge.

Les éléments en jeu

Le justificatif signé est un VC-JWT : un JWS compact, c’est-à-dire trois chaînes base64url séparées par des points.

header.payload.signature
  • Le header indique comment le jeton a été signé. Pour nos justificatifs, il contient alg: EdDSA, typ: JWT et un kid (identifiant de clé) de la forme did:web:api.badges.ninja#<thumbprint>.
  • Le payload contient les revendications, dont iss (le DID de l’émetteur did:web:api.badges.ninja), jti (l’identifiant du justificatif), nbf (valide à partir de), un exp facultatif (expiration) et un objet vc avec l’OpenBadgeCredential proprement dit.
  • La signature est une signature Ed25519 portant sur les octets exacts de header.payload.

La clé publique qui permet de contrôler la signature est publiée par l’émetteur à deux endroits, sans authentification :

  • https://api.badges.ninja/.well-known/jwks.json renvoie un JWK Set.
  • https://api.badges.ninja/.well-known/did.json renvoie le document DID de did:web:api.badges.ninja.

Le kid du JWKS est l’empreinte (thumbprint) RFC 7638 de la clé. Le kid de l’en-tête du jeton est l’URL DID, et son fragment (la partie après #) est cette même empreinte. C’est ce fragment qui vous permet de choisir la bonne clé.

La recette de vérification

Chaque langage suit les mêmes cinq étapes :

  1. Récupérer le justificatif signé depuis le point d’accès public.
  2. Découper le jeton en ses trois parties.
  3. Lire le header, vérifier que alg vaut exactement EdDSA, et extraire l’empreinte de kid.
  4. Récupérer le JWKS et trouver la clé dont le kid correspond.
  5. Vérifier la signature Ed25519 de header.payload avec cette clé.

Le point d’accès du justificatif est public et prend l’identifiant de l’attribution (le même GUID que dans une URL de vérification comme https://badges.ninja/awards/<awardId>) :

curl https://api.badges.ninja/certify-badge/award/<awardId>/vc

Par défaut, il renvoie le VC-JWT signé en application/jwt. Ajoutez ?format=json pour obtenir le JSON du justificatif non signé, à lire. La référence de vérification documente les deux.

Notez qu’il n’existe pas de point d’accès « vérifiez ça pour moi », et c’est voulu. Un serveur qui vous répond « oui, c’est valide » vous demande de faire confiance au serveur. L’intérêt d’une signature, c’est justement que vous pouvez la contrôler vous-même à l’aide d’une clé publiée.

Node.js

Le module crypto intégré à Node prend en charge Ed25519 et l’import de JWK, donc aucune dépendance n’est nécessaire.

import crypto from "node:crypto";
const API = "https://api.badges.ninja";
const awardId = process.argv[2];
// —— 1. fetch the signed credential
const jwt = (await (await fetch(`${API}/certify-badge/award/${awardId}/vc`)).text()).trim();
// —— 2. split into parts
const [h, p, s] = jwt.split(".");
const header = JSON.parse(Buffer.from(h, "base64url").toString());
const payload = JSON.parse(Buffer.from(p, "base64url").toString());
// —— 3. refuse anything but EdDSA
if (header.alg !== "EdDSA") throw new Error(`unexpected alg: ${header.alg}`);
const thumbprint = header.kid.split("#")[1];
// —— 4. resolve the public key
const jwks = await (await fetch(`${API}/.well-known/jwks.json`)).json();
const jwk = jwks.keys.find((k) => k.kid === thumbprint);
if (!jwk) throw new Error("no matching key in JWKS");
const publicKey = crypto.createPublicKey({ key: jwk, format: "jwk" });
// —— 5. verify the signature over "header.payload"
const ok = crypto.verify(null, Buffer.from(`${h}.${p}`), publicKey, Buffer.from(s, "base64url"));
console.log(ok ? "signature valid" : "signature INVALID");
console.log("issuer:", payload.iss, "credential:", payload.jti);

L’argument d’algorithme null est correct : avec Ed25519, le type de clé fixe l’algorithme. Si vous préférez une bibliothèque, jose fait le même travail avec compactVerify et importJWK, et s’occupe des contrôles d’en-tête à votre place.

Python

Le paquet cryptography vous donne Ed25519 directement. Installez-le avec pip install cryptography requests.

import base64, json, sys
import requests
from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
API = "https://api.badges.ninja"
award_id = sys.argv[1]
def b64url(data: str) -> bytes:
    return base64.urlsafe_b64decode(data + "=" * (-len(data) % 4))
# —— 1. fetch the signed credential
jwt = requests.get(f"{API}/certify-badge/award/{award_id}/vc").text.strip()
# —— 2. split into parts
h, p, s = jwt.split(".")
header = json.loads(b64url(h))
payload = json.loads(b64url(p))
# —— 3. refuse anything but EdDSA
if header["alg"] != "EdDSA":
    raise SystemExit(f"unexpected alg: {header['alg']}")
thumbprint = header["kid"].split("#")[1]
# —— 4. resolve the public key
keys = requests.get(f"{API}/.well-known/jwks.json").json()["keys"]
jwk = next((k for k in keys if k["kid"] == thumbprint), None)
if jwk is None:
    raise SystemExit("no matching key in JWKS")
public_key = Ed25519PublicKey.from_public_bytes(b64url(jwk["x"]))
# —— 5. verify the signature over "header.payload"
try:
    public_key.verify(b64url(s), f"{h}.{p}".encode())
    print("signature valid")
except InvalidSignature:
    print("signature INVALID")
print("issuer:", payload["iss"], "credential:", payload["jti"])

Python n’a pas d’import JWK pour Ed25519 dans cette bibliothèque : nous décodons donc nous-mêmes la coordonnée x (la clé publique brute de 32 octets). C’est tout ce que contient un JWK de type OKP avec la courbe Ed25519.

Go

La bibliothèque standard de Go couvre tout, y compris crypto/ed25519.

package main
import (
	"crypto/ed25519"
	"encoding/base64"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"os"
	"strings"
)
const api = "https://api.badges.ninja"
func get(url string) []byte {
	res, err := http.Get(url)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	b, _ := io.ReadAll(res.Body)
	return b
}
func main() {
	awardID := os.Args[1]
	// —— 1. fetch the signed credential
	jwt := strings.TrimSpace(string(get(api + "/certify-badge/award/" + awardID + "/vc")))
	// —— 2. split into parts
	parts := strings.Split(jwt, ".")
	if len(parts) != 3 {
		panic("not a compact JWS")
	}
	enc := base64.RawURLEncoding
	hb, _ := enc.DecodeString(parts[0])
	var header struct{ Alg, Kid string }
	json.Unmarshal(hb, &header)
	// —— 3. refuse anything but EdDSA
	if header.Alg != "EdDSA" {
		panic("unexpected alg: " + header.Alg)
	}
	thumbprint := strings.Split(header.Kid, "#")[1]
	// —— 4. resolve the public key
	var jwks struct {
		Keys []struct{ Kid, X string } `json:"keys"`
	}
	json.Unmarshal(get(api+"/.well-known/jwks.json"), &jwks)
	var pub ed25519.PublicKey
	for _, k := range jwks.Keys {
		if k.Kid == thumbprint {
			pub, _ = enc.DecodeString(k.X)
		}
	}
	if pub == nil {
		panic("no matching key in JWKS")
	}
	// —— 5. verify the signature over "header.payload"
	sig, _ := enc.DecodeString(parts[2])
	ok := ed25519.Verify(pub, []byte(parts[0]+"."+parts[1]), sig)
	fmt.Println("signature valid:", ok)
}

Lancez-le avec go run main.go <awardId>. La gestion des erreurs est allégée pour la lisibilité ; dans un vrai outil, vous contrôleriez chaque décodage.

Erreurs courantes et comment les lire

La clé est introuvable dans le JWKS. Vous avez comparé le kid complet de l’en-tête du jeton (did:web:api.badges.ninja#abc) avec le kid du JWKS (abc). Comparez uniquement le fragment après #. Si le fragment ne correspond toujours pas, l’émetteur a peut-être fait pivoter ses clés depuis l’émission du jeton ; récupérez le document DID et examinez ses entrées verificationMethod.

Signature invalide sur un jeton que vous venez de télécharger. Vérifiez que vous avez contrôlé header.payload sous sa forme base64url d’origine, et non un JSON réencodé. Resérialiser le JSON modifie les octets et casse la signature. Vérifiez aussi qu’il n’y a pas de saut de ligne final dans le jeton téléchargé.

Confusion d’algorithme. L’attaque JWT classique consiste en un jeton qui déclare alg: none ou bascule vers un algorithme symétrique pour inciter un vérificateur à l’accepter. Nos exemples l’évitent en codant en dur l’algorithme attendu, EdDSA, et en refusant tout le reste. Ne laissez jamais le jeton choisir comment il est vérifié.

Erreurs de remplissage base64. JWS utilise du base64url sans remplissage. Python demande de rajouter le remplissage (voir plus haut), et Go demande RawURLEncoding, et non URLEncoding.

Signature valide, mais le justificatif est-il toujours bon ? Une signature prouve l’authenticité et l’intégrité, pas le statut actuel. Un justificatif peut être correctement signé et pourtant révoqué ou expiré. Vérifiez exp dans le payload, ainsi que le statut de révocation décrit ci-dessous.

N’oubliez pas la révocation

Chaque justificatif Open Badges 3.0 émis par https://badges.ninja contient une entrée credentialStatus conforme à la Bitstring Status List du W3C. Elle pointe vers un justificatif de liste de statuts que vous pouvez récupérer à /certify-badge/status/<listId>. Quand un émetteur révoque une attribution, un bit change dans cette liste ; la liste est mise en cache environ une minute, si bien que les révocations parviennent rapidement aux vérificateurs. Décodez la liste et lisez le bit à la position statusListIndex du justificatif : 1 signifie révoqué, 0 signifie actif. La référence de vérification inclut un court exemple Node de ce contrôle de bit.

Un vérificateur complet fait trois choses : il vérifie la signature, contrôle l’expiration et contrôle le bit de révocation. Si vous voulez voir à quoi ressemble la révocation côté émetteur, l’action du tableau de bord est décrite dans le guide des attributions.

Quand vous n’avez besoin de rien de tout cela

La plupart des responsables de programme n’écriront jamais ce code, et c’est très bien ainsi. Pour les vérifications du quotidien, ouvrez la page publique de l’attribution à l’adresse https://badges.ninja/awards/<awardId> et lisez-la. La page ne demande ni inscription ni clé, et elle affiche l’émetteur, le badge et le statut. Les bénéficiaires peuvent aussi télécharger le Verifiable Credential depuis le menu Download de leur page publique de justificatif, et l’importer dans n’importe quel portefeuille compatible Open Badges 3.0.

La vérification de signature devient précieuse quand :

  • un employeur ou une université veut automatiser le contrôle des justificatifs qu’il reçoit ;
  • vous construisez un système d’archivage qui conserve des copies de justificatifs et doit prouver qu’elles n’ont pas été altérées ;
  • un auditeur demande la preuve que vos justificatifs sont vérifiables de façon indépendante, et pas seulement « faites confiance à notre site ».

La configuration de clé API utilisée pour l’émission n’est pas nécessaire ici, car tous ces points d’accès sont publics. Si vous souhaitez délivrer des justificatifs depuis du code, le guide de démarrage de l’API vous accompagne dans la création d’une clé et de votre première attribution.

API Keys — empty state

Référence rapide

ÉlémentValeur
Justificatif signéGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
JSON non signé, à liremême URL avec ?format=json
DID de l’émetteurdid:web:api.badges.ninja
Clés publiques/.well-known/jwks.json et /.well-known/did.json
AlgorithmeEd25519 (EdDSA)
Correspondance de cléle fragment du kid de l’en-tête est égal au kid du JWKS
RévocationcredentialStatus pointant vers /certify-badge/status/<listId>

Pour conclure

Vérifier la signature d’un Open Badge est une routine courte et mécanique : récupérer le jeton, imposer l’algorithme, trouver la clé grâce à son empreinte, et contrôler la signature Ed25519 sur les deux premiers segments. Ajoutez les contrôles d’expiration et de révocation, et vous obtenez un vérificateur qui ne fait confiance qu’à la clé publiée par l’émetteur. Cette indépendance est précisément ce qui donne à un justificatif numérique plus de valeur qu’un PDF.

Prêt à délivrer votre premier justificatif vérifiable ? Commencez gratuitement sur badges.ninja — concepteur visuel, page de vérification publique, certificat PDF, sortie Open Badge v2.0. Aucune carte bancaire requise.

Nacho Coll

À propos de l'auteur

Founder & Engineer at Badges Ninja

Nacho founded Badges Ninja to make issuing verifiable digital credentials as simple as a single API call — Open Badge v2.0 badges and certificates, minted, hosted, and verifiable without standing up your own issuer infrastructure. Writes about the Open Badges spec, credential verification, and running a credentialing platform serverless on AWS, from the operator side of the wire.

Retour au blog

Articles similaires