Hash Web Token (HWT)

Offizielle Dokumentation Issues Diskussionen

Ein zustandsloses, netzwerknatives Token-Protokoll für domänenübergreifende Delegation.

Tokens werden von einer ausstellenden Origin signiert, sind von jeder Partei verifizierbar, die die Domain des Issuers (Aussteller) erreichen kann, und tragen Autorisierungskontext entweder direkt oder als Referenz.

Status: Draft v0.7.

Was HWT tut

Was HWT nicht adressiert

Token-Format

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

Sechs durch Punkte getrennte Felder. Der Punkt ist der Feldtrenner und DARF NICHT in key-id, format oder im Top-Level-Namen erscheinen.

format deklariert den Codec. j (JSON) ist der einzige erforderliche Codec. Weitere Community-Codecs sind in CONVENTIONS.md dokumentiert.

Ablaufzeit ist strukturell – ein Token, der seinen expires-Wert überschritten hat, ist bedingungslos ungültig, unabhängig von der Signaturvalidität.

Beispiel einer Delegation Chain

Drei Hops: ein Benutzer bei einem Identity-Provider → ein Orchestrierungsagent → ein Worker-Service → das finale API-Ziel.

Root-Token (gehalten vom Benutzer, ausgestellt von auth.example.com):

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

Zwischentoken (ausgestellt von agent.example.com für den Worker):

{
  "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" }
  ]
}

Finaler abgeleiteter Token (ausgestellt von worker.example.com für die Ziel-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" }
  ]
}

Die Ziel-API verifiziert die Signatur des finalen Tokens gegen die veröffentlichten Schlüssel von worker.example.com, bestätigt, dass die del-Kette strukturell intakt ist (sie ist durch die äußere Signatur abgedeckt), und kann die vollständige Autorisierungsherkunft bis zum ursprünglichen Benutzer zurückverfolgen. Die Autorisierung wurde bei keinem Hop eskaliert – durchgehend roles: ["editor"].

Key Discovery

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

JWKS-Format (RFC 7517). alg pro Schlüssel ist obligatorisch. Mehrere gleichzeitige Schlüssel für Rotation unterstützt.

Origin-Metadaten

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

Deklariert die Issuer-URL, Protokollversion, unterstützte authz-Schemata, Audience-Konfiguration, Delegationstiefengrenze und Endpunkt-URLs.

Vertrauensmodell

Der Vertrauensanker ist die Domain des Issuers, keine zentrale Autorität. Die Verifizierung setzt voraus, dass DNS korrekt auflöst und TLS zum well-known-Endpunkt des Issuers verbindet. Die empfohlene Produktionskonfiguration ist eine vorab registrierte Issuer-allowlist – Verifier lehnen Tokens von Issuern ab, die nicht in der Liste stehen, und wandeln Key Discovery in eine lokale Cache-Abfrage ohne Laufzeit-DNS-Abhängigkeit um.

Dokumentation

Implementierungen

Referenzbibliothek

Demos

Lizenz

Apache License 2.0