{"canonical_url":"https://engineer.company/glossary/jwt/","content_markdown":"# JWT\n\n## What it is\n\nA JWT is a short string that carries a set of statements from one party to\nanother in a form the receiver can check. The letters stand for JSON Web Token.\nRFC 7519 defined it in May 2015 as a compact way of representing claims that is\nsafe to put in a URL, and notes that the name is pronounced \"jot\". A claim is a\nname and a value asserted about a subject: `\"sub\": \"24400320\"` says whom the\ntoken is about, `\"exp\": 1300819380` says when it stops being valid.\n\nOn the wire a JWT is a series of base64url strings joined by dots. A signed one\nhas three: a header that names the algorithm, a payload that holds the claims,\nand a signature computed over the first two. An encrypted one has five, and its\nclaims cannot be read without the key. RFC 7519 does none of the cryptography\nitself. It relies on JSON Web Signature (RFC 7515) for tokens that are signed or\nprotected with a message authentication code, and on JSON Web Encryption (RFC\n7516) for tokens that are encrypted; the algorithms are listed in RFC 7518 and\nthe keys can be published in the JSON Web Key format of RFC 7517.\n\n`HS256` is an HMAC with SHA-256: one shared secret both creates and checks the\ntoken, so every service that can verify it can also mint it. `RS256` and `ES256`\nuse a key pair: the issuer signs with a private key and everyone else verifies\nwith the public one, which can be handed out freely. RFC 7519 makes only `HS256`\nand the unsigned `none` mandatory to implement, and recommends `RS256` and\n`ES256`.\n\nSection 4.1 registers seven claim names: `iss` (issuer), `sub` (subject), `aud`\n(audience), `exp` (expiration time), `nbf` (not before), `iat` (issued at) and\n`jti` (JWT ID, a unique identifier that can be used to stop a token being\nreplayed). They are three letters long because the format is meant to be\ncompact, and every one of them is optional. Which claims a token must carry is\nleft to the application that uses it. Beyond the registered set, anyone can\ndefine public claims, either registered with IANA or given a name that cannot\ncollide with anyone else's, such as a URL, or private claims agreed between two\nparties.\n\n## Why it matters\n\nThe point of a JWT is that the receiver can check it on its own. With the\nissuer's key and a clock, a service can tell whether the token is genuine, whom\nit is for and whether it is still valid, without a database lookup and without\ncalling the issuer. RFC 9068 (October 2021) records that many commercial OAuth\nimplementations issue access tokens that resource servers parse and validate\ndirectly, a pattern common where the server that issues tokens and the one that\naccepts them are separated by some boundary, and that many of them use JWT. It\nthen standardised the layout, so that such tokens work across vendors.\n\nIt is also the format behind OpenID Connect: every ID token is a JWT addressed\nto the application that asked for it. The provider must sign it unless both\nconditions for using `alg` set to `none` hold: the response type returns no ID\ntoken from the Authorization Endpoint, as in the Authorization Code Flow, and\nthe client explicitly requested `none` at registration. When the media\ntype `application/jwt` was registered in 2015, the registration already named\nOpenID Connect, Salesforce, Google, Android, Windows Azure and Amazon Web\nServices among its users.\n\nRFC 7519 aims the format at space-constrained places including the Authorization\nheader and parameters in a URI's query, which is why the claim names are short\nand the encoding passes through a URL unescaped.\n\nThe same property that makes a JWT cheap to check makes it hard to take back. A\nreceiver that verifies the signature and the clock will accept the token until\n`exp`, whatever has happened to the account in the meantime.\n\n## What it looks like in practice\n\nRFC 7519 works through a complete example. The header declares that the object\nis a JWT and that it is protected with HMAC SHA-256:\n\n```text\n{\"typ\":\"JWT\",\n \"alg\":\"HS256\"}\n```\n\nThe claims name an issuer, an expiry time and one public claim whose name is a\nURL, so that it cannot clash with a claim anyone else defines:\n\n```text\n{\"iss\":\"joe\",\n \"exp\":1300819380,\n \"http://example.com/is_root\":true}\n```\n\nEach part is encoded with base64url, the HMAC is computed over the header and\npayload joined by a dot, and the three results are joined into one string. The\nRFC prints it with line breaks for display only:\n\n```text\neyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1NiJ9\n.\neyJpc3MiOiJqb2UiLA0KICJleHAiOjEzMDA4MTkzODAsDQogImh0dHA6Ly9leGFt\ncGxlLmNvbS9pc19yb290Ijp0cnVlfQ\n.\ndBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk\n```\n\nThree things follow from this example. First, the claims are readable by anyone\nwho holds the token: base64url is an encoding, so decoding the middle part gives\nthe JSON back without any key. Second, the signature covers the encoded strings\nexactly as they were sent. The RFC's header contains a CRLF line break and a\nleading space, and it lists the exact bytes for that reason; formatting the JSON\nmore neatly and encoding it again would produce a different string, and the\nsignature would no longer match. The key for this example is printed in Appendix\nA.1 of RFC 7515, and with it the signature verifies. Third, the token has long\nexpired: `1300819380` seconds after 1 January 1970 is 22 March 2011 at 18:43\nUTC, so a correct validator rejects it today.\n\nA receiver that gets a token like this runs a fixed set of checks before it\nreads a single claim. It splits the string at the dots, decodes the header and\nconfirms that it is valid JSON containing only parameters and values whose\nsyntax and meaning it understands and supports, or that are explicitly specified\nto be ignored when unknown. It\ncompares `alg` with the algorithms it has decided to accept for this issuer and\nkey: RFC 7519 is explicit that this is an application decision, and that a token\nshould be rejected if its algorithm is unacceptable even when the signature is\nvalid. It verifies the signature with a key that belongs to the issuer. Then it\nchecks the claims: `iss` must be an issuer it trusts, `aud` must name the\nreceiver itself, the current time must be before `exp`, allowing a few minutes\nat most for clock skew, and after `nbf` if that claim is present. Only then does\nit act on the claims.\n\nA JWT access token under RFC 9068 shows what a real profile adds. Its header in\nthat RFC reads `{\"typ\":\"at+JWT\",\"alg\":\"RS256\",\"kid\":\"RjEwOwOA\"}`: an explicit\ntype, an asymmetric algorithm, and the ID of the key in the issuer's published\nset. The profile makes `iss`, `exp`, `aud`, `sub`, `client_id`, `iat` and `jti`\nmandatory, and a resource server must check that `typ` is `at+jwt` or\n`application/at+jwt` and reject other types. These media type and subtype names\nare case-insensitive; `at+JWT` in the example is an equivalent spelling.\n\nThe claims inside a token are a snapshot taken when it was signed, so anything\nthat can change before `exp` is better decided on the server. One of this site's\nprojects,\n[hardening an application at every layer](/portfolio/hardened-the-application-with-nonce-based-csp/),\nre-checks the entitlements (tier, role, organisation and ship scoping) on the\nserver on every request and treats the gates in the browser as UX only.\n\n## Where it goes wrong\n\n**The token picks its own algorithm.** The `alg` header is there for\nflexibility, and RFC 8725 describes how some libraries trusted it too far. An\nattacker could change it to `none` and the library would accept the token with\nno signature at all; or change `RS256` to `HS256`, and the library would check\nan HMAC using the issuer's public RSA key as the shared secret, a key the\nattacker can download. Configure the library with the algorithms you accept,\nuse each key with exactly one algorithm, and reject `none` outright.\n\n**The HMAC secret is a password.** A token signed with `HS256` under a short,\nmemorable secret can be attacked offline: anyone holding a single token can try\nguesses against it at their own pace, without touching your server. RFC 8725\nforbids using a human-memorable password directly as an HMAC key, and RFC 7518\nrequires an `HS256` key of at least 256 bits. Generate the key from a\ncryptographic random source, keep it in a secret store, and prefer a key pair\nwhen many services only need to verify.\n\n**The signature checks out, so everything is believed.** A valid signature\nproves who issued the token, not whom it was for. If one issuer serves several\nservices and the receiver skips `aud`, a token legitimately sent to one service\ncan be replayed against another. RFC 8725 calls this substitution and requires\nany receiver of such tokens to validate the audience and reject a token that\nlacks one. Check `aud` against your own identifier, and check that the signing\nkey belongs to the issuer named in `iss`.\n\n**One kind of token passes for another.** An ID token, an access token and a\nsecurity event token from the same issuer can look much alike, and a receiver\nthat only checks signature and issuer may accept the wrong kind. RFC 8725 calls\nthis cross-JWT confusion and recommends explicit typing through the `typ`\nheader; RFC 9068 applies it with `at+jwt`. Give each kind of token its own type\nor audience, and write the validation rules so that each kind fails the others'\nchecks.\n\n**The header chooses the key.** The `kid` header says which key to use, and\n`jku` and `x5u` can point to a URL from which to fetch it. All of them arrive\nfrom the sender. A `kid` passed unchecked into a database query or a directory\nlookup becomes a way into that system, and a server that follows any URL it is\ngiven in `jku` or `x5u` can be made to send requests wherever the sender\nchooses. Look `kid` up only among keys you already hold, and fetch keys only\nfrom an allow-list of locations, such as the issuer's published `jwks_uri`.\n\n**Anyone can read the payload.** A signed JWT protects its claims against\ntampering, not against reading, and it often travels through browsers, logs and\nproxies. RFC 7519 notes that a JWT may contain privacy-sensitive information and\nthat the simplest protection is to leave it out; otherwise the token should be\nencrypted, or at least sent only over TLS. RFC 9068 adds that a client must not\ninspect an access token at all, since the issuer may change its format. Put\nidentifiers in the token, not personal data, and encrypt when the content itself\nmust stay private.\n\n## Further reading\n\n- [RFC 7519: JSON Web Token (JWT)](https://www.rfc-editor.org/rfc/rfc7519) — the\n  format itself, with the registered claims, the worked example and the\n  validation steps.\n- [RFC 7515: JSON Web Signature (JWS)](https://www.rfc-editor.org/rfc/rfc7515) —\n  how the header, payload and signature are encoded and joined, and the key used\n  in the example above.\n- [RFC 8725: JSON Web Token Best Current Practices](https://www.rfc-editor.org/rfc/rfc8725)\n  — the known attacks on JWT and the rules for libraries and applications that\n  prevent them.\n- [RFC 7518: JSON Web Algorithms (JWA)](https://www.rfc-editor.org/rfc/rfc7518)\n  — the algorithm names used in `alg`, with the minimum key size for each HMAC.\n- [RFC 9068: JWT Profile for OAuth 2.0 Access Tokens](https://www.rfc-editor.org/rfc/rfc9068)\n  — the standard layout for JWT access tokens and the checks a resource server\n  must run.\n\n\u003chttps://engineer.company/glossary/jwt/\u003e\n","date_modified":"2026-11-08T11:12:58Z","description":"How a JWT carries signed claims in three dot-separated parts, the checks a server must run before it believes one, and six ways it goes wrong.","formats":{"gemtext":"https://engineer.company/glossary/jwt/index.gmi","gopher":"https://engineer.company/glossary/jwt/gophermap","html":"https://engineer.company/glossary/jwt/","json":"https://engineer.company/glossary/jwt/index.json","markdown":"https://engineer.company/glossary/jwt/index.md","pdf":"https://engineer.company/glossary/jwt/index.pdf"},"kind":"page","language":"en","title":"What is JWT?","url":"https://engineer.company/glossary/jwt/","version":1}