Open Badge'i allkirja kontrollimine Node.js-is, Pythonis ja Go-s
Kolm töötavat koodinäidet (Node, Python, Go), kuidas tuua allkirjastatud Open Badge'i mandaat, leida väljaandja avalik võti ja kontrollida JWS-allkirja.
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.
Kui sa mandaate välja annad, toimub suurem osa kontrollimisest sinuta: saaja jagab linki, tööandja klõpsab sellel ja kinnitusleht teeb ülejäänu. Varem või hiljem küsib aga keegi teravama küsimuse: „Kuidas ma tean, et selle faili allkirjastasid tõesti sina ja keegi pole seda hiljem muutnud?” Sellele vastab digiallkiri ning selle kontrollimine võtab igas levinud keeles umbes viisteist rida koodi.
See õpetus näitab samm-sammult, kuidas kontrollida https://badges.ninja kaudu välja antud allkirjastatud Open Badges 3.0 mandaati Node.js-is, Pythonis ja Go-s. Mandaatide väljaandmiseks ei pea sa midagi sellest jooksutama. See on mõeldud neile, kes tahavad süsteemi auditeerida, ehitada sisemise kontrollimisriista või lihtsalt mõista, mida „kontrollitav” praktikas tähendab.
Mida sa tegelikult kontrollid
Open Badgesis on kaks kontrollimise taset ning neid tasub eristada.
Majutatud kinnitamine on Open Badges 2.0 mudel. Autasul on avalik URL ning igaüks, kes selle avab, näeb väljaandjat, märki, saaja räsitud identiteeti ja staatust. Usaldus tuleneb sellest, et andmeid serveeritakse väljaandja enda domeenilt. Kui saad lehe https://badges.ninja peal avada, on mandaat ehtne. See ei vaja koodi ega allkirja.
Allkirja kontrollimine on Open Badges 3.0 mudel, mis põhineb W3C Verifiable Credentialsil. Mandaat on pakitud allkirjastatud tokeniks, mistõttu saab seda kontrollida võrguühenduseta, aastaid hiljem, isegi kui see on kopeeritud rahakotti või e-kirja manusesse. Usaldus tuleneb matemaatikast: token kannab allkirja, mille võis luua ainult väljaandja privaatvõtme omanik.
Platvormil https://badges.ninja on iga autasu saadaval mõlemal kujul. See artikkel räägib teisest. Kahe versiooni erinevuste tausta kohta loe Open Badges v2 vs v3 ja majutatud JSON-i ülevaadet vaata Open Badge JSON-LD läbivaatusest.
Liikuvad osad
Allkirjastatud mandaat on VC-JWT: kompaktne JWS, mis koosneb kolmest punktidega eraldatud base64url-stringist.
header.payload.signature
- Päis ütleb, kuidas allkirjastati. Meie mandaatidel sisaldab see
alg: EdDSA,typ: JWTjakid(võtme ID), mis näeb välja nagudid:web:api.badges.ninja#<thumbprint>. - Sisu (payload) kannab väiteid, sealhulgas
iss(väljaandja DIDdid:web:api.badges.ninja),jti(mandaadi ID),nbf(kehtib alates), valikulineexp(aegumine) ja objektvctegelikuOpenBadgeCredentialiga. - Allkiri on Ed25519 allkiri täpsete baitide
header.payloadüle.
Allkirja kontrollimiseks vajaliku avaliku võtme avaldab väljaandja kahes kohas, mõlemad ilma autentimiseta:
https://api.badges.ninja/.well-known/jwks.jsontagastab JWK komplekti.https://api.badges.ninja/.well-known/did.jsontagastabdid:web:api.badges.ninjaDID-dokumendi.
JWKS-i kid on võtme RFC 7638 sõrmejälg. Tokeni päises olev kid on DID URL ja selle fragment (osa pärast #) on sama sõrmejälg. Selle fragmendi järgi valid õige võtme.
Kontrollimise retsept
Kõigis keeltes järgitakse samu viit sammu:
- Too avalikust lõpp-punktist allkirjastatud mandaat.
- Jaga token kolmeks osaks.
- Loe päis, kontrolli, et
algon täpseltEdDSA, ning võtakid-ist sõrmejälg. - Too JWKS ja leia võti, mille
kidühtib. - Kontrolli selle võtmega Ed25519 allkirja
header.payloadüle.
Mandaadi lõpp-punkt on avalik ja võtab autasu ID (sama GUID, mida näed kinnitus-URL-is, näiteks https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Vaikimisi tagastab see allkirjastatud VC-JWT kujul application/jwt. Lisa ?format=json, et saada lugemiseks allkirjastamata mandaadi JSON. Mõlemat kirjeldab kinnitamise viide.
Pane tähele, et eraldi „kontrolli seda minu eest” lõpp-punkti pole, ja see on tahtlik. Server, mis ütleb „jah, kehtib”, palub sul serverit usaldada. Allkirja mõte ongi see, et saad ise avaldatud võtme vastu kontrollida.
Node.js
Node’i sisseehitatud crypto moodul toetab Ed25519 ja JWK importi, seega pole sõltuvusi vaja.
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);
Algoritmi argument null on õige: Ed25519 puhul määrab algoritmi võtmetüüp. Kui eelistad teeki, teeb jose sama töö compactVerify ja importJWK abil ning käsitleb päise kontrolle sinu eest.
Python
Pakett cryptography annab sulle Ed25519 otse. Paigalda see käsuga 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"])
Pythonil pole selles teegis Ed25519 jaoks JWK importi, seega dekodeerime x koordinaadi (toore 32-baidise avaliku võtme) ise. See ongi kõik, mida tüüpi OKP ja kõveraga Ed25519 JWK sisaldab.
Go
Go standardteek katab kõik, sealhulgas 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)
}
Käivita see käsuga go run main.go <awardId>. Veakäsitlus on loetavuse huvides kärbitud; päris tööriistas kontrolliksid iga dekodeerimist.
Levinud vead ja kuidas neid lugeda
Võtit JWKS-is ei leita. Sa võrdlesid tokeni päise täielikku kid-i (did:web:api.badges.ninja#abc) JWKS-i kid-iga (abc). Võrdle ainult fragmenti pärast #. Kui fragment ikka ei ühti, võis väljaandja olla võtmeid vahetanud pärast tokeni väljastamist; too DID-dokument ja vaata verificationMethod kirjeid.
Allkiri on kehtetu just allalaaditud tokenil. Kontrolli, et kinnitasid header.payload algse base64url-tekstina, mitte uuesti kodeeritud JSON-ina. JSON-i ümberserialiseerimine muudab baite ja rikub allkirja. Kontrolli ka, kas allalaaditud tokeni lõpus on reavahetus.
Algoritmi segiajamine. Klassikaline JWT rünnak on token, mis väidab alg: none või lülitub sümmeetrilisele algoritmile, et kontrollija eksitada. Meie näited väldivad seda, kodeerides oodatud algoritmi EdDSA püsivalt ja keeldudes kõigest muust. Ära kunagi lase tokenil ise valida, kuidas seda kontrollitakse.
Base64 täitesümbolite vead. JWS kasutab base64url-i ilma täiteta. Python vajab täite tagasilisamist (näidatud ülal) ja Go vajab RawURLEncoding-ut, mitte URLEncoding-ut.
Allkiri kehtib, aga kas mandaat on ikka hea? Allkiri tõendab autentsust ja terviklust, mitte praegust staatust. Mandaat võib olla korrektselt allkirjastatud ning siiski tühistatud või aegunud. Kontrolli sisus exp ja allpool kirjeldatud tühistusbitti.
Ära unusta tühistamist
Iga Open Badges 3.0 mandaat aadressilt https://badges.ninja sisaldab credentialStatus kirjet, mis järgib W3C Bitstring Status Listi. See viitab staatusloendi mandaadile, mille saad aadressilt /certify-badge/status/<listId>. Kui väljaandja autasu tühistab, pöördub loendis üks bitt; loend on vahemälus umbes minuti, nii et tühistused jõuavad kontrollijateni kiiresti. Dekodeeri loend ja loe bitt mandaadi statusListIndex kohalt: 1 tähendab tühistatud, 0 aktiivne. Kinnitamise viide sisaldab lühikest Node’i näidet selle bitikontrolli kohta.
Täielik kontrollija teeb kolme asja: kontrollib allkirja, aegumist ja tühistusbitti. Kui tahad näha, kuidas tühistamine väljaandja poolt paistab, on armatuurlaua tegevus kirjeldatud autasude juhendis.
Millal sa seda kõike ei vaja
Enamik programmide omanikke ei kirjuta seda koodi kunagi ja see on täiesti okei. Igapäevaseks kontrolliks ava autasu avalik leht aadressil https://badges.ninja/awards/<awardId> ja loe seda. Leht ei vaja registreerumist ega võtit ning näitab väljaandjat, märki ja staatust. Saajad saavad Verifiable Credentiali alla laadida ka oma avaliku mandaadilehe Download menüüst ja importida selle mis tahes Open Badges 3.0 rahakotti.
Allkirja kontrollimine muutub väärtuslikuks, kui:
- tööandja või ülikool soovib saadud mandaatide kontrolli automatiseerida;
- sa ehitad registrisüsteemi, mis salvestab mandaatide koopiaid ja peab tõestama, et neid pole muudetud;
- audiitor küsib tõendit, et sinu mandaadid on sõltumatult kontrollitavad, mitte lihtsalt „usalda meie veebilehte”.
Väljaandmiseks kasutatavat API võtme seadistust siin vaja ei lähe, sest kõik need lõpp-punktid on avalikud. Kui tahad mandaate koodist välja anda, juhatab API kiirstart sind võtme loomisest esimese autasuni.

Kiirviide
| Üksus | Väärtus |
|---|---|
| Allkirjastatud mandaat | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| Allkirjastamata JSON lugemiseks | sama URL koos ?format=json |
| Väljaandja DID | did:web:api.badges.ninja |
| Avalikud võtmed | /.well-known/jwks.json ja /.well-known/did.json |
| Algoritm | Ed25519 (EdDSA) |
| Võtme ühitamine | päise kid fragment võrdub JWKS-i kid-iga |
| Tühistamine | credentialStatus, mis viitab /certify-badge/status/<listId> |
Kokkuvõtteks
Open Badge’i allkirja kontrollimine on lühike mehaaniline rutiin: too token, fikseeri algoritm, leia võti sõrmejälje järgi ja kontrolli Ed25519 allkirja kahe esimese segmendi üle. Lisa aegumise ja tühistuse kontroll ning sul on kontrollija, mis ei usalda kedagi peale väljaandja avaldatud võtme. Just see sõltumatus teebki digitaalse mandaadi väärtuslikumaks kui PDF.
Valmis andma välja oma esimest kontrollitavat mandaati? Alusta tasuta badges.ninjas — visuaalne disainer, avalik kinnitusleht, PDF-sertifikaat, Open Badge v2.0 väljund. Krediitkaarti pole vaja.
Kuidas see artikkel valmis
Osa selle blogi postitustest on koostatud tehisintellekti abiga ning seejärel üle vaadatud, faktikontrollitud ja toimetatud Badges Ninja meeskonna poolt enne avaldamist. Iga koodinäide ja hind on kontrollitud reaalse toote vastu. Loe lähemalt meie toimetus- ja AI-protsessi kohta meie toimetusprotsessi lehel .

Autorist
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.
Rohkem autorilt Nacho Coll
- Programmeerimiskooli Open Badges: kontrollitavate tunnistuste väljaandmine terve kohordi mastaabis19. nov 2026 · 9min lugemist
- Veebikonksude seadistamine märgisündmuste jaoks: reaalajas integratsioon sinu taustasüsteemiga16. nov 2026 · 7min lugemist
- Open Badge'i aegumine ja uuendamine: ajaliselt piiratud kvalifikatsioonide elutsükli haldus12. nov 2026 · 9min lugemist


