Node.js, Python, Go로 Open Badge 서명 검증하기

서명된 Open Badge 자격 증명을 가져와 발급자의 공개 키를 확인하고 JWS 서명을 검증하는, 바로 동작하는 코드 샘플 세 가지(Node, Python, Go).

Nacho Coll 작성자 업데이트됨 17 분 읽기
서명된 Open Badge 자격 증명을 가져와 발급자의 공개 키를 확인하고 JWS 서명을 검증하는, 바로 동작하는 코드 샘플 세 가지(Node, Python, Go).

자격 증명을 발급하는 입장이라면 검증 작업의 대부분은 알아서 처리돼요. 수령자가 링크를 공유하고, 고용주가 그 링크를 클릭하면 나머지는 검증 페이지가 해결해 주니까요. 하지만 언젠가는 더 날카로운 질문을 받게 돼요. “이 파일이 정말 당신이 서명한 거고, 나중에 수정되지 않았다는 걸 어떻게 알 수 있죠?” 이 질문에 답하는 것이 디지털 서명이고, 주요 언어라면 15줄 정도의 코드로 확인할 수 있어요.

이 튜토리얼에서는 https://badges.ninja 에서 발급한 서명된 Open Badges 3.0 자격 증명을 Node.js, Python, Go로 단계별로 검증하는 방법을 보여 드려요. 자격 증명을 발급하는 데는 아무것도 실행할 필요가 없어요. 시스템을 감사하고 싶거나, 내부 검증 도구를 만들고 싶거나, “검증 가능”이 실제로 무엇을 뜻하는지 이해하고 싶은 분들을 위한 글이에요.

실제로 무엇을 검증하나요

Open Badges에는 두 가지 검증 계층이 있고, 둘을 구분해 두면 도움이 돼요.

호스팅 검증은 Open Badges 2.0 모델이에요. 수여 내역에는 공개 URL이 있고, 누구든 열어 보면 발급자, 배지, 수령자의 해시된 신원, 상태를 볼 수 있어요. 데이터가 발급자 본인의 도메인에서 제공된다는 점이 신뢰의 근거예요. https://badges.ninja 에서 해당 페이지에 접속할 수 있다면 그 자격 증명은 진짜예요. 코드도 서명도 필요 없어요.

서명 검증은 W3C Verifiable Credentials를 기반으로 한 Open Badges 3.0 모델이에요. 자격 증명이 서명된 토큰으로 패키징되어 있어서, 지갑이나 이메일 첨부 파일로 복사된 뒤에도 몇 년이 지나서도 오프라인으로 확인할 수 있어요. 신뢰의 근거는 수학이에요. 토큰에는 발급자의 개인 키를 가진 쪽만 만들 수 있는 서명이 들어 있거든요.

https://badges.ninja 에서는 모든 수여 내역을 두 가지 형태로 모두 제공해요. 이 글은 두 번째 방식에 대한 이야기예요. 두 버전의 차이에 대한 배경은 Open Badges v2 vs v3를, 호스팅된 JSON 둘러보기는 Open Badge JSON-LD 워크스루를 읽어 보세요.

구성 요소

서명된 자격 증명은 VC-JWT예요. 점으로 구분된 base64url 문자열 세 개로 이루어진 컴팩트 JWS죠.

