Node.js、Python、Go で Open Badge の署名を検証する
署名付き Open Badge クレデンシャルを取得し、発行者の公開鍵を解決して JWS 署名を検証するための、動作するコードサンプル 3 種(Node、Python、Go)。
クレデンシャルを発行する側であれば、検証作業のほとんどは自動で行われます。受取人がリンクを共有し、雇用主がそれをクリックすれば、あとは検証ページが処理してくれます。ところが遅かれ早かれ、もっと鋭い質問が飛んできます。「このファイルが本当にあなたによって署名され、あとから改ざんされていないとどうやって分かるのですか?」この問いに答えるのがデジタル署名であり、主要な言語ならわずか 15 行ほどのコードで確認できます。
このチュートリアルでは、https://badges.ninja で発行された署名付き Open Badges 3.0 クレデンシャルを、Node.js、Python、Go で順を追って検証する方法を紹介します。クレデンシャルを発行するだけなら、どれも実行する必要はありません。システムを監査したい方、社内向けの検証ツールを作りたい方、あるいは「検証可能」が実際に何を意味するのかを理解したい方のための内容です。
実際に何を検証するのか
Open Badges には 2 つの検証レイヤーがあり、区別しておくと理解しやすくなります。
ホスト型検証は Open Badges 2.0 のモデルです。受賞には公開 URL があり、開けば誰でも発行者、バッジ、受取人のハッシュ化された ID、ステータスを確認できます。信頼の根拠は、データが発行者自身のドメインから配信されていることです。https://badges.ninja 上でそのページに到達できれば、クレデンシャルは本物です。コードも署名も不要です。
署名検証は、W3C Verifiable Credentials をベースにした Open Badges 3.0 のモデルです。クレデンシャルは署名付きトークンとしてパッケージ化されているため、ウォレットやメール添付にコピーされた後でも、何年経ってもオフラインで検証できます。信頼の根拠は数学です。トークンには、発行者の秘密鍵の持ち主にしか作れない署名が含まれています。
https://badges.ninja では、すべての受賞が両方の形式で利用できます。この記事は後者について解説します。2 つのバージョンの違いについては Open Badges v2 vs v3 を、ホスト型 JSON の解説は Open Badge JSON-LD ウォークスルー をご覧ください。
構成要素
署名付きクレデンシャルは VC-JWT です。ドットで区切られた 3 つの base64url 文字列からなる、コンパクトな JWS です。
header.payload.signature
- ヘッダーは署名方法を示します。当サービスのクレデンシャルでは
alg: EdDSA、typ: JWT、そしてdid:web:api.badges.ninja#<thumbprint>の形をしたkid(鍵 ID)が含まれます。 - ペイロードにはクレームが入っています。
iss(発行者 DIDdid:web:api.badges.ninja)、jti(クレデンシャル ID)、nbf(有効開始)、任意のexp(有効期限)、そして実際のOpenBadgeCredentialを持つvcオブジェクトです。 - 署名は、
header.payloadの正確なバイト列に対する Ed25519 署名です。
署名を検証する公開鍵は、発行者が認証なしで次の 2 か所に公開しています。
https://api.badges.ninja/.well-known/jwks.jsonは JWK Set を返します。https://api.badges.ninja/.well-known/did.jsonはdid:web:api.badges.ninjaの DID ドキュメントを返します。
JWKS の kid は、鍵の RFC 7638 サムプリントです。トークンヘッダーの kid は DID URL で、そのフラグメント(# の後ろの部分)が同じサムプリントになっています。このフラグメントを使って正しい鍵を選びます。
検証の手順
どの言語でも、次の 5 ステップは同じです。
- 公開エンドポイントから署名付きクレデンシャルを取得します。
- トークンを 3 つの部分に分割します。
- ヘッダーを読み、
algがちょうどEdDSAであることを確認し、kidからサムプリントを取り出します。 - JWKS を取得し、
kidが一致する鍵を探します。 - その鍵で
header.payloadに対する Ed25519 署名を検証します。
クレデンシャルのエンドポイントは公開されており、受賞 ID(https://badges.ninja/awards/<awardId> のような検証 URL に含まれるものと同じ GUID)を受け取ります。
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
デフォルトでは、署名付き VC-JWT が application/jwt として返されます。?format=json を付けると、読むための署名なしクレデンシャル JSON が得られます。どちらも検証リファレンスに記載されています。
「これを検証してください」という別のエンドポイントがないのは、意図的です。「はい、有効です」と答えるサーバーは、そのサーバーを信頼することをあなたに求めます。署名の本質は、公開された鍵を使って自分で確かめられることにあります。
Node.js
Node 組み込みの crypto モジュールは 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"])
このライブラリには Ed25519 の JWK インポート機能がないため、x 座標(生の 32 バイト公開鍵)を自分でデコードします。曲線が Ed25519 の OKP タイプの JWK に含まれるのは、それだけです。
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)と、JWKS の kid(abc)を比較しています。# の後ろのフラグメントだけを比較してください。それでも一致しない場合は、トークン発行後に発行者が鍵をローテーションした可能性があります。DID ドキュメントを取得し、verificationMethod のエントリを確認してください。
ダウンロードしたばかりのトークンで署名が無効になる。 header.payload を、再エンコードした JSON ではなく元の base64url テキストのまま検証したか確認してください。JSON を再シリアライズするとバイト列が変わり、署名が壊れます。ダウンロードしたトークンの末尾に改行が付いていないかも確認しましょう。
アルゴリズム混同。 古典的な JWT 攻撃では、トークンが alg: none を名乗ったり、対称アルゴリズムに切り替えたりして、検証側をだまして受け入れさせます。このサンプルは、期待するアルゴリズム EdDSA をハードコードし、それ以外をすべて拒否することで防いでいます。検証方法をトークンに決めさせてはいけません。
Base64 のパディングエラー。 JWS はパディングなしの base64url を使います。Python では(上記のように)パディングを補う必要があり、Go では URLEncoding ではなく RawURLEncoding が必要です。
署名は有効でも、クレデンシャルはまだ有効か? 署名が証明するのは真正性と完全性であり、現在のステータスではありません。正しく署名されていても、失効や期限切れになっていることはあります。ペイロードの exp と、次に説明する失効ステータスを確認してください。
失効の確認を忘れずに
https://badges.ninja が発行するすべての Open Badges 3.0 クレデンシャルには、W3C Bitstring Status List に従った credentialStatus が含まれています。これは /certify-badge/status/<listId> で取得できるステータスリストのクレデンシャルを指します。発行者が受賞を失効させると、そのリストのビットが 1 つ反転します。リストは約 1 分間キャッシュされるので、失効はすぐに検証側へ届きます。リストをデコードし、クレデンシャルの statusListIndex の位置のビットを読んでください。1 は失効、0 は有効を意味します。検証リファレンスには、このビットチェックの短い Node の例が載っています。
完全な検証ツールは 3 つのことを行います。署名の検証、有効期限の確認、失効ビットの確認です。発行者側から見た失効の様子を知りたい場合は、ダッシュボードの操作を受賞ガイドで解説しています。
これらが不要な場合
ほとんどのプログラム運営者は、このコードを書くことはなく、それで問題ありません。日常的な確認なら、受賞の公開ページ https://badges.ninja/awards/<awardId> を開いて読むだけです。このページはサインアップも鍵も不要で、発行者、バッジ、ステータスが表示されます。受取人は、公開クレデンシャルページの Download メニューから 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 のフラグメントが JWKS の kid と一致 |
| 失効 | /certify-badge/status/<listId> を指す credentialStatus |
まとめ
Open Badge の署名検証は、短く機械的な手順です。トークンを取得し、アルゴリズムを固定し、サムプリントで鍵を見つけ、最初の 2 つのセグメントに対する Ed25519 署名を確認します。有効期限と失効のチェックを加えれば、発行者が公開した鍵だけを信頼する検証ツールの完成です。この独立性こそが、デジタルクレデンシャルを PDF 以上の価値あるものにしています。
最初の検証可能なクレデンシャルを発行する準備はできましたか? badges.ninja で無料で始める — ビジュアルデザイナー、公開検証ページ、PDF 証明書、Open Badge v2.0 出力。クレジットカードは不要です。
この記事の作成方法
このブログの記事の一部は、AIアシスタントの支援を受けて下書きされた後、公開前にBadges Ninjaチームがレビュー、ファクトチェック、編集を行っています。すべてのコードサンプルと価格は実際の製品と照合して検証済みです。編集方針とAIプロセスについて詳しくは、 編集プロセスページ .

著者について
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.


