JWT-Auth
JwtAuth prüft JSON Web Tokens aus Authorization: Bearer <token> und
reicht die geprüften Claims an die Handler weiter, die es umschließt.
RS256, ES256 und HS256 werden mit WebCrypto geprüft — derselbe Code auf
Bun, Node und Deno, ohne Abhängigkeit — gegen Schlüssel, die du
konfigurierst, oder gegen das JWK-Set des Ausstellers.
import { JwtAuth, JwtAuthOptions, completeJson, get, jwtClaimsOf, path, withMiddleware } from 'actor-ts/http';
const jwtOptions = JwtAuthOptions.create() .withAlgorithms('RS256') .withIssuer('https://auth.example.com/') .withAudience('orders-api') .withJwksUrl('https://auth.example.com/.well-known/jwks.json');
const routes = withMiddleware(JwtAuth(jwtOptions), path('orders', get((request) => { const claims = jwtClaimsOf(request)!; return completeJson(200, { user: claims.sub }); })),);JwtAuth prüft; es stellt keine Tokens aus und macht kein
OpenID-Connect-Discovery — die URL des JWK-Sets wird ausdrücklich
übergeben. Die Optionen gehen auch als einfaches Objekt:
JwtAuth({ algorithms: ['RS256'], jwksUrl: '…' }).
Die Claims lesen
Abschnitt betitelt „Die Claims lesen“jwtClaimsOf(request) liefert die Claims des geprüften Tokens, oder
undefined auf einer Route, die kein JwtAuth umschließt. exp ist
immer vorhanden und eine Zahl; nbf, iat, iss, sub, aud und jti
sind so typisiert, wie die Middleware sie geprüft hat; jeder andere Claim
kommt so durch, wie der Aussteller ihn geschrieben hat. Das Objekt ist
eingefroren.
Die Claims reisen als Request-Attribut, nicht als Header. Ein Header ist Client-Eingabe — auf einer Route, die die Middleware nicht umschließt, kann ein Client jeden beliebigen Header schicken —, aber nichts, was ein Client schickt, kann zu einem Attribut werden. Deine eigene Middleware kann Handlern auf dieselbe Weise Werte übergeben:
import { RequestAttributeKey, attribute, withAttribute, type Middleware } from 'actor-ts/http';
const TENANT = RequestAttributeKey.of<string>('my-app.tenant');
const tenant: Middleware = (request, next) => next(withAttribute(request, TENANT, tenantOf(request)));
// in a handler inside it:const name = attribute(request, TENANT);withAttribute liefert eine Kopie und ändert den übergebenen Request nie.
Namen unter actor-ts. gehören dem Framework.
Schlüssel
Abschnitt betitelt „Schlüssel“Aus dem JWK-Set des Ausstellers
Abschnitt betitelt „Aus dem JWK-Set des Ausstellers“withJwksUrl(url) liest RSA- und P-256-Schlüssel aus dem veröffentlichten
Schlüsselset des Ausstellers:
- Bei Bedarf geholt — von der ersten Anfrage, die es braucht —, danach
jwksCacheTtlMslang (10 Minuten) vertraut. - Bei unbekannter Key-ID aufgefrischt, denn so sieht eine
Schlüsselrotation von hier aus — höchstens einmal je
jwksMinRefreshIntervalMs(30 s), und jede Anfrage, die den Schlüssel braucht, während ein Abruf läuft, wartet auf genau diesen einen Abruf. Ein Client, der zufällige Key-IDs schickt, kostet den Aussteller einen Abruf pro Intervall, nicht einen pro Anfrage. - Begrenzt: Jeder Abruf hat eine eigene Frist (
jwksTimeoutMs, 5 s) und eine eigene Größengrenze (jwksMaxResponseBytes, 64 KiB), nicht dieHttpClient-Defaults von 30 s und 8 MiB, und ein Redirect wird abgelehnt statt verfolgt. - Nur
https:— einfacheshttp:wird für einen Loopback-Host akzeptiert, für einen lokalen Aussteller in der Entwicklung. - Einmal laut je Ausfall: Ein Abruf, der scheitert, wird auf warn geloggt, mit der URL des Sets und der Ursache — Zugangsdaten in beiden maskiert, und eine abgelaufene Frist als solche benannt —, einmal je Ausfall, nicht einmal je abgelehnter Anfrage. Weitere gescheiterte Versuche desselben Ausfalls gehen auf debug, und der Abruf, der wieder gelingt, wird auf info geloggt.
Ein Eintrag wird übersprungen, wenn er kein RSA- oder P-256-Schlüssel ist
— vor allem ein oct-Schlüssel (HMAC) —, wenn sein eigenes alg, use
oder key_ops sagt, dass er kein RS256- oder ES256-Signaturschlüssel ist,
wenn er private Bestandteile trägt oder wenn er ein RSA-Schlüssel unter
2048 Bit oder mit einem öffentlichen Exponenten kleiner als 3 oder gerade
ist (RFC 8017 §3.1). Jeder übersprungene Eintrag wird auf debug geloggt, mit
seiner Position, seiner kid und dem Grund — so lässt sich ein
veröffentlichter Schlüssel, der nie etwas verifiziert, ohne Debugger
erklären.
Konfigurierte Schlüssel
Abschnitt betitelt „Konfigurierte Schlüssel“const jwtOptions = JwtAuthOptions.create() .withAlgorithms('RS256', 'HS256') .withPublicKeys({ keyId: 'main', algorithm: 'RS256', key: process.env.JWT_PUBLIC_KEY_PEM! }) .withSecrets({ keyId: 'internal', secret: process.env.JWT_HMAC_SECRET! });publicKeysnehmen einen JWK (ktyRSA oder EC aufP-256) oder einen PEM-Block-----BEGIN PUBLIC KEY-----, jeweils an RS256 oder ES256 gebunden. Ein RSA-Schlüssel braucht mindestens 2048 Bit und einen ungeraden öffentlichen Exponenten von mindestens 3: Ein JWK, desseneetwas anderes ist, wird beim Aufruf vonJwtAuth(...)abgelehnt, mit seinem Feld, und ein PEM-Schlüssel, der das nicht erfüllt, lässt jede Anfrage als Serverfehler scheitern, wie jeder Schlüssel, der sich nicht importieren lässt.secretssind nur HS256, mindestens 32 Byte. Sie sind die einzige Quelle für HMAC-Schlüssel: Ein JWK-Set wird nie nach einem gelesen.- Statische Schlüssel und ein JWK-Set lassen sich kombinieren. Ein konfigurierter Schlüssel antwortet für seine eigene Key-ID, ohne das Set zu fragen, und ein HS256-Token fragt es nie: Ein Set enthält keinen HMAC-Schlüssel.
Ein Token, das eine Key-ID nennt, wird mit diesem Schlüssel geprüft. Ein Token ohne Key-ID wird mit dem einen Schlüssel seines Algorithmus geprüft und abgelehnt, wenn es mehrere gibt — jeden durchzuprobieren würde ein gefälschtes Token eine Prüfung pro Schlüssel kosten lassen.
Was geprüft wird, der Reihe nach
Abschnitt betitelt „Was geprüft wird, der Reihe nach“- Das Token besteht aus drei kanonischen base64url-Segmenten und ist
nicht größer als
maxTokenBytes(8 KiB) — geprüft, bevor irgendetwas dekodiert wird. algist genau einer deralgorithms.critwird abgelehnt.jku,x5u,jwkundx5cwerden nie gelesen.- Der Schlüssel wird wie oben gefunden, und die Signatur hat genau die Länge dieses Schlüssels.
- Die Signatur verifiziert, mit dem Algorithmus, an den der Schlüssel beim Import gebunden wurde.
- Die Claims:
expist Pflicht;expundnbfwerden mitclockSkewMs(30 s) Toleranz geprüft;issundaudwerden exakt verglichen.
Antworten
Abschnitt betitelt „Antworten“| Situation | Status | WWW-Authenticate |
|---|---|---|
kein Authorization-Header oder ein anderes Schema | 401 | Bearer realm="actor-ts" |
| ein Token, das eine Prüfung nicht besteht | 401 | Bearer realm="actor-ts", error="invalid_token" |
| ein Token braucht das JWK-Set, und das lässt sich nicht abrufen | 503, einmal je Ausfall auf warn geloggt | — |
| ein konfigurierter Schlüssel lässt sich nicht importieren | 500, geloggt | — |
Die 401-Bodies nennen die Prüfung, die fehlgeschlagen ist —
token expired, token audience not accepted und so weiter — und
wiederholen nie das Token. Ein 503 bedeutet, dass das Token nie beurteilt
wurde: Ein 401 würde einen Client ein Token wegwerfen lassen, das
vielleicht in Ordnung ist. Das Set braucht nur ein RS256- oder
ES256-Token, das keinen konfigurierten Schlüssel nennt — ein Token ohne
Key-ID eingeschlossen. Ein HS256-Token oder eines, das einen
konfigurierten Schlüssel nennt, wird ohne das Set beantwortet: Es wartet nie
auf einen Abruf, und der Ausfall des Sets erreicht es nie.
Konfiguration
Abschnitt betitelt „Konfiguration“| Builder-Methode | Feld | Zweck |
|---|---|---|
withAlgorithms(...) | algorithms | Pflicht. Die akzeptierten Algorithmen: RS256, ES256, HS256. |
withIssuer(...) | issuer | Akzeptierte iss-Werte. Nicht gesetzt: nicht geprüft. |
withAudience(...) | audience | Akzeptierte aud-Werte. Nicht gesetzt: Ein Token, das irgendeine Audience nennt, wird abgelehnt. |
withClockSkewMs(ms) | clockSkewMs | Toleranz für exp / nbf. Default 30 s, höchstens 5 min. |
withPublicKeys(...) | publicKeys | Statische RS256-/ES256-Schlüssel, JWK oder PEM. |
withSecrets(...) | secrets | Statische HS256-Secrets, mindestens 32 Byte. |
withJwksUrl(url) | jwksUrl | Das JWK-Set des Ausstellers. |
withJwksTimeoutMs(ms) | jwksTimeoutMs | Frist für einen Abruf. Default 5 s, höchstens 60 s. |
withJwksMaxResponseBytes(n) | jwksMaxResponseBytes | Größtes akzeptiertes Schlüsselset. Default 64 KiB. |
withJwksCacheTtlMs(ms) | jwksCacheTtlMs | Wie lange einem abgerufenen Set vertraut wird. Default 10 min. |
withJwksMinRefreshIntervalMs(ms) | jwksMinRefreshIntervalMs | Mindestabstand zwischen zwei Abrufen. Default 30 s. |
withMaxTokenBytes(n) | maxTokenBytes | Größtes akzeptiertes Token. Default 8 KiB. |
withRealm(name) | realm | Realm im WWW-Authenticate. Default 'actor-ts'. |
withClock(clock) | clock | Woher die Zeit gelesen wird — mit system.clock steuert ein ManualScheduler sie. |
withLogger(logger) | logger | Wohin die Middleware meldet, was keine Antwort zeigt — einen Ausfall des JWK-Sets auf warn, einen übersprungenen Eintrag auf debug. Default: die Konsole, ab warn; mit system.log landet es beim Logging der Anwendung. |
Die Optionen werden geprüft, wenn JwtAuth(...) aufgerufen wird, und eine
Konfiguration, die nie ein Token verifizieren könnte, scheitert dort, mit
Namen: ein erlaubter Algorithmus ohne Schlüssel, der ihn prüft, ein
Schlüssel, den kein erlaubter Algorithmus nutzt, ein RSA-JWK, dessen
öffentlicher Exponent kleiner als 3 oder gerade ist, ein kurzes oder wie
PEM aussehendes Secret, eine http:-URL für das JWK-Set. Einen
HOCON-Block gibt es noch nicht: Alles kommt aus diesen Optionen.
Fallstricke
Abschnitt betitelt „Fallstricke“So wird JWT-Prüfung gewöhnlich kaputt gemacht. Jeder dieser Fälle ist hier geschlossen, und jeder hat einen Test.
alg: none. Ein unsigniertes Token wird von einem Prüfer akzeptiert, der dem Token seinen Algorithmus glaubt. Hier mussalggenau einer deralgorithmssein, und die könnennonenicht enthalten — in keiner Schreibweise.- Verwechslung von RS256 und HS256. Einem Prüfer, der „den Schlüssel“
für den Algorithmus importiert, den das Token nennt, lässt sich ein
HS256-Token unterschieben, das mit dem öffentlichen RSA-Schlüssel als
HMAC-Secret signiert ist. Hier wird jeder Schlüssel einmal importiert,
für einen Algorithmus, und HMAC-Schlüssel kommen nur aus
secrets; ein Secret, das wie ein PEM-Block aussieht, wird abgelehnt. - Schlüssel aus dem Token.
jku,x5u,jwkundx5cwürden das Token seinen eigenen Prüfer wählen lassen. Sie werden nie gelesen. - Keine Audience-Prüfung. Ein Token, das dein Aussteller für einen
anderen Dienst ausgestellt hat, ist ein gültiges Token. Setze
audience; ohne sie wird ein Token, das irgendeine Audience nennt, abgelehnt (RFC 7519 §4.1.3) statt durchgewunken. - Kein Ablauf. Ein Token ohne
expwäre für immer gültig, also wird es abgelehnt. HalteclockSkewMsklein: Es verlängert die Lebensdauer jedes Tokens. - Veraltete Schlüssel.
jwksCacheTtlMsist die Zeit, die ein Schlüssel, den der Aussteller zurückgezogen hat, hier weiter verifiziert. Lässt sich das Set danach nicht abrufen, wird eine Anfrage, die es braucht, mit503abgelehnt — nie gegen das alte Set geprüft. - DER-kodierte ES256-Signaturen. JWS will das rohe 64-Byte-Paar
r || s; die DER-Form, die manche Werkzeuge erzeugen, wird als fehlerhaft abgelehnt. - Ein öffentlicher RSA-Exponent von 1. Die Prüfung potenziert die Signatur mit dem öffentlichen Exponenten, also ist bei einem Exponenten von 1 die „Signatur“, die ein Schlüssel annimmt, der kodierte Hash des Tokens selbst — kein privater Schlüssel nötig, und das WebCrypto mindestens einer Runtime verifiziert mit so einem Schlüssel. Ein Exponent kleiner als 3 oder gerade (RFC 8017 §3.1) wird auf jedem Weg abgelehnt: ein konfigurierter JWK, wenn die Middleware gebaut wird, jeder RSA-Schlüssel, wenn er importiert wird.
- Schwache HMAC-Secrets. HS256 braucht ein Secret, das mindestens so lang ist wie sein Hash, 32 Byte. Nimm lieber RS256 oder ES256, wenn mehr als eine Partei prüft: Wer ein HS256-Token prüfen kann, kann auch eines ausstellen.
Wie weiter
Abschnitt betitelt „Wie weiter“- Bearer-Token — ein vorab geteiltes Token für Operator-Endpoints, wenn es keinen Aussteller gibt.
- Sicherheit — wo Auth im Stack sitzt.
- WebSocket — was Middleware beim Upgrade tut.
