Open Badge -allekirjoituksen varmennus Node.js:llä, Pythonilla ja Gollla
Kolme toimivaa koodiesimerkkiä (Node, Python, Go) allekirjoitetun Open Badge -todistuksen hakemiseen, myöntäjän julkisen avaimen selvittämiseen ja JWS-allekirjoituksen varmentamiseen.
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.
Jos myönnät todistuksia, suurin osa varmennustyöstä tapahtuu ilman sinua: vastaanottaja jakaa linkin, työnantaja klikkaa sitä, ja varmennussivu hoitaa lopun. Ennemmin tai myöhemmin joku kuitenkin kysyy terävämmän kysymyksen. “Mistä tiedän, että tämän tiedoston on todella allekirjoittanut sinä, eikä sitä ole muokattu jälkikäteen?” Tähän vastaa digitaalinen allekirjoitus, ja sen tarkistaminen vie noin viisitoista riviä koodia millä tahansa yleisellä kielellä.
Tämä opas näyttää, miten varmennat https://badges.ninja:n kautta myönnetyn allekirjoitetun Open Badges 3.0 -todistuksen vaihe vaiheelta Node.js:llä, Pythonilla ja Gollla. Mitään tästä ei tarvitse ajaa todistusten myöntämiseksi. Tämä on tarkoitettu niille, jotka haluavat auditoida järjestelmän, rakentaa sisäisen varmennustyökalun tai vain ymmärtää, mitä “varmennettavissa oleva” käytännössä tarkoittaa.
Mitä oikeastaan varmennat
Open Badgesissa on kaksi varmennuksen tasoa, ja ne kannattaa pitää erillään.
Isännöity varmennus on Open Badges 2.0 -malli. Myöntämisellä on julkinen URL, ja jokainen, joka avaa sen, näkee myöntäjän, merkin, vastaanottajan tiivistetyn identiteetin ja tilan. Luottamus syntyy siitä, että data tarjoillaan myöntäjän omalta verkkotunnukselta. Jos pääset sivulle osoitteessa https://badges.ninja, todistus on aito. Tämä ei vaadi koodia eikä allekirjoitusta.
Allekirjoituksen varmennus on Open Badges 3.0 -malli, joka perustuu W3C Verifiable Credentials -standardiin. Todistus on paketoitu allekirjoitetuksi tokeniksi, joten sen voi tarkistaa offline-tilassa vuosia myöhemmin, vaikka se olisi kopioitu lompakkoon tai sähköpostin liitteeksi. Luottamus syntyy matematiikasta: token sisältää allekirjoituksen, jonka on voinut tuottaa vain myöntäjän yksityisen avaimen haltija.
Palvelussa https://badges.ninja jokainen myöntö on saatavilla molemmissa muodoissa. Tämä artikkeli käsittelee jälkimmäistä. Jos haluat taustaa siitä, miten versiot eroavat, lue Open Badges v2 vs v3, ja isännöidyn JSONin esittelyyn tutustu Open Badge JSON-LD -läpikäyntiin.
Liikkuvat osat
Allekirjoitettu todistus on VC-JWT: kompakti JWS, eli kolme pisteillä erotettua base64url-merkkijonoa.
header.payload.signature
- Header kertoo, miten allekirjoitus on tehty. Meidän todistuksissamme se sisältää
alg: EdDSA,typ: JWTjakid:n (avaimen tunniste), joka näyttää tältä:did:web:api.badges.ninja#<thumbprint>. - Payload sisältää väitteet (claims), mukaan lukien
iss(myöntäjän DIDdid:web:api.badges.ninja),jti(todistuksen tunniste),nbf(voimassa alkaen), valinnaisenexp:n (vanheneminen) javc-objektin, jossa on varsinainenOpenBadgeCredential. - Allekirjoitus on Ed25519-allekirjoitus
header.payload-tavujen tarkan sisällön yli.
Allekirjoituksen tarkistava julkinen avain julkaistaan kahdessa paikassa, kumpikin ilman tunnistautumista:
https://api.badges.ninja/.well-known/jwks.jsonpalauttaa JWK Setin.https://api.badges.ninja/.well-known/did.jsonpalauttaadid:web:api.badges.ninja-tunnuksen DID-dokumentin.
JWKS:n kid on avaimen RFC 7638 -thumbprint. Token-headerin kid on DID URL, ja sen fragmentti (#-merkin jälkeinen osa) on sama thumbprint. Tuon fragmentin avulla valitset oikean avaimen.
Varmennusohje
Jokainen kieli noudattaa samoja viittä vaihetta:
- Hae allekirjoitettu todistus julkisesta rajapintapisteestä.
- Jaa token kolmeen osaan.
- Lue header, tarkista että
algon täsmälleenEdDSA, ja ota thumbprintkid:stä. - Hae JWKS ja etsi avain, jonka
kidtäsmää. - Varmenna Ed25519-allekirjoitus
header.payload-sisällön yli kyseisellä avaimella.
Todistuksen rajapintapiste on julkinen ja ottaa vastaan myöntötunnisteen (sama GUID, jonka näet varmennus-URL:ssä, kuten https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Oletuksena tämä palauttaa allekirjoitetun VC-JWT:n tyyppinä application/jwt. Lisää ?format=json, niin saat allekirjoittamattoman todistus-JSONin luettavaksi. Varmennusviite dokumentoi molemmat.
Huomaa, ettei erillistä “varmenna tämä puolestani” -rajapintapistettä ole, ja se on tarkoituksellista. Palvelin, joka kertoo “kyllä, kelvollinen”, pyytää sinua luottamaan palvelimeen. Allekirjoituksen koko pointti on, että voit tarkistaa sen itse julkaistua avainta vasten.
Node.js
Noden sisäänrakennettu crypto-moduuli tukee Ed25519:ää ja JWK-tuontia, joten riippuvuuksia ei tarvita.
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);
Algoritmin null-argumentti on oikein: Ed25519:n kanssa avaintyyppi määrää algoritmin. Jos haluat kirjaston, jose tekee saman compactVerify- ja importJWK-funktioilla ja hoitaa header-tarkistukset puolestasi.
Python
cryptography-paketti tarjoaa Ed25519:n suoraan. Asenna se komennolla 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"])
Pythonissa ei tässä kirjastossa ole JWK-tuontia Ed25519:lle, joten dekoodaamme x-koordinaatin (raaka 32-tavuinen julkinen avain) itse. Se on kaikki, mitä tyypin OKP ja käyrän Ed25519 JWK sisältää.
Go
Gon standardikirjasto kattaa kaiken, myös crypto/ed25519:n.
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)
}
Aja se komennolla go run main.go <awardId>. Virheenkäsittelyä on typistetty luettavuuden vuoksi; oikeassa työkalussa tarkistaisit jokaisen dekoodauksen.
Yleiset virheet ja miten ne luetaan
Avainta ei löydy JWKS:stä. Vertasit token-headerin koko kid:ia (did:web:api.badges.ninja#abc) JWKS:n kid:iin (abc). Vertaa vain #-merkin jälkeistä fragmenttia. Jos fragmentti ei silti täsmää, myöntäjä on voinut kierrättää avaimia tokenin luomisen jälkeen; hae DID-dokumentti ja katso sen verificationMethod-merkinnät.
Allekirjoitus on virheellinen juuri lataamallasi tokenilla. Tarkista, että varmensit header.payload-osan alkuperäisenä base64url-tekstinä, et uudelleenkoodattuna JSONina. JSONin sarjallistaminen uudelleen muuttaa tavut ja rikkoo allekirjoituksen. Tarkista myös, ettei ladatun tokenin perässä ole rivinvaihtoa.
Algoritmisekaannus. Klassinen JWT-hyökkäys on token, joka väittää alg: none tai vaihtaa symmetriseen algoritmiin, jotta varmentaja huijataan hyväksymään se. Esimerkkimme välttävät tämän kovakoodaamalla odotetun algoritmin, EdDSA, ja hylkäämällä kaiken muun. Älä koskaan anna tokenin päättää, miten se varmennetaan.
Base64-täytteen virheet. JWS käyttää base64urlia ilman täytettä. Pythonissa täyte pitää lisätä takaisin (näytetty yllä), ja Gossa tarvitaan RawURLEncoding, ei URLEncoding.
Allekirjoitus on kelvollinen, mutta onko todistus yhä voimassa? Allekirjoitus todistaa aitouden ja eheyden, ei nykyistä tilaa. Todistus voi olla oikein allekirjoitettu ja silti peruutettu tai vanhentunut. Tarkista exp payloadista ja tarkista peruutustila, josta kerrotaan seuraavaksi.
Älä unohda peruutusta
Jokaisella https://badges.ninja:n Open Badges 3.0 -todistuksella on credentialStatus-merkintä, joka noudattaa W3C Bitstring Status List -standardia. Se osoittaa tilalistatodistukseen, jonka voit hakea osoitteesta /certify-badge/status/<listId>. Kun myöntäjä peruuttaa myönnön, listassa käännetään yksi bitti; lista on välimuistissa noin minuutin, joten peruutukset tavoittavat varmentajat nopeasti. Dekoodaa lista ja lue bitti todistuksen statusListIndex-kohdasta: 1 tarkoittaa peruutettua, 0 aktiivista. Varmennusviite sisältää lyhyen Node-esimerkin tuosta bittitarkistuksesta.
Täydellinen varmentaja tekee kolme asiaa: varmentaa allekirjoituksen, tarkistaa vanhenemisen ja tarkistaa peruutusbitin. Jos haluat nähdä, miltä peruutus näyttää myöntäjän puolelta, hallintapaneelin toiminto on kuvattu myöntöoppaassa.
Milloin et tarvitse tätä lainkaan
Useimmat ohjelmien omistajat eivät koskaan kirjoita tätä koodia, ja se on täysin ok. Päivittäisiin tarkistuksiin avaa myönnön julkinen sivu osoitteessa https://badges.ninja/awards/<awardId> ja lue se. Sivu ei vaadi rekisteröitymistä eikä avainta, ja se näyttää myöntäjän, merkin ja tilan. Vastaanottajat voivat myös ladata Verifiable Credentialin julkisen todistussivunsa Lataa-valikosta ja tuoda sen mihin tahansa Open Badges 3.0 -lompakkoon.
Allekirjoituksen tarkistus tulee arvokkaaksi, kun:
- työnantaja tai yliopisto haluaa automatisoida saamiensa todistusten tarkistuksen;
- rakennat rekisterijärjestelmää, joka tallentaa todistusten kopioita ja jonka täytyy pystyä osoittamaan, ettei niitä ole muutettu;
- tarkastaja pyytää todisteita siitä, että todistuksesi ovat riippumattomasti varmennettavissa, eikä vain “luota verkkosivuumme”.
Myöntämiseen käytettyä API-avaimen asennusta ei tarvita tässä, koska kaikki nämä rajapintapisteet ovat julkisia. Jos haluat myöntää todistuksia koodista, API-pikaopas käy läpi avaimen luomisen ja ensimmäisen myönnön.

Pikaviite
| Kohde | Arvo |
|---|---|
| Allekirjoitettu todistus | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| Allekirjoittamaton JSON luettavaksi | sama URL ja ?format=json |
| Myöntäjän DID | did:web:api.badges.ninja |
| Julkiset avaimet | /.well-known/jwks.json ja /.well-known/did.json |
| Algoritmi | Ed25519 (EdDSA) |
| Avaimen täsmäys | headerin kid:n fragmentti vastaa JWKS:n kid:iä |
| Peruutus | credentialStatus osoittaa kohteeseen /certify-badge/status/<listId> |
Yhteenveto
Open Badge -allekirjoituksen varmennus on lyhyt, mekaaninen rutiini: hae token, lukitse algoritmi, etsi avain thumbprintin avulla ja tarkista Ed25519-allekirjoitus kahden ensimmäisen segmentin yli. Lisää vanhenemisen ja peruutuksen tarkistus, ja sinulla on varmentaja, joka ei luota kehenkään muuhun kuin myöntäjän julkaisemaan avaimeen. Juuri tämä riippumattomuus tekee digitaalisesta todistuksesta arvokkaamman kuin PDF.
Valmis myöntämään ensimmäisen varmennettavan todistuksesi? Aloita ilmaiseksi badges.ninjassa — visuaalinen suunnittelija, julkinen varmennussivu, PDF-sertifikaatti, Open Badge v2.0 -tuloste. Luottokorttia ei tarvita.
Miten tämä artikkeli tehtiin
Osa tämän blogin artikkeleista laaditaan tekoälyavustajan avulla, minkä jälkeen Badges Ninja -tiimi tarkistaa, faktantarkistaa ja muokkaa ne ennen julkaisua. Jokainen koodiesimerkki ja hinta tarkistetaan live-tuotteesta. Lue lisää toimituksellisesta ja tekoälyprosessistamme toimitusprosessin sivulla .

Kirjoittajasta
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.
Lisää käyttäjältä Nacho Coll
- Open Badges koodauskoulutuksiin: varmennettavat todistukset kohortin mittakaavassa19.11.2026 · 8min lukuaika
- Webhookien käyttöönotto merkkitapahtumille: reaaliaikainen integraatio taustajärjestelmääsi16.11.2026 · 7min lukuaika
- Open Badgen voimassaolon päättyminen ja uusiminen: määräaikaisten todistusten elinkaaren hallinta12.11.2026 · 8min lukuaika


