Open-Badge-Signatur in Node.js, Python und Go verifizieren

Drei funktionierende Codebeispiele (Node, Python, Go), um ein signiertes Open-Badge-Credential abzurufen, den öffentlichen Schlüssel des Ausstellers aufzulösen und die JWS-Signatur zu verifizieren.

Nacho Coll Von Aktualisiert 9 Min. Lesezeit
Drei funktionierende Codebeispiele (Node, Python, Go), um ein signiertes Open-Badge-Credential abzurufen, den öffentlichen Schlüssel des Ausstellers aufzulösen und die JWS-Signatur zu verifizieren.

Wenn du Credentials ausstellst, läuft der Großteil der Verifizierung ohne dein Zutun: Ein Empfänger teilt einen Link, ein Arbeitgeber klickt darauf, und die Verifizierungsseite erledigt den Rest. Aber früher oder später stellt jemand eine schärfere Frage. „Woher weiß ich, dass diese Datei wirklich von dir signiert und nicht nachträglich verändert wurde?“ Diese Frage beantwortet eine digitale Signatur, und sie zu prüfen kostet in jeder gängigen Sprache etwa fünfzehn Zeilen Code.

Dieses Tutorial zeigt Schritt für Schritt, wie du ein signiertes Open-Badges-3.0-Credential, das über https://badges.ninja ausgestellt wurde, in Node.js, Python und Go verifizierst. Du musst nichts davon ausführen, um Credentials auszustellen. Es ist für alle, die das System auditieren, ein internes Verifizierungstool bauen oder einfach verstehen wollen, was „verifizierbar“ in der Praxis bedeutet.

Was du eigentlich verifizierst

Bei Open Badges gibt es zwei Verifizierungsebenen, und es hilft, sie auseinanderzuhalten.

Gehostete Verifizierung ist das Modell von Open Badges 2.0. Die Auszeichnung hat eine öffentliche URL, und wer sie öffnet, sieht den Aussteller, das digitale Abzeichen, die gehashte Identität des Empfängers und den Status. Das Vertrauen entsteht dadurch, dass die Daten von der eigenen Domain des Ausstellers ausgeliefert werden. Wenn du die Seite auf https://badges.ninja erreichst, ist das Credential echt. Dafür braucht es weder Code noch Signatur.

Signaturverifizierung ist das Modell von Open Badges 3.0, aufgebaut auf W3C Verifiable Credentials. Das Credential wird als signiertes Token verpackt und lässt sich deshalb offline prüfen, noch Jahre später, selbst wenn es in eine Wallet oder einen E-Mail-Anhang kopiert wurde. Das Vertrauen kommt aus der Mathematik: Das Token trägt eine Signatur, die nur der Inhaber des privaten Schlüssels des Ausstellers erzeugen konnte.

Auf https://badges.ninja gibt es jede Auszeichnung in beiden Formen. Dieser Artikel handelt von der zweiten. Wenn du wissen willst, wie sich die beiden Versionen unterscheiden, lies Open Badges v2 vs v3, und für eine Tour durch das gehostete JSON siehe die Open-Badge-JSON-LD-Anleitung.

Die beweglichen Teile

Das signierte Credential ist ein VC-JWT: ein kompaktes JWS, also drei base64url-Strings, getrennt durch Punkte.

header.payload.signature
  • Der Header sagt, wie signiert wurde. Bei unseren Credentials enthält er alg: EdDSA, typ: JWT und eine kid (Schlüssel-ID), die so aussieht: did:web:api.badges.ninja#<thumbprint>.
  • Der Payload enthält die Claims, darunter iss (die Aussteller-DID did:web:api.badges.ninja), jti (die Credential-ID), nbf (gültig ab), ein optionales exp (Ablauf) und ein vc-Objekt mit dem eigentlichen OpenBadgeCredential.
  • Die Signatur ist eine Ed25519-Signatur über die exakten Bytes von header.payload.

Der öffentliche Schlüssel, der die Signatur prüft, wird vom Aussteller an zwei Stellen veröffentlicht, beide ohne Authentifizierung:

  • https://api.badges.ninja/.well-known/jwks.json liefert ein JWK Set.
  • https://api.badges.ninja/.well-known/did.json liefert das DID-Dokument für did:web:api.badges.ninja.

