Верифікація підпису Open Badge у Node.js, Python і Go
Три робочі приклади коду (Node, Python, Go): отримання підписаного посвідчення Open Badge, пошук публічного ключа емітента та перевірка підпису 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.
Якщо ви видаєте посвідчення, більшість роботи з верифікації відбувається без вас: отримувач ділиться посиланням, роботодавець відкриває його, а решту робить сторінка верифікації. Але рано чи пізно хтось поставить гостріше запитання: «Як мені переконатися, що цей файл справді підписали ви і його не змінили згодом?» Відповідь дає цифровий підпис, а перевірка займає близько п’ятнадцяти рядків коду в будь-якій поширеній мові.
Цей туторіал покроково показує, як верифікувати підписане посвідчення Open Badges 3.0, видане через https://badges.ninja, у Node.js, Python і Go. Запускати щось із цього для видачі посвідчень не потрібно. Він для тих, хто хоче провести аудит системи, створити внутрішній інструмент верифікації або просто зрозуміти, що на практиці означає «верифіковане».
Що саме ви верифікуєте
В Open Badges є два рівні верифікації, і їх корисно розрізняти.
Хостингова верифікація — це модель Open Badges 2.0. Нагорода має публічну URL-адресу, і кожен, хто її відкриє, побачить емітента, значок, хешовану ідентичність отримувача та статус. Довіра випливає з того, що дані віддаються з домену самого емітента. Якщо сторінка відкривається на https://badges.ninja, посвідчення справжнє. Для цього не потрібні ні код, ні підпис.
Верифікація підпису — це модель Open Badges 3.0 на основі W3C Verifiable Credentials. Посвідчення пакується як підписаний токен, тож його можна перевірити офлайн, навіть через роки, якщо його скопіювали до гаманця чи вкладення листа. Довіра ґрунтується на математиці: токен містить підпис, який міг створити лише власник приватного ключа емітента.
На https://badges.ninja кожна нагорода доступна в обох формах. Ця стаття про другу. Якщо хочете дізнатися, чим відрізняються версії, прочитайте Open Badges v2 vs v3, а огляд хостингового JSON дивіться в розборі Open Badge JSON-LD.
З чого це складається
Підписане посвідчення — це VC-JWT: компактний JWS, тобто три рядки base64url, розділені крапками.
header.payload.signature
- Заголовок (header) каже, як створено підпис. У наших посвідченнях він містить
alg: EdDSA,typ: JWTтаkid(ідентифікатор ключа) на кшталтdid:web:api.badges.ninja#<thumbprint>. - Корисне навантаження (payload) містить твердження (claims), зокрема
iss(DID емітентаdid:web:api.badges.ninja),jti(ідентифікатор посвідчення),nbf(чинне з), необов’язковийexp(термін дії) та об’єктvcзі справжнімOpenBadgeCredential. - Підпис — це підпис Ed25519 над точними байтами
header.payload.
Публічний ключ для перевірки підпису емітент публікує у двох місцях, обидва без автентифікації:
https://api.badges.ninja/.well-known/jwks.jsonповертає набір JWK (JWK Set).https://api.badges.ninja/.well-known/did.jsonповертає DID-документ дляdid:web:api.badges.ninja.
kid у JWKS — це відбиток ключа за RFC 7638. kid у заголовку токена — це DID URL, і його фрагмент (частина після #) є тим самим відбитком. Саме за цим фрагментом ви обираєте потрібний ключ.
Рецепт верифікації
В усіх мовах п’ять однакових кроків:
- Отримайте підписане посвідчення з публічної кінцевої точки.
- Розділіть токен на три частини.
- Прочитайте заголовок, переконайтеся, що
algточноEdDSA, і візьміть відбиток ізkid. - Отримайте JWKS і знайдіть ключ із відповідним
kid. - Перевірте підпис Ed25519 над
header.payloadцим ключем.
Кінцева точка посвідчення публічна й приймає ідентифікатор нагороди (той самий GUID, що в URL верифікації на кшталт https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
За замовчуванням вона повертає підписаний VC-JWT як application/jwt. Додайте ?format=json, щоб отримати непідписаний JSON посвідчення для читання. Обидва варіанти описано в довіднику з верифікації.
Зверніть увагу: окремої кінцевої точки «перевір це за мене» немає, і це свідомо. Сервер, який каже «так, дійсне», просить вас довіряти серверу. Весь сенс підпису в тому, що ви перевіряєте його самі за опублікованим ключем.
Node.js
Вбудований модуль crypto у Node підтримує Ed25519 та імпорт JWK, тому залежності не потрібні.
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);
Аргумент null на місці алгоритму правильний: в Ed25519 тип ключа визначає алгоритм. Якщо віддаєте перевагу бібліотеці, jose робить те саме через compactVerify та importJWK і сама перевіряє заголовки.
Python
Пакет cryptography одразу дає Ed25519. Встановіть його командою 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 не має імпорту JWK для Ed25519, тому координату x (сирий 32-байтовий публічний ключ) ми декодуємо самі. Це все, що містить JWK типу OKP з кривою Ed25519.
Go
Стандартна бібліотека Go покриває все, включно з 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)
}
Запустіть командою go run main.go <awardId>. Обробку помилок скорочено для читабельності; у справжньому інструменті ви перевіряли б кожне декодування.
Типові помилки та як їх читати
Ключа немає в JWKS. Ви порівняли повний kid із заголовка токена (did:web:api.badges.ninja#abc) із kid у JWKS (abc). Порівнюйте лише фрагмент після #. Якщо фрагмент усе одно не збігається, емітент міг змінити ключі після створення токена; отримайте DID-документ і перегляньте записи verificationMethod.
Підпис недійсний на токені, який ви щойно завантажили. Перевірте, що ви верифікували header.payload як вихідний текст base64url, а не заново закодований JSON. Повторна серіалізація JSON змінює байти й ламає підпис. Також перевірте, чи немає кінцевого переведення рядка в завантаженому токені.
Плутанина алгоритмів. Класична атака на JWT — токен, що заявляє alg: none або переходить на симетричний алгоритм, аби верифікатор його прийняв. Наші приклади цього уникають: очікуваний алгоритм EdDSA прописано жорстко, а все інше відхиляється. Ніколи не дозволяйте токену самому обирати, як його верифікувати.
Помилки доповнення base64. JWS використовує base64url без доповнення. Python потребує повернути доповнення (показано вище), а Go — RawURLEncoding, а не URLEncoding.
Підпис дійсний, але чи посвідчення ще чинне? Підпис доводить автентичність і цілісність, а не поточний статус. Посвідчення може бути правильно підписане й водночас відкликане чи прострочене. Перевірте exp у payload та статус відкликання, описаний нижче.
Не забудьте про відкликання
Кожне посвідчення Open Badges 3.0 з https://badges.ninja містить запис credentialStatus за W3C Bitstring Status List. Він вказує на посвідчення зі списком статусів, яке можна отримати за адресою /certify-badge/status/<listId>. Коли емітент відкликає нагороду, у цьому списку перемикається біт; список кешується приблизно на хвилину, тож відкликання швидко доходять до верифікаторів. Декодуйте список і прочитайте біт за statusListIndex посвідчення: 1 означає відкликано, 0 — активне. Довідник з верифікації містить короткий приклад на Node для цієї перевірки біта.
Повний верифікатор робить три речі: перевіряє підпис, перевіряє термін дії та перевіряє біт відкликання. Щоб побачити, як відкликання виглядає з боку емітента, дію на панелі описано в посібнику з нагород.
Коли нічого з цього не потрібно
Більшість власників програм ніколи не писатимуть такий код, і це нормально. Для щоденних перевірок відкрийте публічну сторінку нагороди за адресою https://badges.ninja/awards/<awardId> і прочитайте її. Сторінка не потребує реєстрації чи ключа й показує емітента, значок і статус. Отримувачі також можуть завантажити Verifiable Credential з меню «Завантажити» на своїй публічній сторінці посвідчення та імпортувати його в будь-який гаманець Open Badges 3.0.
Перевірка підпису стає цінною, коли:
- роботодавець чи університет хоче автоматизувати перевірку отриманих посвідчень;
- ви створюєте систему обліку, що зберігає копії посвідчень і мусить довести, що їх не змінювали;
- аудитор просить доказ, що ваші посвідчення можна верифікувати незалежно, а не просто «довіряйте нашому сайту».
Налаштування API-ключа, яке ви використовуєте для видачі, тут не потрібне, бо всі ці кінцеві точки публічні. Якщо ви хочете видавати посвідчення з коду, швидкий старт API проведе вас через створення ключа та першу нагороду.

Коротка довідка
| Елемент | Значення |
|---|---|
| Підписане посвідчення | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| Непідписаний JSON для читання | та сама URL із ?format=json |
| DID емітента | did:web:api.badges.ninja |
| Публічні ключі | /.well-known/jwks.json і /.well-known/did.json |
| Алгоритм | Ed25519 (EdDSA) |
| Збіг ключа | фрагмент kid із заголовка дорівнює kid у JWKS |
| Відкликання | credentialStatus, що вказує на /certify-badge/status/<listId> |
Підсумок
Верифікація підпису Open Badge — це коротка механічна процедура: отримайте токен, зафіксуйте алгоритм, знайдіть ключ за відбитком і перевірте підпис Ed25519 над першими двома сегментами. Додайте перевірки терміну дії та відкликання — і матимете верифікатор, що не довіряє нікому, крім опублікованого ключа емітента. Саме ця незалежність робить цифрове посвідчення вартішим за PDF.
Готові видати своє перше верифіковане посвідчення? Почніть безкоштовно на badges.ninja — візуальний дизайнер, публічна сторінка верифікації, PDF-сертифікат, вивід Open Badge v2.0. Кредитна картка не потрібна.
Як створено цю статтю
Деякі публікації в цьому блозі створюються за допомогою ШІ-асистента, а потім перевіряються, звіряються з фактами й редагуються командою Badges Ninja перед публікацією. Кожен приклад коду та ціна звіряються з актуальним продуктом. Докладніше про наш редакційний процес і процес роботи з ШІ читайте на сторінці редакційного процесу .

Про автора
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.
Більше від Nacho Coll
- Open Badges для буткемпів: верифіковані сертифікати в масштабі когорти19 лист. 2026 р. · 10хв читання
- Налаштування вебхуків для подій значків: інтеграція з вашим бекендом у реальному часі16 лист. 2026 р. · 8хв читання
- Строк дії та поновлення Open Badge: керування життєвим циклом обмежених у часі посвідчень12 лист. 2026 р. · 10хв читання


