用 Node.js、Python 和 Go 驗證 Open Badge 簽章
三份可執行的程式碼範例(Node、Python、Go),教你取得已簽章的 Open Badge 憑證、解析簽發者的公開金鑰,並驗證 JWS 簽章。
如果你負責簽發憑證,大部分驗證工作其實不需要你插手:接收者分享一個連結,雇主點開,驗證頁面就會完成剩下的事。但遲早會有人問出更尖銳的問題:「我怎麼知道這個檔案真的是你們簽發的,而且事後沒被改過?」回答這個問題靠的是數位簽章,而在任何主流語言裡,驗證一個簽章大約只需要十五行程式碼。
本教學會一步步示範,如何在 Node.js、Python 和 Go 中驗證透過 https://badges.ninja 簽發的、已簽章的 Open Badges 3.0 憑證。簽發憑證並不需要執行其中任何程式碼。它是寫給想要稽核系統、建立內部驗證工具,或者只是想弄明白「可驗證」在實務上代表什麼的人。
你到底在驗證什麼
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,以及形如did:web:api.badges.ninja#<thumbprint>的kid(金鑰 ID)。 - **酬載(payload)**包含各項宣告,其中有
iss(簽發者 DIDdid:web:api.badges.ninja)、jti(憑證 ID)、nbf(生效時間)、選用的exp(到期時間),以及包含實際OpenBadgeCredential的vc物件。 - **簽章(signature)**是對
header.payload的精確位元組計算出的 Ed25519 簽章。
用來驗證簽章的公開金鑰由簽發者發布在兩個位置,皆無需身分驗證:
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 指紋(thumbprint)。權杖標頭中的 kid 是 DID URL,它的片段(# 之後的部分)正是同一個指紋。靠這個片段,你就能挑出正確的金鑰。
驗證流程
每種語言都遵循同樣的五個步驟:
- 從公開端點取得已簽章的憑證。
- 把權杖拆成三個部分。
- 讀取標頭,確認
alg恰好是EdDSA,並從kid中取出指紋。 - 取得 JWKS,找出
kid相符的金鑰。 - 用該金鑰驗證對
header.payload的 Ed25519 簽章。
憑證端點是公開的,參數為獎項 ID(就是驗證 URL 中看到的那個 GUID,例如 https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
預設情況下,它會以 application/jwt 回傳已簽章的 VC-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"])
這個函式庫中 Python 沒有針對 Ed25519 的 JWK 匯入功能,所以我們自己解碼 x 座標(即 32 位元組的原始公開金鑰)。類型為 OKP、曲線為 Ed25519 的 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 項目。
剛下載的權杖簽章無效。 檢查你驗證的是原始 base64url 文字 header.payload,而不是重新編碼後的 JSON。重新序列化 JSON 會改變位元組,進而破壞簽章。同時檢查下載的權杖結尾是否帶有換行字元。
演算法混淆。 經典的 JWT 攻擊是:權杖宣稱 alg: none,或切換成對稱演算法,誘使驗證方接受它。我們的範例透過寫死預期的演算法 EdDSA 並拒絕其他一切來避開這個問題。永遠不要讓權杖自己決定要如何被驗證。
Base64 填充錯誤。 JWS 使用不帶填充的 base64url。Python 需要把填充補回去(如上所示),Go 需要使用 RawURLEncoding,而不是 URLEncoding。
簽章有效,但憑證現在還有效嗎? 簽章證明的是真實性和完整性,而不是目前狀態。一份憑證可能簽章正確,卻已被撤銷或已過期。請檢查酬載中的 exp,並檢查下面介紹的撤銷狀態。
別忘了撤銷狀態
https://badges.ninja 上的每份 Open Badges 3.0 憑證都帶有一個遵循 W3C Bitstring Status List 的 credentialStatus 項目。它指向一份狀態清單憑證,你可以在 /certify-badge/status/<listId> 取得。當簽發者撤銷某個獎項時,該清單中的一個位元會翻轉;清單會快取約一分鐘,因此撤銷會很快傳達給驗證方。解碼該清單,讀取憑證 statusListIndex 處的位元:1 表示已撤銷,0 表示有效。驗證參考文件中包含一個檢查該位元的簡短 Node 範例。
一個完整的驗證程式要做三件事:驗證簽章、檢查有效期限、檢查撤銷位元。如果想從簽發者這一側看看撤銷是什麼樣子,儀表板中的操作在獎項指南中有介紹。
什麼時候你不需要這些
大多數專案負責人永遠不會寫這類程式碼,這完全沒問題。日常檢查時,打開獎項的公開頁面 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 |
| 撤銷 | credentialStatus 指向 /certify-badge/status/<listId> |
總結
驗證 Open Badge 簽章是一套簡短、機械的流程:取得權杖、固定演算法、依指紋找到金鑰,再對前兩段檢查 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.