header.payload.signature
  • 헤더는 어떻게 서명했는지 알려 줘요. 저희 자격 증명에는 alg: EdDSA, typ: JWT, 그리고 did:web:api.badges.ninja#<thumbprint> 형태의 kid(키 ID)가 들어 있어요.
  • 페이로드에는 클레임이 담겨 있어요. iss(발급자 DID did:web:api.badges.ninja), jti(자격 증명 ID), nbf(유효 시작), 선택 사항인 exp(만료), 그리고 실제 OpenBadgeCredential이 들어 있는 vc 객체가 있어요.
  • 서명은 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 썸프린트예요. 토큰 헤더의 kid는 DID URL이고, 그 프래그먼트(# 뒤의 부분)가 바로 같은 썸프린트예요. 이 프래그먼트로 올바른 키를 고르면 돼요.

검증 절차

어떤 언어든 다음 다섯 단계를 따라요.

  1. 공개 엔드포인트에서 서명된 자격 증명을 가져와요.
  2. 토큰을 세 부분으로 나눠요.
  3. 헤더를 읽고 alg가 정확히 EdDSA인지 확인한 다음, kid에서 썸프린트를 꺼내요.
  4. JWKS를 가져와서 kid가 일치하는 키를 찾아요.
  5. 그 키로 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분 동안 캐시되므로 취소 사항이 검증하는 쪽에 빠르게 전달돼요. 목록을 디코딩해서 자격 증명의 statusListIndex 위치에 있는 비트를 읽으세요. 1이면 취소됨, 0이면 활성 상태예요. 검증 레퍼런스에 이 비트 확인을 보여 주는 짧은 Node 예제가 있어요.

완전한 검증기는 세 가지를 해요. 서명 검증, 만료 확인, 취소 비트 확인이에요. 발급자 입장에서 취소가 어떻게 보이는지 궁금하다면, 대시보드 동작을 수여 가이드에서 다루고 있어요.

이 모든 게 필요 없는 경우

대부분의 프로그램 운영자는 이 코드를 직접 쓸 일이 없고, 그래도 괜찮아요. 일상적인 확인은 수여 내역의 공개 페이지 https://badges.ninja/awards/<awardId> 를 열어서 읽으면 돼요. 이 페이지는 가입도 키도 필요 없고, 발급자와 배지, 상태를 보여 줘요. 수령자는 공개 자격 증명 페이지의 Download 메뉴에서 Verifiable Credential을 내려받아 어떤 Open Badges 3.0 지갑으로든 가져올 수도 있어요.

서명 확인이 빛을 발하는 경우는 다음과 같아요.

  • 고용주나 대학이 받은 자격 증명의 확인을 자동화하고 싶을 때
  • 자격 증명 사본을 저장하는 기록 시스템을 만들면서 변조되지 않았음을 증명해야 할 때
  • 감사 담당자가 “저희 웹사이트를 믿으세요”가 아니라 자격 증명이 독립적으로 검증 가능하다는 증거를 요구할 때

발급에 쓰는 API 키 설정은 여기서는 필요 없어요. 이 엔드포인트들은 모두 공개되어 있으니까요. 코드로 자격 증명을 발급하고 싶다면 API 퀵스타트에서 키 생성부터 첫 수여까지 안내해요.

API Keys — empty state

빠른 참조

항목값
서명된 자격 증명GET https://api.badges.ninja/certify-badge/award/<awardId>/vc
읽기용 서명 없는 JSON같은 URL에 ?format=json
발급자 DIDdid:web:api.badges.ninja
공개 키/.well-known/jwks.json 및 /.well-known/did.json
알고리즘Ed25519 (EdDSA)
키 매칭헤더 kid의 프래그먼트가 JWKS kid와 같음
취소/certify-badge/status/<listId> 를 가리키는 credentialStatus

마무리

Open Badge 서명 검증은 짧고 기계적인 절차예요. 토큰을 가져오고, 알고리즘을 고정하고, 썸프린트로 키를 찾고, 앞의 두 세그먼트에 대한 Ed25519 서명을 확인하면 돼요. 만료와 취소 확인까지 더하면 발급자가 게시한 키 말고는 아무도 신뢰하지 않는 검증기가 완성돼요. 이런 독립성이 바로 디지털 자격 증명을 PDF보다 가치 있게 만들어 줘요.

첫 번째 검증 가능한 자격 증명을 발급할 준비가 되셨나요? badges.ninja에서 무료로 시작하기 — 비주얼 디자이너, 공개 검증 페이지, PDF 인증서, Open Badge v2.0 출력. 신용카드는 필요 없어요.

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.

블로그로 돌아가기

관련 글