Verificare la firma di un Open Badge in Node.js, Python e Go
Tre esempi di codice funzionanti (Node, Python, Go) per recuperare una credenziale Open Badge firmata, risolvere la chiave pubblica dell'emittente e verificare la firma JWS.
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.
Se emetti credenziali, la maggior parte del lavoro di verifica avviene senza di te: un destinatario condivide un link, un datore di lavoro ci clicca e la pagina di verifica fa il resto. Prima o poi, però, qualcuno farà una domanda più incisiva. «Come faccio a sapere che questo file è stato davvero firmato da te e non modificato in seguito?» A rispondere è una firma digitale, e controllarne una richiede circa quindici righe di codice in qualsiasi linguaggio diffuso.
Questo tutorial mostra, passo dopo passo, come verificare una credenziale Open Badges 3.0 firmata ed emessa tramite https://badges.ninja, in Node.js, Python e Go. Non serve eseguire nulla di tutto ciò per emettere credenziali. È per chi vuole fare un audit del sistema, costruire uno strumento di verifica interno o semplicemente capire cosa significhi «verificabile» in pratica.
Cosa stai davvero verificando
In Open Badges esistono due livelli di verifica ed è utile tenerli separati.
La verifica ospitata è il modello di Open Badges 2.0. L’assegnazione ha un URL pubblico e chiunque lo apra vede l’emittente, il badge, l’identità con hash del destinatario e lo stato. La fiducia deriva dal fatto che i dati vengono serviti dal dominio dell’emittente stesso. Se riesci a raggiungere la pagina su https://badges.ninja, la credenziale è autentica. Non servono codice né firma.
La verifica della firma è il modello di Open Badges 3.0, basato sulle Verifiable Credentials del W3C. La credenziale è impacchettata come token firmato, quindi può essere controllata offline, anni dopo, anche se è stata copiata in un wallet o in un allegato email. La fiducia deriva dalla matematica: il token contiene una firma che solo chi possiede la chiave privata dell’emittente poteva produrre.
Su https://badges.ninja ogni assegnazione è disponibile in entrambe le forme. Questo articolo parla della seconda. Per capire le differenze tra le due versioni leggi Open Badges v2 vs v3; per una panoramica del JSON ospitato, vedi la guida al JSON-LD di Open Badge.
Gli ingranaggi
La credenziale firmata è un VC-JWT: un JWS compatto, ovvero tre stringhe base64url separate da punti.
header.payload.signature
- L’header indica come è stato firmato. Per le nostre credenziali contiene
alg: EdDSA,typ: JWTe unkid(key id) simile adid:web:api.badges.ninja#<thumbprint>. - Il payload contiene le dichiarazioni (claim), tra cui
iss(il DID dell’emittentedid:web:api.badges.ninja),jti(l’id della credenziale),nbf(valida da), unexpfacoltativo (scadenza) e un oggettovccon l’OpenBadgeCredentialvera e propria. - La firma è una firma Ed25519 calcolata sui byte esatti di
header.payload.
La chiave pubblica che controlla la firma è pubblicata dall’emittente in due punti, entrambi senza autenticazione:
https://api.badges.ninja/.well-known/jwks.jsonrestituisce un JWK Set.https://api.badges.ninja/.well-known/did.jsonrestituisce il documento DID perdid:web:api.badges.ninja.
Il kid del JWKS è il thumbprint RFC 7638 della chiave. Il kid nell’header del token è l’URL DID e il suo frammento (la parte dopo #) è lo stesso thumbprint. Quel frammento è ciò che ti permette di scegliere la chiave giusta.
La ricetta di verifica
Ogni linguaggio segue gli stessi cinque passaggi:
- Recupera la credenziale firmata dall’endpoint pubblico.
- Dividi il token nelle sue tre parti.
- Leggi l’header, controlla che
algsia esattamenteEdDSAe prendi il thumbprint dakid. - Recupera il JWKS e trova la chiave il cui
kidcorrisponde. - Verifica la firma Ed25519 su
header.payloadcon quella chiave.
L’endpoint della credenziale è pubblico e accetta l’id dell’assegnazione (lo stesso GUID che vedi in un URL di verifica come https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Per impostazione predefinita restituisce il VC-JWT firmato come application/jwt. Aggiungi ?format=json per ottenere il JSON non firmato della credenziale, da leggere. Il riferimento sulla verifica documenta entrambi.
Nota che non esiste un endpoint separato «verificalo per me», ed è voluto. Un server che ti dice «sì, valido» ti chiede di fidarti del server. Il senso di una firma è proprio poterla controllare da solo con una chiave pubblicata.
Node.js
Il modulo integrato crypto di Node supporta Ed25519 e l’importazione JWK, quindi non servono dipendenze.
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’argomento null per l’algoritmo è corretto: con Ed25519 è il tipo di chiave a fissare l’algoritmo. Se preferisci una libreria, jose fa lo stesso lavoro con compactVerify e importJWK e gestisce per te i controlli sull’header.
Python
Il pacchetto cryptography ti dà Ed25519 direttamente. Installalo con 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"])
In questa libreria Python non ha un’importazione JWK per Ed25519, quindi decodifichiamo noi la coordinata x (la chiave pubblica grezza di 32 byte). È tutto ciò che contiene un JWK di tipo OKP con curva Ed25519.
Go
La libreria standard di Go copre tutto, incluso 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)
}
Eseguilo con go run main.go <awardId>. La gestione degli errori è ridotta per leggibilità; in uno strumento reale controlleresti ogni decodifica.
Errori comuni e come interpretarli
La chiave non si trova nel JWKS. Hai confrontato il kid completo dell’header del token (did:web:api.badges.ninja#abc) con il kid del JWKS (abc). Confronta solo il frammento dopo #. Se il frammento continua a non corrispondere, l’emittente potrebbe aver ruotato le chiavi dopo la creazione del token: recupera il documento DID e guarda le voci di verificationMethod.
Firma non valida su un token appena scaricato. Controlla di aver verificato header.payload come testo base64url originale, non come JSON ricodificato. Riserializzare il JSON cambia i byte e rompe la firma. Controlla anche che non ci sia un a capo finale nel token scaricato.
Confusione sull’algoritmo. Il classico attacco JWT è un token che dichiara alg: none o passa a un algoritmo simmetrico per ingannare un verificatore e fargli accettare il token. I nostri esempi lo evitano fissando nel codice l’algoritmo atteso, EdDSA, e rifiutando tutto il resto. Non lasciare mai che sia il token a scegliere come viene verificato.
Errori di padding base64. Il JWS usa base64url senza padding. Python richiede di riaggiungere il padding (mostrato sopra), e Go richiede RawURLEncoding, non URLEncoding.
Firma valida, ma la credenziale è ancora buona? Una firma prova autenticità e integrità, non lo stato attuale. Una credenziale può essere firmata correttamente ed essere comunque revocata o scaduta. Controlla exp nel payload e controlla lo stato di revoca descritto di seguito.
Non dimenticare la revoca
Ogni credenziale Open Badges 3.0 di https://badges.ninja include una voce credentialStatus conforme alla W3C Bitstring Status List. Punta a una credenziale di lista di stato che puoi recuperare da /certify-badge/status/<listId>. Quando un emittente revoca un’assegnazione, in quella lista si inverte un bit; la lista resta in cache per circa un minuto, quindi le revoche raggiungono rapidamente i verificatori. Decodifica la lista e leggi il bit in corrispondenza di statusListIndex della credenziale: 1 significa revocata, 0 significa attiva. Il riferimento sulla verifica include un breve esempio in Node di questo controllo del bit.
Un verificatore completo fa tre cose: verifica la firma, controlla la scadenza e controlla il bit di revoca. Se vuoi vedere come appare la revoca dal lato dell’emittente, l’azione nella dashboard è descritta nella guida alle assegnazioni.
Quando non ti serve nulla di tutto questo
La maggior parte dei responsabili di programma non scriverà mai questo codice, e va bene così. Per i controlli quotidiani, apri la pagina pubblica dell’assegnazione su https://badges.ninja/awards/<awardId> e leggila. La pagina non richiede registrazione né chiave e mostra emittente, badge e stato. I destinatari possono anche scaricare la Verifiable Credential dal menu Download della loro pagina pubblica della credenziale e importarla in qualsiasi wallet Open Badges 3.0.
La verifica della firma diventa preziosa quando:
- un datore di lavoro o un’università vuole automatizzare i controlli sulle credenziali che riceve;
- stai costruendo un sistema di registrazione che conserva copie delle credenziali e deve dimostrare che non sono state alterate;
- un auditor chiede la prova che le tue credenziali siano verificabili in modo indipendente, non solo «fidatevi del nostro sito».
Qui non serve la stessa configurazione della chiave API usata per l’emissione, perché tutti questi endpoint sono pubblici. Se invece vuoi emettere credenziali da codice, la guida rapida all’API ti accompagna nella creazione di una chiave e della tua prima assegnazione.

Riferimento rapido
| Elemento | Valore |
|---|---|
| Credenziale firmata | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| JSON non firmato da leggere | stesso URL con ?format=json |
| DID dell’emittente | did:web:api.badges.ninja |
| Chiavi pubbliche | /.well-known/jwks.json e /.well-known/did.json |
| Algoritmo | Ed25519 (EdDSA) |
| Corrispondenza della chiave | il frammento del kid dell’header è uguale al kid del JWKS |
| Revoca | credentialStatus che punta a /certify-badge/status/<listId> |
Per concludere
Verificare la firma di un Open Badge è una routine breve e meccanica: recupera il token, fissa l’algoritmo, trova la chiave tramite thumbprint e controlla la firma Ed25519 sui primi due segmenti. Aggiungi i controlli di scadenza e revoca e avrai un verificatore che non si fida di nessuno tranne che della chiave pubblicata dall’emittente. È proprio questa indipendenza a rendere una credenziale digitale più preziosa di un PDF.
Pronto a emettere la tua prima credenziale verificabile? Inizia gratis su badges.ninja — designer visuale, pagina di verifica pubblica, certificato PDF, output Open Badge v2.0. Nessuna carta di credito richiesta.
Come è stato realizzato questo articolo
Alcuni articoli di questo blog vengono redatti con l'aiuto di un assistente IA e poi revisionati, verificati e modificati dal team di Badges Ninja prima della pubblicazione. Ogni esempio di codice e ogni prezzo viene verificato rispetto al prodotto live. Scopri di più sul nostro processo editoriale e sull'uso dell'IA nella nostra pagina sul processo editoriale .

Informazioni sull'autore
Nacho Coll
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.
Altri articoli di Nacho Coll
- Open Badges per i bootcamp di coding: emettere credenziali verificabili su scala di coorte19 nov 2026 · 12min di lettura
- Configurare i webhook per gli eventi dei badge: integrazione in tempo reale con il tuo backend16 nov 2026 · 9min di lettura
- Scadenza e rinnovo degli Open Badge: gestire il ciclo di vita delle credenziali a tempo12 nov 2026 · 12min di lettura


