Memverifikasi Tanda Tangan Open Badge di Node.js, Python, dan Go
Tiga contoh kode yang berfungsi (Node, Python, Go) untuk mengambil kredensial Open Badge yang ditandatangani, menemukan kunci publik penerbit, dan memverifikasi tanda tangan 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.
Jika Anda menerbitkan kredensial, sebagian besar pekerjaan verifikasi berlangsung tanpa Anda: penerima membagikan tautan, pemberi kerja mengkliknya, dan halaman verifikasi mengerjakan sisanya. Namun cepat atau lambat seseorang mengajukan pertanyaan yang lebih tajam. “Bagaimana saya tahu file ini benar-benar ditandatangani oleh Anda, dan tidak diubah setelahnya?” Pertanyaan itu dijawab oleh tanda tangan digital, dan memeriksanya hanya butuh sekitar lima belas baris kode di bahasa pemrograman arus utama mana pun.
Tutorial ini menunjukkan cara memverifikasi kredensial Open Badges 3.0 yang ditandatangani dan diterbitkan melalui https://badges.ninja, langkah demi langkah, di Node.js, Python, dan Go. Anda tidak perlu menjalankan satu pun dari ini untuk menerbitkan kredensial. Tutorial ini untuk Anda yang ingin mengaudit sistem, membangun alat verifikasi internal, atau sekadar memahami arti “verifiable” dalam praktik.
Apa yang sebenarnya Anda verifikasi
Ada dua lapisan verifikasi dalam Open Badges, dan sebaiknya keduanya dibedakan.
Verifikasi hosted adalah model Open Badges 2.0. Award memiliki URL publik, dan siapa pun yang membukanya melihat penerbit, lencana, identitas penerima yang di-hash, dan statusnya. Kepercayaan datang dari fakta bahwa data disajikan dari domain milik penerbit sendiri. Jika Anda bisa membuka halaman itu di https://badges.ninja, kredensial tersebut asli. Ini tidak membutuhkan kode maupun tanda tangan.
Verifikasi tanda tangan adalah model Open Badges 3.0, yang dibangun di atas W3C Verifiable Credentials. Kredensial dikemas sebagai token bertanda tangan, sehingga bisa diperiksa secara offline, bertahun-tahun kemudian, bahkan jika sudah disalin ke dompet digital atau lampiran email. Kepercayaan datang dari matematika: token membawa tanda tangan yang hanya bisa dibuat oleh pemegang kunci privat penerbit.
Di https://badges.ninja, setiap award tersedia dalam kedua bentuk. Artikel ini membahas bentuk yang kedua. Jika Anda ingin latar belakang perbedaan kedua versi, baca Open Badges v2 vs v3, dan untuk tur JSON hosted, lihat panduan Open Badge JSON-LD.
Bagian-bagian yang terlibat
Kredensial bertanda tangan adalah VC-JWT: JWS kompak, yaitu tiga string base64url yang dipisahkan titik.
header.payload.signature
- Header menjelaskan cara penandatanganan. Untuk kredensial kami, isinya
alg: EdDSA,typ: JWT, dankid(key id) yang tampak sepertidid:web:api.badges.ninja#<thumbprint>. - Payload memuat klaim, termasuk
iss(DID penerbitdid:web:api.badges.ninja),jti(id kredensial),nbf(berlaku mulai),expopsional (kedaluwarsa), dan objekvcberisiOpenBadgeCredentialyang sesungguhnya. - Tanda tangan adalah tanda tangan Ed25519 atas byte persis dari
header.payload.
Kunci publik yang memeriksa tanda tangan dipublikasikan penerbit di dua tempat, keduanya tanpa autentikasi:
https://api.badges.ninja/.well-known/jwks.jsonmengembalikan JWK Set.https://api.badges.ninja/.well-known/did.jsonmengembalikan dokumen DID untukdid:web:api.badges.ninja.
kid pada JWKS adalah thumbprint RFC 7638 dari kunci tersebut. kid pada header token adalah URL DID, dan fragmennya (bagian setelah #) adalah thumbprint yang sama. Fragmen itulah cara Anda memilih kunci yang tepat.
Resep verifikasi
Setiap bahasa mengikuti lima langkah yang sama:
- Ambil kredensial bertanda tangan dari endpoint publik.
- Pisahkan token menjadi tiga bagiannya.
- Baca header, pastikan
algpersisEdDSA, dan ambil thumbprint darikid. - Ambil JWKS dan cari kunci dengan
kidyang cocok. - Verifikasi tanda tangan Ed25519 atas
header.payloaddengan kunci tersebut.
Endpoint kredensial bersifat publik dan menerima id award (GUID yang sama dengan yang Anda lihat di URL verifikasi seperti https://badges.ninja/awards/<awardId>):
curl https://api.badges.ninja/certify-badge/award/<awardId>/vc
Secara default endpoint ini mengembalikan VC-JWT bertanda tangan sebagai application/jwt. Tambahkan ?format=json untuk mendapatkan JSON kredensial tanpa tanda tangan agar mudah dibaca. Referensi verifikasi mendokumentasikan keduanya.
Perhatikan bahwa tidak ada endpoint terpisah “verifikasikan ini untuk saya”, dan itu disengaja. Server yang memberi tahu Anda “ya, valid” meminta Anda memercayai server. Inti dari tanda tangan adalah Anda dapat memeriksanya sendiri terhadap kunci yang dipublikasikan.
Node.js
Modul crypto bawaan Node mendukung Ed25519 dan impor JWK, jadi Anda tidak butuh dependensi apa pun.
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);
Argumen algoritma null memang benar: pada Ed25519 jenis kunci sudah menentukan algoritmanya. Jika Anda lebih suka pustaka, jose melakukan hal yang sama dengan compactVerify dan importJWK, serta menangani pemeriksaan header untuk Anda.
Python
Paket cryptography menyediakan Ed25519 secara langsung. Instal dengan 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 tidak memiliki impor JWK untuk Ed25519 di pustaka ini, jadi kami men-decode sendiri koordinat x (kunci publik mentah 32 byte). Hanya itu isi JWK bertipe OKP dengan kurva Ed25519.
Go
Pustaka standar Go mencakup semuanya, termasuk 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)
}
Jalankan dengan go run main.go <awardId>. Penanganan error dipangkas agar mudah dibaca; pada alat sungguhan Anda akan memeriksa setiap decode.
Kesalahan umum dan cara membacanya
Kunci tidak ditemukan di JWKS. Anda membandingkan kid lengkap dari header token (did:web:api.badges.ninja#abc) dengan kid JWKS (abc). Bandingkan hanya fragmen setelah #. Jika fragmen masih tidak cocok, penerbit mungkin telah merotasi kunci sejak token dibuat; ambil dokumen DID dan lihat entri verificationMethod-nya.
Tanda tangan tidak valid pada token yang baru diunduh. Pastikan Anda memverifikasi header.payload sebagai teks base64url asli, bukan JSON yang dienkode ulang. Serialisasi ulang JSON mengubah byte dan merusak tanda tangan. Periksa juga apakah ada baris baru di akhir token yang diunduh.
Kebingungan algoritma. Serangan JWT klasik adalah token yang mengklaim alg: none atau beralih ke algoritma simetris sehingga verifier tertipu menerimanya. Contoh kami menghindarinya dengan menetapkan algoritma yang diharapkan, EdDSA, dan menolak yang lain. Jangan pernah biarkan token menentukan cara ia diverifikasi.
Kesalahan padding Base64. JWS memakai base64url tanpa padding. Python perlu menambahkan kembali padding (ditunjukkan di atas), dan Go membutuhkan RawURLEncoding, bukan URLEncoding.
Tanda tangan valid, tetapi apakah kredensialnya masih berlaku? Tanda tangan membuktikan keaslian dan integritas, bukan status saat ini. Kredensial bisa ditandatangani dengan benar namun tetap dicabut atau kedaluwarsa. Periksa exp di payload, dan periksa status pencabutan yang dijelaskan berikutnya.
Jangan lupakan pencabutan
Setiap kredensial Open Badges 3.0 dari https://badges.ninja memiliki entri credentialStatus yang mengikuti W3C Bitstring Status List. Entri itu menunjuk ke kredensial status list yang dapat Anda ambil di /certify-badge/status/<listId>. Ketika penerbit mencabut sebuah award, satu bit pada daftar itu berubah; daftar di-cache sekitar satu menit, sehingga pencabutan cepat sampai ke verifier. Decode daftarnya dan baca bit pada statusListIndex milik kredensial: 1 berarti dicabut, 0 berarti aktif. Referensi verifikasi menyertakan contoh Node singkat untuk pemeriksaan bit tersebut.
Verifier yang lengkap melakukan tiga hal: memverifikasi tanda tangan, memeriksa kedaluwarsa, dan memeriksa bit pencabutan. Jika Anda ingin melihat seperti apa pencabutan dari sisi penerbit, tindakan di dasbor dibahas di panduan award.
Kapan Anda tidak membutuhkan semua ini
Sebagian besar pengelola program tidak akan pernah menulis kode ini, dan itu tidak masalah. Untuk pemeriksaan sehari-hari, buka halaman publik award di https://badges.ninja/awards/<awardId> dan baca saja. Halaman ini tidak memerlukan pendaftaran maupun kunci, dan menampilkan penerbit, lencana, dan status. Penerima juga dapat mengunduh Verifiable Credential dari menu Download di halaman kredensial publik mereka, lalu mengimpornya ke dompet Open Badges 3.0 mana pun.
Pemeriksaan tanda tangan menjadi berharga ketika:
- pemberi kerja atau universitas ingin mengotomatiskan pemeriksaan kredensial yang mereka terima;
- Anda membangun sistem pencatatan yang menyimpan salinan kredensial dan perlu membuktikan bahwa salinan itu tidak diubah;
- auditor meminta bukti bahwa kredensial Anda dapat diverifikasi secara independen, bukan sekadar “percayai situs kami”.
Pengaturan API key yang sama seperti untuk penerbitan tidak diperlukan di sini, karena semua endpoint ini bersifat publik. Jika Anda ingin menerbitkan kredensial lewat kode, panduan cepat API menjelaskan cara membuat key dan award pertama Anda.

Referensi cepat
| Item | Nilai |
|---|---|
| Kredensial bertanda tangan | GET https://api.badges.ninja/certify-badge/award/<awardId>/vc |
| JSON tanpa tanda tangan untuk dibaca | URL yang sama dengan ?format=json |
| DID penerbit | did:web:api.badges.ninja |
| Kunci publik | /.well-known/jwks.json dan /.well-known/did.json |
| Algoritma | Ed25519 (EdDSA) |
| Pencocokan kunci | fragmen kid header sama dengan kid JWKS |
| Pencabutan | credentialStatus yang menunjuk ke /certify-badge/status/<listId> |
Penutup
Memverifikasi tanda tangan Open Badge adalah rutinitas yang singkat dan mekanis: ambil token, kunci algoritmanya, temukan kunci lewat thumbprint, dan periksa tanda tangan Ed25519 atas dua segmen pertama. Tambahkan pemeriksaan kedaluwarsa dan pencabutan, dan Anda punya verifier yang tidak memercayai siapa pun selain kunci yang dipublikasikan penerbit. Kemandirian itulah yang membuat kredensial digital lebih berharga daripada PDF.
Siap menerbitkan kredensial terverifikasi pertama Anda? Mulai gratis di badges.ninja — desainer visual, halaman verifikasi publik, sertifikat PDF, keluaran Open Badge v2.0. Tanpa kartu kredit.
Bagaimana artikel ini dibuat
Beberapa artikel di blog ini disusun dengan bantuan asisten AI, lalu ditinjau, diperiksa faktanya, dan disunting oleh tim Badges Ninja sebelum dipublikasikan. Setiap contoh kode dan harga diverifikasi terhadap produk yang aktif. Baca selengkapnya tentang proses editorial dan AI kami di halaman proses editorial .

Tentang penulis
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.
Lainnya dari Nacho Coll
- Open Badges untuk Bootcamp Coding: Menerbitkan Kredensial Terverifikasi dalam Skala Angkatan19 Nov 2026 · 10menit baca
- Menyiapkan Webhook untuk Peristiwa Lencana: Integrasi Real-Time dengan Backend Anda16 Nov 2026 · 8menit baca
- Masa Berlaku dan Perpanjangan Open Badge: Manajemen Siklus Hidup Kredensial Berbatas Waktu12 Nov 2026 · 10menit baca


