Hash Web Token (HWT)

공식 문서 이슈 토론

도메인 간 위임(cross-domain delegation)을 위한 상태 비저장(stateless), 네트워크 네이티브 token 프로토콜입니다.

Token은 발급자(issuer) 오리진이 서명하고, 발급자의 도메인에 접근할 수 있는 누구나 검증할 수 있으며, 인가 컨텍스트를 직접 또는 참조 형식으로 담습니다.

상태: 초안 v0.7.

HWT가 하는 것

HWT가 다루지 않는 것

Token 형식

hwt.signature.key-id.expires-unix-seconds.format.payload

점으로 구분된 여섯 개의 필드. 점은 필드 구분자이며 key-id, format, 최상위 이름에는 포함되어서는 안 됩니다.

format은 codec을 선언합니다. j(JSON)는 유일한 필수 codec입니다. 추가 커뮤니티 codec은 CONVENTIONS.md에 기술되어 있습니다.

만료는 구조적입니다 — expires 값을 지난 token은 서명 유효성에 관계없이 무조건 무효입니다.

위임 체인 예시

세 단계: 신원 공급자의 사용자 → 오케스트레이션 에이전트 → 워커 서비스 → 최종 API 대상.

루트 token (auth.example.com이 발급, 사용자 보유):

{
  "iss": "https://auth.example.com",
  "sub": "user:4503599627370495",
  "tid": "root-a1b2",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] }
}

중간 token (agent.example.com이 워커를 위해 발급):

{
  "iss": "https://agent.example.com",
  "sub": "svc:orchestrator",
  "aud": "https://worker.example.com",
  "tid": "mid-c3d4",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com", "sub": "user:4503599627370495", "tid": "root-a1b2" }
  ]
}

최종 파생 token (worker.example.com이 대상 API를 위해 발급):

{
  "iss": "https://worker.example.com",
  "sub": "svc:worker",
  "aud": "https://api.target.example.com",
  "tid": "final-e5f6",
  "authz": { "scheme": "RBAC/1.0.2", "roles": ["editor"] },
  "del": [
    { "iss": "https://auth.example.com", "sub": "user:4503599627370495", "tid": "root-a1b2" },
    { "iss": "https://agent.example.com", "sub": "svc:orchestrator", "tid": "mid-c3d4" }
  ]
}

대상 API는 worker.example.com의 공개 키로 최종 token의 서명을 검증하고, del 체인이 구조적으로 무결한지 확인하며(외부 서명으로 보호됨), 전체 인가 출처를 원래 사용자까지 추적할 수 있습니다. 어느 단계에서도 인가는 상승되지 않았습니다 — 전 구간에 걸쳐 roles: ["editor"].

키 발견

GET https://{issuer-domain}/.well-known/hwt-keys.json

JWKS 형식(RFC 7517). 키별 alg 지정이 필수입니다. 교체를 위한 여러 동시 키를 지원합니다.

오리진 메타데이터

GET https://{issuer-domain}/.well-known/hwt.json

발급자 URL, 프로토콜 버전, 지원하는 authz 스키마, 오디언스 구성, 위임 깊이 한도, 엔드포인트 URL을 선언합니다.

신뢰 모델

신뢰 앵커는 중앙 기관이 아닌 발급자의 도메인입니다. 검증은 DNS가 올바르게 해석되고 TLS가 발급자의 well-known 엔드포인트에 연결되는 것에 의존합니다. 권장되는 프로덕션 방식은 사전 등록된 발급자 allowlist입니다 — 검증자는 목록에 없는 발급자의 token을 거부하여, 키 발견을 런타임 DNS 의존성 없이 로컬 캐시 조회로 전환합니다.

문서

구현체

참조 라이브러리

데모

라이선스

Apache License 2.0