Xác minh chữ ký Open Badge bằng Node.js, Python và Go
Ba đoạn mã mẫu chạy được (Node, Python, Go) để lấy credential Open Badge đã ký, tìm khóa công khai của tổ chức cấp và xác minh chữ ký 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.
Nếu bạn cấp credential, phần lớn công việc xác minh diễn ra mà không cần bạn: người nhận chia sẻ một liên kết, nhà tuyển dụng bấm vào, và trang xác minh lo phần còn lại. Nhưng sớm muộn cũng có người hỏi một câu sắc hơn: “Làm sao tôi biết tệp này thật sự do bạn ký, và không bị chỉnh sửa sau đó?” Câu hỏi ấy được trả lời bằng chữ ký số, và kiểm tra nó chỉ mất khoảng mười lăm dòng mã trong bất kỳ ngôn ngữ phổ biến nào.
Hướng dẫn này chỉ cho bạn cách xác minh từng bước một credential Open Badges 3.0 đã ký, được cấp qua https://badges.ninja, bằng Node.js, Python và Go. Bạn không cần chạy bất kỳ đoạn nào trong số này để cấp credential. Bài viết dành cho những ai muốn kiểm toán hệ thống, xây công cụ xác minh nội bộ, hoặc đơn giản là hiểu “verifiable” nghĩa là gì trong thực tế.
Bạn thực sự đang xác minh điều gì
Open Badges có hai lớp xác minh, và nên tách bạch chúng.
Xác minh được lưu trữ (hosted) là mô hình của Open Badges 2.0. Award có một URL công khai, và bất kỳ ai mở nó đều thấy tổ chức cấp, huy hiệu, danh tính đã băm của người nhận và trạng thái. Niềm tin đến từ việc dữ liệu được phục vụ từ chính tên miền của tổ chức cấp. Nếu bạn truy cập được trang đó trên https://badges.ninja, credential là thật. Cách này không cần mã và không cần chữ ký.
Xác minh chữ ký là mô hình của Open Badges 3.0, xây dựng trên W3C Verifiable Credentials. Credential được đóng gói thành một token đã ký, nên có thể kiểm tra ngoại tuyến, nhiều năm sau, ngay cả khi nó đã được sao chép vào ví hoặc tệp đính kèm email. Niềm tin đến từ toán học: token mang một chữ ký mà chỉ người giữ khóa riêng của tổ chức cấp mới tạo ra được.
Trên https://badges.ninja, mỗi award đều có cả hai dạng. Bài viết này nói về dạng thứ hai. Nếu bạn muốn biết bối cảnh về sự khác nhau giữa hai phiên bản, hãy đọc Open Badges v2 vs v3, và để xem JSON được lưu trữ, hãy xem hướng dẫn chi tiết Open Badge JSON-LD.
Các thành phần chính
Credential đã ký là một VC-JWT: một JWS dạng gọn, gồm ba chuỗi base64url ngăn cách bằng dấu chấm.
header.payload.signature
- Header cho biết cách ký. Với credential của chúng tôi, nó chứa
alg: EdDSA,typ: JWTvà mộtkid(key id) có dạngdid:web:api.badges.ninja#<thumbprint>. - Payload chứa các claim, gồm
iss(DID của tổ chức cấpdid:web:api.badges.ninja),jti(id credential),nbf(có hiệu lực từ),exptùy chọn (hết hạn), và đối tượngvcchứaOpenBadgeCredentialthực sự. - Chữ ký là chữ ký Ed25519 trên đúng các byte của
header.payload.
Khóa công khai dùng để kiểm tra chữ ký được tổ chức cấp công bố ở hai nơi, đều không cần xác thực:
https://api.badges.ninja/.well-known/jwks.jsontrả về một JWK Set.https://api.badges.ninja/.well-known/did.jsontrả về tài liệu DID củadid:web:api.badges.ninja.
kid trong JWKS là thumbprint RFC 7638 của khóa. kid trong header của token là một DID URL, và phần fragment của nó (phần sau #) chính là thumbprint đó. Fragment này là cách bạn chọn đúng khóa.
Công thức xác minh
Mọi ngôn ngữ đều theo cùng năm bước:
- Lấy credential đã ký từ endpoint công khai.
- Tách token thành ba phần.
- Đọc header, kiểm tra
algđúng bằngEdDSA, và lấy thumbprint từkid. - Lấy JWKS và tìm khóa có
kidkhớp. - Xác minh chữ ký Ed25519 trên
header.payloadbằng khóa đó.
Endpoint credential là công khai và nhận id của award (cùng GUID bạn thấy trong URL xác minh như https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Mặc định endpoint trả về VC-JWT đã ký dưới dạng application/jwt. Thêm ?format=json để nhận JSON credential chưa ký cho mục đích đọc. Tài liệu tham chiếu xác minh mô tả cả hai.
Lưu ý rằng không có endpoint “xác minh giúp tôi” riêng, và đó là chủ ý. Một máy chủ nói với bạn “đúng, hợp lệ” là đang yêu cầu bạn tin máy chủ. Toàn bộ ý nghĩa của chữ ký là bạn tự kiểm tra nó với khóa đã công bố.
Node.js
Module crypto có sẵn của Node hỗ trợ Ed25519 và nhập JWK, nên bạn không cần phụ thuộc nào.
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);
Đối số thuật toán null là đúng: với Ed25519, loại khóa đã quyết định thuật toán. Nếu bạn thích dùng thư viện, jose làm việc tương tự với compactVerify và importJWK, đồng thời xử lý giúp bạn các bước kiểm tra header.
Python
Gói cryptography cung cấp trực tiếp Ed25519. Cài đặt bằng 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"])
Thư viện này không có hàm nhập JWK cho Ed25519 trong Python, nên chúng tôi tự giải mã tọa độ x (khóa công khai thô 32 byte). Đó là tất cả những gì một JWK loại OKP với đường cong Ed25519 chứa.
Go
Thư viện chuẩn của Go bao quát mọi thứ, gồm cả 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)
}
Chạy bằng go run main.go <awardId>. Phần xử lý lỗi được lược bớt cho dễ đọc; trong công cụ thực tế bạn sẽ kiểm tra mọi bước giải mã.
Lỗi thường gặp và cách đọc chúng
Không tìm thấy khóa trong JWKS. Bạn đã so sánh kid đầy đủ từ header của token (did:web:api.badges.ninja#abc) với kid của JWKS (abc). Hãy chỉ so sánh fragment sau #. Nếu fragment vẫn không khớp, có thể tổ chức cấp đã xoay khóa kể từ khi token được tạo; hãy lấy tài liệu DID và xem các mục verificationMethod của nó.
Chữ ký không hợp lệ trên token vừa tải về. Hãy kiểm tra rằng bạn xác minh header.payload dưới dạng văn bản base64url gốc, không phải JSON đã mã hóa lại. Việc tuần tự hóa lại JSON làm thay đổi các byte và phá vỡ chữ ký. Cũng hãy kiểm tra xem token tải về có ký tự xuống dòng ở cuối không.
Nhầm lẫn thuật toán. Kiểu tấn công JWT kinh điển là token tuyên bố alg: none hoặc chuyển sang thuật toán đối xứng để đánh lừa bộ xác minh chấp nhận nó. Các mẫu của chúng tôi tránh điều này bằng cách cố định thuật toán mong đợi là EdDSA và từ chối mọi thứ khác. Đừng bao giờ để token quyết định cách nó được xác minh.
Lỗi padding Base64. JWS dùng base64url không có padding. Python cần thêm lại padding (như ở trên), và Go cần RawURLEncoding, không phải URLEncoding.
Chữ ký hợp lệ, nhưng credential còn dùng được không? Chữ ký chứng minh tính xác thực và toàn vẹn, không phải trạng thái hiện tại. Một credential có thể được ký đúng mà vẫn bị thu hồi hoặc hết hạn. Hãy kiểm tra exp trong payload, và kiểm tra trạng thái thu hồi được mô tả ngay sau đây.
Đừng quên thu hồi
Mọi credential Open Badges 3.0 từ https://badges.ninja đều có mục credentialStatus theo W3C Bitstring Status List. Nó trỏ tới một status list credential mà bạn có thể lấy tại /certify-badge/status/<listId>. Khi tổ chức cấp thu hồi một award, một bit trong danh sách đó được lật; danh sách được cache khoảng một phút, nên việc thu hồi đến với các bộ xác minh rất nhanh. Hãy giải mã danh sách và đọc bit tại statusListIndex của credential: 1 nghĩa là đã thu hồi, 0 nghĩa là đang hoạt động. Tài liệu tham chiếu xác minh có một ví dụ Node ngắn về việc kiểm tra bit này.
Một bộ xác minh đầy đủ làm ba việc: xác minh chữ ký, kiểm tra hạn dùng và kiểm tra bit thu hồi. Nếu bạn muốn xem thu hồi trông thế nào từ phía tổ chức cấp, thao tác trên dashboard được trình bày trong hướng dẫn về award.
Khi bạn không cần đến những điều này
Hầu hết chủ chương trình sẽ không bao giờ viết đoạn mã này, và như vậy là ổn. Với việc kiểm tra hằng ngày, hãy mở trang công khai của award tại https://badges.ninja/awards/<awardId> và đọc nó. Trang này không cần đăng ký hay khóa, và hiển thị tổ chức cấp, huy hiệu và trạng thái. Người nhận cũng có thể tải Verifiable Credential từ menu Download trên trang credential công khai của họ, rồi nhập vào bất kỳ ví Open Badges 3.0 nào.
Việc kiểm tra chữ ký trở nên giá trị khi:
- nhà tuyển dụng hoặc trường đại học muốn tự động hóa việc kiểm tra các credential họ nhận được;
- bạn đang xây hệ thống lưu hồ sơ giữ bản sao credential và cần chứng minh chúng không bị thay đổi;
- kiểm toán viên yêu cầu bằng chứng rằng credential của bạn có thể xác minh độc lập, chứ không chỉ là “hãy tin website của chúng tôi”.
Không cần thiết lập API key như khi cấp credential, vì tất cả các endpoint này đều công khai. Nếu bạn muốn cấp credential từ mã, hướng dẫn nhanh API sẽ chỉ cách tạo key và award đầu tiên.

Tra cứu nhanh
| Mục | Giá trị |
|---|---|
| Credential đã ký | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| JSON chưa ký để đọc | cùng URL với ?format=json |
| DID của tổ chức cấp | did:web:api.badges.ninja |
| Khóa công khai | /.well-known/jwks.json và /.well-known/did.json |
| Thuật toán | Ed25519 (EdDSA) |
| Khớp khóa | fragment của kid trong header bằng kid của JWKS |
| Thu hồi | credentialStatus trỏ tới /certify-badge/status/<listId> |
Lời kết
Xác minh chữ ký Open Badge là một quy trình ngắn và máy móc: lấy token, cố định thuật toán, tìm khóa theo thumbprint và kiểm tra chữ ký Ed25519 trên hai đoạn đầu. Thêm kiểm tra hạn dùng và thu hồi, bạn có một bộ xác minh không tin ai ngoài khóa mà tổ chức cấp đã công bố. Chính sự độc lập đó làm credential số có giá trị hơn một tệp PDF.
Sẵn sàng cấp credential có thể xác minh đầu tiên của bạn? Bắt đầu miễn phí tại badges.ninja — trình thiết kế trực quan, trang xác minh công khai, chứng chỉ PDF, đầu ra Open Badge v2.0. Không cần thẻ tín dụng.
Bài viết này được thực hiện như thế nào
Một số bài viết trên blog này được soạn với sự hỗ trợ của trợ lý AI, sau đó được đội ngũ Badges Ninja xem xét, kiểm chứng và biên tập trước khi xuất bản. Mọi đoạn code và mức giá đều được đối chiếu với sản phẩm thực tế. Tìm hiểu thêm về quy trình biên tập và AI của chúng tôi tại trang quy trình biên tập .

Về tác giả
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.
Thêm bài viết của Nacho Coll
- Open Badges cho bootcamp lập trình: Cấp chứng chỉ có thể xác minh ở quy mô khóa học19 thg 11, 2026 · 14phút đọc
- Thiết lập Webhook cho sự kiện huy hiệu: Tích hợp thời gian thực với backend của bạn16 thg 11, 2026 · 11phút đọc
- Hết hạn và gia hạn Open Badge: Quản lý vòng đời cho chứng chỉ có thời hạn12 thg 11, 2026 · 14phút đọc


