Open Badge parašo patikrinimas Node.js, Python ir Go kalbomis
Trys veikiantys kodo pavyzdžiai (Node, Python, Go): kaip gauti pasirašytą Open Badge kredencialą, rasti išdavėjo viešąjį raktą ir patikrinti JWS parašą.
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.
Jei išduodate kredencialus, didžiąją patikrinimo darbo dalį atlieka kiti: gavėjas pasidalija nuoroda, darbdavys ją atidaro, o patikrinimo puslapis padaro likusį darbą. Bet anksčiau ar vėliau kas nors užduoda aštresnį klausimą: „Iš kur žinoti, kad šį failą tikrai pasirašėte jūs ir kad jo niekas nepakeitė?“ Į tai atsako skaitmeninis parašas, o jį patikrinti galima maždaug penkiolika kodo eilučių bet kuria populiaria kalba.
Šioje pamokoje žingsnis po žingsnio parodome, kaip patikrinti per https://badges.ninja išduotą pasirašytą Open Badges 3.0 kredencialą Node.js, Python ir Go kalbomis. Kredencialams išduoti nieko iš to paleisti nereikia. Tai skirta tiems, kurie nori auditą atlikti sistemai, sukurti vidinį patikrinimo įrankį arba tiesiog suprasti, ką praktiškai reiškia „patikrinamas“.
Ką iš tikrųjų tikrinate
Open Badges yra du patikrinimo lygiai, ir verta juos skirti.
Talpinamas patikrinimas (angl. hosted verification) yra Open Badges 2.0 modelis. Apdovanojimas turi viešą URL, o jį atidaręs kiekvienas mato išdavėją, skaitmeninį ženklelį, užhaširuotą gavėjo tapatybę ir būseną. Pasitikėjimas kyla iš to, kad duomenys pateikiami iš paties išdavėjo domeno. Jei puslapį pasiekiate adresu https://badges.ninja, kredencialas tikras. Tam nereikia nei kodo, nei parašo.
Parašo patikrinimas yra Open Badges 3.0 modelis, paremtas W3C Verifiable Credentials. Kredencialas supakuotas kaip pasirašytas žetonas, todėl jį galima patikrinti neprisijungus, net po daugelio metų, net jei jis buvo nukopijuotas į piniginę ar el. laiško priedą. Pasitikėjimas kyla iš matematikos: žetonas turi parašą, kurį galėjo sukurti tik išdavėjo privačiojo rakto turėtojas.
Per https://badges.ninja kiekvienas apdovanojimas pasiekiamas abiem formomis. Šis straipsnis apie antrąją. Jei norite sužinoti, kuo skiriasi dvi versijos, skaitykite Open Badges v2 vs v3, o talpinamo JSON apžvalgą rasite Open Badge JSON-LD analizėje.
Judančios dalys
Pasirašytas kredencialas yra VC-JWT: kompaktiškas JWS, t. y. trys base64url eilutės, atskirtos taškais.
header.payload.signature
- Antraštė (angl. header) nurodo, kaip pasirašyta. Mūsų kredencialuose joje yra
alg: EdDSA,typ: JWTirkid(rakto identifikatorius), atrodantis taip:did:web:api.badges.ninja#<thumbprint>. - Turinys (angl. payload) talpina teiginius, įskaitant
iss(išdavėjo DIDdid:web:api.badges.ninja),jti(kredencialo id),nbf(galioja nuo), neprivalomąexp(galiojimo pabaiga) irvcobjektą su pačiuOpenBadgeCredential. - Parašas yra Ed25519 parašas, apskaičiuotas iš tikslių
header.payloadbaitų.
Viešąjį raktą parašui patikrinti išdavėjas skelbia dviem vietomis, abi be autentifikavimo:
https://api.badges.ninja/.well-known/jwks.jsongrąžina JWK rinkinį.https://api.badges.ninja/.well-known/did.jsongrąžinadid:web:api.badges.ninjaDID dokumentą.
JWKS kid yra rakto RFC 7638 atspaudas (angl. thumbprint). Žetono antraštės kid yra DID URL, o jo fragmentas (dalis po #) yra tas pats atspaudas. Būtent pagal šį fragmentą pasirenkamas tinkamas raktas.
Patikrinimo receptas
Kiekviena kalba seka tuos pačius penkis žingsnius:
- Gaukite pasirašytą kredencialą iš viešo galinio taško.
- Padalykite žetoną į tris dalis.
- Perskaitykite antraštę, patikrinkite, ar
algtiksliai lygusEdDSA, ir iškidpaimkite atspaudą. - Gaukite JWKS ir raskite raktą su atitinkančiu
kid. - Tuo raktu patikrinkite Ed25519 parašą, apskaičiuotą iš
header.payload.
Kredencialo galinis taškas yra viešas ir priima apdovanojimo id (tą patį GUID, kurį matote patikrinimo URL, pavyzdžiui, https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Pagal numatytuosius nustatymus grąžinamas pasirašytas VC-JWT kaip application/jwt. Pridėkite ?format=json, jei norite gauti nepasirašytą kredencialo JSON skaitymui. Abu variantai aprašyti patikrinimo nuorodoje.
Atkreipkite dėmesį: atskiro „patikrink tai už mane“ galinio taško nėra, ir tai sąmoninga. Serveris, kuris sako „taip, galioja“, prašo pasitikėti serveriu. Visa parašo esmė ta, kad jį galite patikrinti patys pagal viešai paskelbtą raktą.
Node.js
Node integruotas crypto modulis palaiko Ed25519 ir JWK importą, todėl priklausomybių nereikia.
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);
Argumentas null vietoje algoritmo yra teisingas: naudojant Ed25519 algoritmą nulemia rakto tipas. Jei mieliau naudojate biblioteką, jose atlieka tą patį darbą su compactVerify ir importJWK ir pati patikrina antraštes.
Python
Paketas cryptography suteikia Ed25519 tiesiogiai. Įdiekite jį komanda 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"])
Šioje bibliotekoje Python neturi Ed25519 JWK importo, todėl x koordinatę (neapdorotą 32 baitų viešąjį raktą) iškoduojame patys. Būtent tiek ir yra OKP tipo JWK su kreive Ed25519.
Go
Go standartinė biblioteka apima viską, įskaitant 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)
}
Paleiskite komanda go run main.go <awardId>. Klaidų apdorojimas sutrumpintas dėl aiškumo; tikrame įrankyje reikėtų tikrinti kiekvieną dekodavimą.
Dažnos klaidos ir kaip jas skaityti
Rakto nėra JWKS. Palyginote visą žetono antraštės kid (did:web:api.badges.ninja#abc) su JWKS kid (abc). Lyginkite tik fragmentą po #. Jei fragmentas vis tiek nesutampa, galbūt išdavėjas pakeitė raktus nuo žetono išrašymo; gaukite DID dokumentą ir peržiūrėkite jo verificationMethod įrašus.
Parašas neteisingas ką tik atsisiųstam žetonui. Patikrinkite, ar tikrinote header.payload kaip pradinį base64url tekstą, o ne iš naujo užkoduotą JSON. Perserializavus JSON pasikeičia baitai ir parašas nebegalioja. Taip pat patikrinkite, ar atsisiųstas žetonas nesibaigia naujos eilutės simboliu.
Algoritmo painiojimas. Klasikinė JWT ataka: žetonas teigia alg: none arba persijungia į simetrinį algoritmą, kad patikrintojas būtų apgautas jį priimti. Mūsų pavyzdžiai to išvengia užkoduodami laukiamą algoritmą EdDSA ir atmesdami visa kita. Niekada neleiskite žetonui pačiam pasirinkti, kaip jis bus tikrinamas.
Base64 užpildymo klaidos. JWS naudoja base64url be užpildymo. Python reikia užpildymą pridėti atgal (parodyta aukščiau), o Go reikia RawURLEncoding, ne URLEncoding.
Parašas galioja, bet ar kredencialas vis dar geras? Parašas įrodo autentiškumą ir vientisumą, bet ne dabartinę būseną. Kredencialas gali būti teisingai pasirašytas ir vis tiek atšauktas ar pasibaigęs. Patikrinkite turinio exp ir toliau aprašytą atšaukimo būseną.
Nepamirškite atšaukimo
Kiekvienas Open Badges 3.0 kredencialas iš https://badges.ninja turi credentialStatus įrašą pagal W3C Bitstring Status List. Jis nurodo būsenos sąrašo kredencialą, kurį galite gauti adresu /certify-badge/status/<listId>. Kai išdavėjas atšaukia apdovanojimą, sąraše pasikeičia bitas; sąrašas talpinamas podėlyje maždaug minutei, todėl atšaukimai patikrintojus pasiekia greitai. Iškoduokite sąrašą ir perskaitykite bitą kredencialo statusListIndex pozicijoje: 1 reiškia atšaukta, 0 reiškia aktyvu. Patikrinimo nuorodoje rasite trumpą Node pavyzdį, kaip tikrinamas šis bitas.
Pilnas patikrintojas atlieka tris dalykus: patikrina parašą, galiojimo pabaigą ir atšaukimo bitą. Jei norite pamatyti, kaip atšaukimas atrodo išdavėjo pusėje, valdymo skydelio veiksmas aprašytas apdovanojimų vadove.
Kada viso to nereikia
Dauguma programų vadovų niekada nerašys šio kodo, ir tai gerai. Kasdieniam patikrinimui atidarykite viešą apdovanojimo puslapį https://badges.ninja/awards/<awardId> ir perskaitykite jį. Puslapiui nereikia nei registracijos, nei rakto, o jame matyti išdavėjas, skaitmeninis ženklelis ir būsena. Gavėjai taip pat gali atsisiųsti Verifiable Credential iš Download meniu savo viešame kredencialo puslapyje ir importuoti jį į bet kurią Open Badges 3.0 piniginę.
Parašo tikrinimas tampa vertingas, kai:
- darbdavys ar universitetas nori automatizuoti gaunamų kredencialų patikrą;
- kuriate įrašų sistemą, kuri saugo kredencialų kopijas ir turi įrodyti, kad jos nebuvo pakeistos;
- auditorius prašo įrodymų, kad jūsų kredencialai nepriklausomai patikrinami, o ne tik „pasitikėkite mūsų svetaine“.
Čia nereikia to paties API rakto, kuris naudojamas išduodant, nes visi šie galiniai taškai yra vieši. Jei kredencialus norite išduoti iš kodo, API greitoji pradžia paaiškina, kaip sukurti raktą ir pirmąjį apdovanojimą.

Trumpa nuoroda
| Elementas | Reikšmė |
|---|---|
| Pasirašytas kredencialas | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| Nepasirašytas JSON skaitymui | tas pats URL su ?format=json |
| Išdavėjo DID | did:web:api.badges.ninja |
| Viešieji raktai | /.well-known/jwks.json ir /.well-known/did.json |
| Algoritmas | Ed25519 (EdDSA) |
| Rakto atitikimas | antraštės kid fragmentas lygus JWKS kid |
| Atšaukimas | credentialStatus, nurodantis į /certify-badge/status/<listId> |
Apibendrinimas
Open Badge parašo patikrinimas yra trumpa, mechaniška rutina: gaukite žetoną, užfiksuokite algoritmą, raskite raktą pagal atspaudą ir patikrinkite Ed25519 parašą pirmiesiems dviem segmentams. Pridėkite galiojimo ir atšaukimo patikras, ir turėsite patikrintoją, kuris nepasitiki niekuo, išskyrus išdavėjo paskelbtą raktą. Būtent ši nepriklausomybė daro skaitmeninį kredencialą vertingesnį už PDF.
Pasiruošę išduoti pirmąjį patikrinamą kredencialą? Pradėkite nemokamai badges.ninja — vizualinis dizaineris, viešas patikrinimo puslapis, PDF sertifikatas, Open Badge v2.0 išvestis. Kreditinės kortelės nereikia.
Kaip parengtas šis straipsnis
Kai kurie šio tinklaraščio įrašai parengiami padedant DI asistentui, o prieš publikuojant juos peržiūri, patikrina faktus ir redaguoja Badges Ninja komanda. Kiekvienas kodo pavyzdys ir kaina patikrinami pagal veikiantį produktą. Daugiau apie mūsų redakcinį ir DI procesą skaitykite mūsų redakcinio proceso puslapyje .

Apie autorių
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.
Daugiau iš Nacho Coll
- Programavimo kursų Open Badges: patikrinami skaitmeniniai įgijimai visos grupės mastu2026-11-19 · 9min skaitymo
- Webhook'ų nustatymas skaitmeninių ženklelių įvykiams: realaus laiko integracija su jūsų serveriu2026-11-16 · 8min skaitymo
- Open Badge galiojimo pabaiga ir atnaujinimas: terminuotų kvalifikacijų gyvavimo ciklo valdymas2026-11-12 · 9min skaitymo


