Weryfikacja podpisu Open Badge w Node.js, Pythonie i Go
Trzy działające przykłady kodu (Node, Python, Go): pobranie podpisanego poświadczenia Open Badge, odnalezienie klucza publicznego wystawcy i weryfikacja podpisu 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.
Jeśli wystawiasz poświadczenia, większość pracy związanej z weryfikacją dzieje się bez Twojego udziału: odbiorca udostępnia link, pracodawca w niego klika, a resztą zajmuje się strona weryfikacji. Prędzej czy później ktoś zada jednak ostrzejsze pytanie: „Skąd mam wiedzieć, że ten plik naprawdę został podpisany przez Ciebie i nikt go potem nie zmienił?“. Odpowiedzią jest podpis cyfrowy, a jego sprawdzenie zajmuje około piętnastu linijek kodu w każdym popularnym języku.
Ten tutorial pokazuje krok po kroku, jak zweryfikować podpisane poświadczenie Open Badges 3.0 wystawione przez https://badges.ninja w Node.js, Pythonie i Go. Nie musisz niczego z tego uruchamiać, żeby wystawiać poświadczenia. To dla osób, które chcą zaudytować system, zbudować wewnętrzne narzędzie weryfikacyjne albo po prostu zrozumieć, co w praktyce znaczy „weryfikowalne”.
Co dokładnie weryfikujesz
W Open Badges istnieją dwie warstwy weryfikacji i warto je rozróżniać.
Weryfikacja hostowana to model z Open Badges 2.0. Przyznana odznaka ma publiczny adres URL, a każdy, kto go otworzy, zobaczy wystawcę, odznakę, zahaszowaną tożsamość odbiorcy i status. Zaufanie wynika stąd, że dane są serwowane z domeny samego wystawcy. Jeśli strona otwiera się na https://badges.ninja, poświadczenie jest prawdziwe. Nie wymaga to kodu ani podpisu.
Weryfikacja podpisu to model z Open Badges 3.0, oparty na W3C Verifiable Credentials. Poświadczenie jest zapakowane jako podpisany token, więc można je sprawdzić offline, nawet po latach, także gdy trafiło do portfela albo załącznika e-mail. Zaufanie bierze się z matematyki: token niesie podpis, który mógł wytworzyć tylko posiadacz klucza prywatnego wystawcy.
W https://badges.ninja każda przyznana odznaka jest dostępna w obu formach. Ten artykuł dotyczy drugiej z nich. Jeśli chcesz poznać tło różnic między wersjami, przeczytaj Open Badges v2 vs v3, a po przewodnik po hostowanym JSON-ie zajrzyj do omówienia Open Badge JSON-LD.
Ruchome części
Podpisane poświadczenie to VC-JWT: skompaktowany JWS, czyli trzy ciągi base64url oddzielone kropkami.
header.payload.signature
- Nagłówek mówi, jak złożono podpis. W naszych poświadczeniach zawiera
alg: EdDSA,typ: JWTorazkid(identyfikator klucza) wyglądający jakdid:web:api.badges.ninja#<thumbprint>. - Payload zawiera twierdzenia (claims), w tym
iss(DID wystawcydid:web:api.badges.ninja),jti(identyfikator poświadczenia),nbf(ważne od), opcjonalneexp(wygaśnięcie) oraz obiektvcz właściwymOpenBadgeCredential. - Podpis to podpis Ed25519 złożony na dokładnych bajtach
header.payload.
Klucz publiczny, którym sprawdza się podpis, wystawca publikuje w dwóch miejscach, oba bez uwierzytelniania:
https://api.badges.ninja/.well-known/jwks.jsonzwraca zbiór JWK (JWK Set).https://api.badges.ninja/.well-known/did.jsonzwraca dokument DID dladid:web:api.badges.ninja.
kid w JWKS to odcisk klucza zgodny z RFC 7638. kid w nagłówku tokenu to adres DID URL, a jego fragment (część po #) jest tym samym odciskiem. Właśnie po tym fragmencie wybierasz właściwy klucz.
Przepis na weryfikację
W każdym języku kroki są te same, pięć:
- Pobierz podpisane poświadczenie z publicznego endpointu.
- Podziel token na trzy części.
- Odczytaj nagłówek, sprawdź, że
algto dokładnieEdDSA, i weź odcisk zkid. - Pobierz JWKS i znajdź klucz o pasującym
kid. - Zweryfikuj podpis Ed25519 dla
header.payloadtym kluczem.
Endpoint poświadczenia jest publiczny i przyjmuje identyfikator przyznanej odznaki (ten sam GUID, który widzisz w adresie weryfikacji, takim jak https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Domyślnie zwraca on podpisany VC-JWT jako application/jwt. Dodaj ?format=json, aby dostać niepodpisany JSON poświadczenia do odczytu. Oba warianty opisuje dokumentacja weryfikacji.
Zwróć uwagę, że nie ma osobnego endpointu „zweryfikuj to za mnie” i jest to celowe. Serwer, który mówi „tak, ważne”, prosi Cię o zaufanie serwerowi. Cały sens podpisu polega na tym, że sam sprawdzasz go względem opublikowanego klucza.
Node.js
Wbudowany moduł crypto w Node obsługuje Ed25519 i import JWK, więc nie potrzebujesz żadnych zależności.
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);
Argument null w miejscu algorytmu jest poprawny: w Ed25519 typ klucza z góry określa algorytm. Jeśli wolisz bibliotekę, jose robi to samo za pomocą compactVerify i importJWK i sama sprawdza nagłówki.
Python
Pakiet cryptography daje Ed25519 od razu. Zainstaluj go poleceniem 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 w tej bibliotece nie ma importu JWK dla Ed25519, więc współrzędną x (surowy, 32-bajtowy klucz publiczny) dekodujemy sami. Tyle właśnie zawiera JWK typu OKP z krzywą Ed25519.
Go
Biblioteka standardowa Go pokrywa wszystko, w tym 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)
}
Uruchom to poleceniem go run main.go <awardId>. Obsługę błędów skrócono dla czytelności; w prawdziwym narzędziu sprawdzałbyś każde dekodowanie.
Typowe błędy i jak je czytać
Klucza nie ma w JWKS. Porównano pełny kid z nagłówka tokenu (did:web:api.badges.ninja#abc) z kid z JWKS (abc). Porównuj tylko fragment po #. Jeśli fragment nadal się nie zgadza, wystawca mógł zrotować klucze od czasu wydania tokenu; pobierz dokument DID i obejrzyj wpisy verificationMethod.
Nieprawidłowy podpis na świeżo pobranym tokenie. Sprawdź, czy weryfikowałeś header.payload jako oryginalny tekst base64url, a nie ponownie zakodowany JSON. Ponowna serializacja JSON-a zmienia bajty i psuje podpis. Sprawdź też, czy pobrany token nie ma końcowego znaku nowej linii.
Pomylenie algorytmów. Klasyczny atak na JWT to token, który deklaruje alg: none albo przełącza się na algorytm symetryczny, tak by weryfikator dał się oszukać i go zaakceptował. Nasze przykłady go unikają, bo na sztywno wpisują oczekiwany algorytm, EdDSA, i odrzucają wszystko inne. Nigdy nie pozwalaj, by to token decydował, jak będzie weryfikowany.
Błędy paddingu base64. JWS używa base64url bez paddingu. Python wymaga jego dodania (pokazano wyżej), a Go potrzebuje RawURLEncoding, nie URLEncoding.
Podpis prawidłowy, ale czy poświadczenie nadal jest dobre? Podpis dowodzi autentyczności i integralności, a nie aktualnego statusu. Poświadczenie może być poprawnie podpisane i mimo to unieważnione albo wygasłe. Sprawdź exp w payloadzie oraz status unieważnienia opisany poniżej.
Nie zapomnij o unieważnieniu
Każde poświadczenie Open Badges 3.0 z https://badges.ninja zawiera wpis credentialStatus zgodny z W3C Bitstring Status List. Wskazuje on poświadczenie z listą statusów, które pobierzesz pod adresem /certify-badge/status/<listId>. Gdy wystawca unieważnia odznakę, na tej liście przestawia się bit; lista jest cache’owana przez około minutę, więc unieważnienia szybko docierają do weryfikatorów. Zdekoduj listę i odczytaj bit pod statusListIndex poświadczenia: 1 oznacza unieważnione, 0 aktywne. Dokumentacja weryfikacji zawiera krótki przykład w Node dla tego sprawdzenia bitu.
Kompletny weryfikator robi trzy rzeczy: weryfikuje podpis, sprawdza wygaśnięcie i sprawdza bit unieważnienia. Jeśli chcesz zobaczyć, jak unieważnienie wygląda od strony wystawcy, akcję w panelu opisuje przewodnik po przyznawaniu odznak.
Kiedy nic z tego nie jest potrzebne
Większość właścicieli programów nigdy nie napisze tego kodu i to w porządku. Do codziennych sprawdzeń otwórz publiczną stronę odznaki pod adresem https://badges.ninja/awards/<awardId> i ją przeczytaj. Strona nie wymaga rejestracji ani klucza, a pokazuje wystawcę, odznakę i status. Odbiorcy mogą też pobrać Verifiable Credential z menu Pobierz na swojej publicznej stronie poświadczenia i zaimportować je do dowolnego portfela Open Badges 3.0.
Sprawdzanie podpisu staje się cenne, gdy:
- pracodawca lub uczelnia chce zautomatyzować sprawdzanie otrzymywanych poświadczeń;
- budujesz system ewidencji, który przechowuje kopie poświadczeń i musi udowodnić, że nie zostały zmienione;
- audytor prosi o dowód, że Twoje poświadczenia są niezależnie weryfikowalne, a nie tylko „zaufaj naszej stronie”.
Konfiguracja klucza API, której używasz do wystawiania, nie jest tu potrzebna, bo wszystkie te endpointy są publiczne. Jeśli chcesz wystawiać poświadczenia z kodu, szybki start API przeprowadzi Cię przez utworzenie klucza i pierwszą przyznaną odznakę.

Krótkie podsumowanie
| Element | Wartość |
|---|---|
| Podpisane poświadczenie | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| Niepodpisany JSON do odczytu | ten sam URL z ?format=json |
| DID wystawcy | did:web:api.badges.ninja |
| Klucze publiczne | /.well-known/jwks.json i /.well-known/did.json |
| Algorytm | Ed25519 (EdDSA) |
| Dopasowanie klucza | fragment kid z nagłówka równa się kid z JWKS |
| Unieważnienie | credentialStatus wskazujące na /certify-badge/status/<listId> |
Na koniec
Weryfikacja podpisu Open Badge to krótka, mechaniczna procedura: pobierz token, przypnij algorytm, znajdź klucz po odcisku i sprawdź podpis Ed25519 na dwóch pierwszych segmentach. Dodaj kontrolę wygaśnięcia i unieważnienia, a otrzymasz weryfikator, który nie ufa nikomu poza opublikowanym kluczem wystawcy. Właśnie ta niezależność sprawia, że cyfrowe poświadczenie jest warte więcej niż PDF.
Gotowy, by wystawić pierwsze weryfikowalne poświadczenie? Zacznij za darmo na badges.ninja — projektant wizualny, publiczna strona weryfikacji, certyfikat PDF, wyjście Open Badge v2.0. Karta kredytowa niepotrzebna.
Jak powstał ten artykuł
Niektóre wpisy na tym blogu powstają z pomocą asystenta AI, a następnie są sprawdzane, weryfikowane merytorycznie i redagowane przez zespół Badges Ninja przed publikacją. Każdy przykład kodu i cena są weryfikowane względem działającego produktu. Więcej o naszym procesie redakcyjnym i wykorzystaniu AI przeczytasz na naszej stronie procesu redakcyjnego .

O autorze
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.
Więcej od Nacho Coll
- Open Badges dla bootcampów programistycznych: weryfikowalne poświadczenia na skalę kohorty19 lis 2026 · 10min czytania
- Konfiguracja webhooków dla zdarzeń odznak: integracja z Twoim backendem w czasie rzeczywistym16 lis 2026 · 8min czytania
- Wygasanie i odnawianie Open Badge: zarządzanie cyklem życia poświadczeń ograniczonych czasowo12 lis 2026 · 10min czytania


