Проверка подписи 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.
Если вы выдаёте credentials, большая часть верификации происходит без вашего участия: получатель делится ссылкой, работодатель переходит по ней, а остальное делает страница верификации. Но рано или поздно кто-нибудь задаст вопрос поострее: «Откуда мне знать, что этот файл действительно подписан вами и не был изменён после этого?» Ответ на него даёт цифровая подпись, а проверить её можно примерно пятнадцатью строками кода на любом распространённом языке.
В этом руководстве по шагам показано, как проверить подписанный credential Open Badges 3.0, выданный через https://badges.ninja, в Node.js, Python и Go. Запускать что-либо из этого для выдачи credentials не нужно. Материал для тех, кто хочет провести аудит системы, собрать внутренний инструмент проверки или просто понять, что на практике означает «верифицируемый».
Что именно вы проверяете
В Open Badges есть два уровня верификации, и полезно их различать.
Размещённая верификация — модель Open Badges 2.0. У награды есть публичный URL, и любой, кто его откроет, увидит издателя, цифровой значок, хешированную идентичность получателя и статус. Доверие возникает потому, что данные отдаются с собственного домена издателя. Если страница на https://badges.ninja открывается, credential настоящий. Ни код, ни подпись для этого не нужны.
Проверка подписи — модель Open Badges 3.0, построенная на W3C Verifiable Credentials. Credential упаковывается как подписанный токен, поэтому его можно проверить офлайн, спустя годы, даже если он был скопирован в кошелёк или вложен в письмо. Доверие здесь обеспечивает математика: токен несёт подпись, которую мог создать только владелец закрытого ключа издателя.
На https://badges.ninja каждая награда доступна в обеих формах. Эта статья — о второй. Если хотите узнать, чем отличаются две версии, прочитайте Open Badges v2 vs v3, а для обзора размещённого JSON см. разбор Open Badge JSON-LD.
Составные части
Подписанный credential — это VC-JWT: компактный JWS, то есть три строки base64url, разделённые точками.
header.payload.signature
- Заголовок (header) сообщает, как выполнена подпись. В наших credentials он содержит
alg: EdDSA,typ: JWTиkid(идентификатор ключа) видаdid:web:api.badges.ninja#<thumbprint>. - Полезная нагрузка (payload) содержит claims, среди них
iss(DID издателяdid:web:api.badges.ninja),jti(идентификатор credential),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, а его фрагмент (часть после #) — тот же самый отпечаток. По этому фрагменту вы и выбираете нужный ключ.
Рецепт верификации
Для любого языка действуют те же пять шагов:
- Получить подписанный credential с публичного эндпоинта.
- Разбить токен на три части.
- Прочитать заголовок, убедиться, что
algв точности равенEdDSA, и взять отпечаток изkid. - Получить JWKS и найти ключ с совпадающим
kid. - Проверить подпись Ed25519 над
header.payloadэтим ключом.
Эндпоинт credential публичный и принимает идентификатор награды (тот же GUID, что виден в URL верификации вида https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
По умолчанию он возвращает подписанный VC-JWT как application/jwt. Добавьте ?format=json, чтобы получить неподписанный JSON credential для чтения. Оба варианта описаны в справочнике по верификации.
Обратите внимание: отдельного эндпоинта «проверь это за меня» нет, и это намеренно. Сервер, который говорит «да, действительно», просит вас доверять серверу. Смысл подписи в том, что вы можете проверить её сами по опубликованному ключу.
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"])
В этой библиотеке нет импорта 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 и отвергая всё остальное. Никогда не позволяйте токену выбирать, как его проверять.
Ошибки padding в base64. JWS использует base64url без padding. В Python padding нужно добавить обратно (см. выше), а в Go нужен RawURLEncoding, а не URLEncoding.
Подпись верна, но действителен ли credential сейчас? Подпись доказывает подлинность и целостность, но не текущий статус. Credential может быть корректно подписан и при этом отозван или просрочен. Проверьте exp в payload и статус отзыва, о котором речь ниже.
Не забывайте об отзыве
Каждый credential Open Badges 3.0 с https://badges.ninja содержит запись credentialStatus по спецификации W3C Bitstring Status List. Она указывает на credential со списком статусов, который можно получить по адресу /certify-badge/status/<listId>. Когда издатель отзывает награду, в этом списке переключается бит; список кешируется примерно на минуту, поэтому отзывы быстро доходят до верификаторов. Декодируйте список и прочитайте бит по statusListIndex credential: 1 — отозван, 0 — действует. Короткий пример такой проверки бита на Node есть в справочнике по верификации.
Полноценный верификатор делает три вещи: проверяет подпись, срок действия и бит отзыва. Как отзыв выглядит со стороны издателя, описано в руководстве по наградам.
Когда всё это вам не нужно
Большинству руководителей программ этот код писать не придётся, и это нормально. Для повседневных проверок откройте публичную страницу награды https://badges.ninja/awards/<awardId> и прочитайте её. Ей не нужны ни регистрация, ни ключ, а показывает она издателя, значок и статус. Получатели также могут скачать Verifiable Credential из меню «Download» на своей публичной странице credential и импортировать его в любой кошелёк Open Badges 3.0.
Проверка подписи становится ценной, когда:
- работодатель или университет хочет автоматизировать проверку получаемых credentials;
- вы строите систему учёта, которая хранит копии credentials и должна доказать, что они не изменены;
- аудитор просит подтверждение, что ваши credentials независимо верифицируемы, а не просто «доверьтесь нашему сайту».
Настройка API-ключа, которую вы используете для выдачи, здесь не нужна, потому что все эти эндпоинты публичные. Если вы хотите выдавать credentials из кода, быстрый старт API проведёт вас через создание ключа и первую награду.

Краткий справочник
| Элемент | Значение |
|---|---|
| Подписанный credential | 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 над первыми двумя сегментами. Добавьте проверки срока действия и отзыва — и вы получите верификатор, который не доверяет никому, кроме опубликованного ключа издателя. Именно эта независимость делает цифровой credential ценнее PDF.
Готовы выдать свой первый верифицируемый credential? Начните бесплатно на 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 для буткемпов по программированию: проверяемые credentials в масштабе потока19 нояб. 2026 г. · 10мин чтения
- Настройка вебхуков для событий бейджей: интеграция с вашим бэкендом в реальном времени16 нояб. 2026 г. · 8мин чтения
- Срок действия и продление Open Badges: управление жизненным циклом ограниченных по времени credentials12 нояб. 2026 г. · 10мин чтения