Die JWKS-kid ist der RFC-7638-Thumbprint des Schlüssels. Die kid im Token-Header ist die DID-URL, und ihr Fragment (der Teil nach #) ist genau dieser Thumbprint. Über dieses Fragment findest du den richtigen Schlüssel.

Das Verifizierungsrezept

In jeder Sprache gelten dieselben fünf Schritte:

  1. Das signierte Credential vom öffentlichen Endpunkt abrufen.
  2. Das Token in seine drei Teile zerlegen.
  3. Den Header lesen, prüfen, dass alg exakt EdDSA ist, und den Thumbprint aus kid übernehmen.
  4. Das JWKS abrufen und den Schlüssel mit passender kid finden.
  5. Die Ed25519-Signatur über header.payload mit diesem Schlüssel verifizieren.

Der Credential-Endpunkt ist öffentlich und erwartet die Award-ID (dieselbe GUID wie in einer Verifizierungs-URL wie https://badges.ninja/awards/<awardId>):

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

Standardmäßig liefert er das signierte VC-JWT als application/jwt. Mit ?format=json bekommst du das unsignierte Credential-JSON zum Lesen. Die Verifizierungsreferenz dokumentiert beides.

Beachte: Es gibt keinen separaten Endpunkt „verifiziere das für mich“, und das ist Absicht. Ein Server, der dir sagt „ja, gültig“, verlangt von dir, dem Server zu vertrauen. Der ganze Sinn einer Signatur ist, dass du sie selbst gegen einen veröffentlichten Schlüssel prüfen kannst.

Node.js

Das eingebaute crypto-Modul von Node unterstützt Ed25519 und den JWK-Import, du brauchst also keine Abhängigkeiten.

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);

Das null als Algorithmus-Argument ist richtig: Bei Ed25519 legt der Schlüsseltyp den Algorithmus fest. Wenn du lieber eine Bibliothek nutzt: jose erledigt dasselbe mit compactVerify und importJWK und übernimmt die Header-Prüfungen für dich.

Python

Das Paket cryptography bietet dir Ed25519 direkt. Installiere es mit 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 hat in dieser Bibliothek keinen JWK-Import für Ed25519, also dekodieren wir die x-Koordinate (den rohen 32-Byte-Public-Key) selbst. Mehr steckt in einem JWK vom Typ OKP mit der Kurve Ed25519 nicht.

Go

Die Standardbibliothek von Go deckt alles ab, auch 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)
}

Starte es mit go run main.go <awardId>. Die Fehlerbehandlung ist der Lesbarkeit halber gekürzt; in einem echten Tool würdest du jede Dekodierung prüfen.

Häufige Fehler und wie du sie liest

Der Schlüssel wird im JWKS nicht gefunden. Du hast die vollständige kid aus dem Token-Header (did:web:api.badges.ninja#abc) mit der JWKS-kid (abc) verglichen. Vergleiche nur das Fragment nach #. Passt das Fragment trotzdem nicht, hat der Aussteller seit der Erstellung des Tokens vielleicht die Schlüssel rotiert; rufe das DID-Dokument ab und sieh dir die verificationMethod-Einträge an.

Signatur ungültig bei einem frisch heruntergeladenen Token. Prüfe, dass du header.payload als originalen base64url-Text verifiziert hast, nicht als neu kodiertes JSON. Wird das JSON neu serialisiert, ändern sich die Bytes und die Signatur bricht. Achte auch auf einen abschließenden Zeilenumbruch im heruntergeladenen Token.

Algorithm Confusion. Der klassische JWT-Angriff ist ein Token, das alg: none behauptet oder auf einen symmetrischen Algorithmus wechselt, damit ein Verifizierer es fälschlich akzeptiert. Unsere Beispiele vermeiden das, indem sie den erwarteten Algorithmus, EdDSA, fest vorgeben und alles andere ablehnen. Lass niemals das Token bestimmen, wie es verifiziert wird.

Base64-Padding-Fehler. JWS nutzt base64url ohne Padding. Python braucht das wieder angefügte Padding (siehe oben), und Go braucht RawURLEncoding, nicht URLEncoding.

Gültige Signatur, aber ist das Credential noch gut? Eine Signatur beweist Echtheit und Integrität, nicht den aktuellen Status. Ein Credential kann korrekt signiert und trotzdem widerrufen oder abgelaufen sein. Prüfe exp im Payload und den Widerrufsstatus, der als Nächstes beschrieben wird.

Vergiss den Widerruf nicht

Jedes Open-Badges-3.0-Credential von https://badges.ninja enthält einen credentialStatus-Eintrag nach der W3C Bitstring Status List. Er verweist auf ein Status-List-Credential, das du unter /certify-badge/status/<listId> abrufen kannst. Widerruft ein Aussteller eine Auszeichnung, kippt in dieser Liste ein Bit; die Liste wird etwa eine Minute gecacht, Widerrufe erreichen Verifizierer also schnell. Dekodiere die Liste und lies das Bit am statusListIndex des Credentials: 1 bedeutet widerrufen, 0 aktiv. Die Verifizierungsreferenz enthält ein kurzes Node-Beispiel für diese Bit-Prüfung.

Ein vollständiger Verifizierer tut drei Dinge: die Signatur prüfen, den Ablauf prüfen und das Widerrufs-Bit prüfen. Wie ein Widerruf aus Sicht des Ausstellers aussieht, erklärt die Dashboard-Aktion in der Awards-Anleitung.

Wann du das alles nicht brauchst

Die meisten Programmverantwortlichen werden diesen Code nie schreiben, und das ist in Ordnung. Für die tägliche Prüfung öffne einfach die öffentliche Seite der Auszeichnung unter https://badges.ninja/awards/<awardId> und lies sie. Die Seite braucht weder Anmeldung noch Schlüssel und zeigt Aussteller, Abzeichen und Status. Empfänger können das Verifiable Credential außerdem im Download-Menü ihrer öffentlichen Credential-Seite herunterladen und in jede Open-Badges-3.0-Wallet importieren.

Signaturprüfung wird wertvoll, wenn:

  • ein Arbeitgeber oder eine Universität die Prüfung erhaltener Credentials automatisieren will;
  • du ein Verwaltungssystem baust, das Kopien von Credentials speichert und beweisen muss, dass sie nicht verändert wurden;
  • ein Auditor einen Nachweis verlangt, dass deine Credentials unabhängig verifizierbar sind, nicht nur „vertraut unserer Website“.

Das API-Key-Setup, das du zum Ausstellen nutzt, brauchst du hier nicht, denn alle diese Endpunkte sind öffentlich. Wenn du Credentials aus Code heraus ausstellen willst, führt dich die API-Schnellstartanleitung durch das Anlegen eines Schlüssels und deine erste Auszeichnung.

API Keys — empty state

Kurzreferenz

ElementWert
Signiertes CredentialGET https://api.badges.ninja/certify-badge/award/<awardId>/vc
Unsigniertes JSON zum Lesendieselbe URL mit ?format=json
Aussteller-DIDdid:web:api.badges.ninja
Öffentliche Schlüssel/.well-known/jwks.json und /.well-known/did.json
AlgorithmusEd25519 (EdDSA)
SchlüsselabgleichFragment der Header-kid entspricht der JWKS-kid
WiderrufcredentialStatus verweist auf /certify-badge/status/<listId>

Zusammenfassung

Eine Open-Badge-Signatur zu verifizieren ist eine kurze, mechanische Routine: Token abrufen, Algorithmus festnageln, Schlüssel per Thumbprint finden und die Ed25519-Signatur über die ersten beiden Segmente prüfen. Ergänze Ablauf- und Widerrufsprüfung, und du hast einen Verifizierer, der niemandem vertraut außer dem veröffentlichten Schlüssel des Ausstellers. Genau diese Unabhängigkeit macht ein digitales Credential mehr wert als ein PDF.

Bereit, dein erstes verifizierbares Credential auszustellen? Kostenlos starten auf badges.ninja — visueller Designer, öffentliche Verifizierungsseite, PDF-Zertifikat, Open-Badge-v2.0-Ausgabe. Keine Kreditkarte erforderlich.

Nacho Coll

Über den Autor

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.

Zurück zum Blog

Verwandte Artikel