JSON Web Token (JWT)

A JWT is a compact string composed of three Base64Url-encoded parts separated by dots: Header.Payload.Signature. This structure is self-contained, meaning the payload contains all the required user claims, avoiding the need for repeated database queries during token validation.

• Header: Specifies the token type (JWT) and the signing algorithm (e.g., HS256, RS256).
• Payload: Contains the claims—statements about an entity (e.g., user ID, roles, expiration) and additional data.
• Signature: Ensures the token hasn't been tampered with by signing the encoded header and payload.

JWTs enable stateless authentication, a core feature for scalable APIs. The server does not need to store session state or token information. After issuing a signed JWT, the server can validate subsequent requests by verifying only the token's signature and expiry. This eliminates server-side session storage, reduces database load, and simplifies horizontal scaling across multiple servers.

• The client stores the JWT (typically in local storage or an HTTP-only cookie) and sends it with each request via the Authorization header.
• The server's validation logic is independent and repeatable for every request.

JWTs use a standardized set of registered claims defined in the RFC 7519 specification, providing interoperability. Developers can also include public claims or private claims to convey any necessary application-specific data.

Common Registered Claims:

• sub (subject): The user identifier.
• exp (expiration time): Unix timestamp for token expiry.
• iat (issued at): Timestamp of token creation.
• iss (issuer): Entity that created the token.

Example Payload:

jsonCopy
{
  "sub": "1234567890",
  "name": "John Doe",
  "iat": 1516239022,
  "admin": true
}

The admin field is a custom private claim.

The signature is the security cornerstone of a JWT. It is created by taking the encoded header, encoded payload, a secret (for HMAC) or a private key (for RSA/ECDSA), and signing them with the algorithm specified in the header. This process guarantees integrity—the recipient can verify that the token content has not been altered—and, when using asymmetric cryptography, authenticates the issuer.

• HMAC (Symmetric): Uses a single shared secret. Both issuer and verifier must know the secret.
• RSA/ECDSA (Asymmetric): Uses a private key to sign and a corresponding public key to verify. This is common for distributed systems.

JWTs come in two main cryptographic forms, defined by separate RFCs:

• JWS (JSON Web Signature): The most common type. It provides integrity via a signature but does not encrypt the payload. The payload is Base64Url-encoded but readable by anyone who inspects the token.
• JWE (JSON Web Encryption): Provides confidentiality by encrypting the payload. The result is a five-part structure. JWE is used when the token must carry sensitive data that should not be visible to clients or intermediaries.

Most authentication flows use signed (JWS), non-encrypted tokens, storing only non-sensitive identifiers in the payload.

While powerful, JWTs require careful implementation to avoid security pitfalls.

Key Risks & Mitigations:

• Token Storage: Storing tokens in localStorage is vulnerable to XSS attacks. Prefer HTTP-only cookies for web apps, though this introduces CSRF concerns.
• Algorithm Confusion: Always explicitly verify the signing algorithm on the server (alg in header) to prevent attackers from forcing a none algorithm or switching from asymmetric to symmetric.
• Short Expiry & Refresh Tokens: Use short-lived access tokens (minutes) paired with long-lived refresh tokens stored securely server-side to balance security and user experience.
• Signature Verification: Never decode a JWT without verifying its signature first.

JWTs provide a verifiable and tamper-proof container for transmitting data between two parties. Because they are digitally signed (using HMAC or RSA/ECDSA), the recipient can be confident the information has not been altered. This makes them suitable for scenarios like:

• Email verification links containing a user ID and expiry.
• Password reset tokens.
• Passing verified user context between internal microservices in a service mesh.

JWTs are well-suited for cross-origin scenarios and mobile applications. They can be securely stored in a mobile device's local storage or keychain and attached to requests. For web applications, they avoid the limitations and security concerns of cross-domain cookies. The token's self-contained nature means the client app does not need to manage complex session state, simplifying the architecture for native iOS/Android apps.

JWTs are a core component in Decentralized Identity (DID) systems like W3C Verifiable Credentials. A user's wallet signs a JWT with their private key, creating a cryptographic proof of identity that can be verified by any service without contacting a central authority. This enables self-sovereign identity and secure, portable logins across dApps.

• Structure: The JWT payload contains DID claims (e.g., iss, sub).
• Verification: The service verifies the signature against the user's public key on the blockchain or a DID document.

Blockchain oracles and node providers use JWT-based authentication to control and meter access to their APIs. A client (e.g., a smart contract developer) obtains a JWT from an auth service, which is then included in the header of requests to fetch off-chain data or submit transactions.

• Authorization: Tokens encode specific permissions (scopes) like read:data or write:tx.
• Security: Prevents unauthorized use of paid API endpoints and protects against Sybil attacks by tying requests to an identity.

dApp front-ends and wallet connectors use JWTs to manage user sessions without storing sensitive keys in browser storage. After a user signs a message with their wallet (e.g., Sign-In with Ethereum), the backend issues a short-lived JWT session token.

• User Experience: Allows persistent, authenticated sessions across browser refreshes.
• Security: The JWT contains a nonce and expiry, reducing the need for constant wallet pop-up signatures and mitigating replay attacks.

JWTs can act as verifiable attestations that are submitted to smart contracts. An off-chain trusted issuer (e.g., a KYC provider) signs a JWT containing a user's credential. The user then presents this JWT to a contract, which verifies the issuer's signature on-chain before granting access.

• Use Case: Gating access to a token sale based on a signed KYC JWT.
• Challenge: On-chain JWT verification requires libraries (like eth-jwt-verifier) to handle the JSON and signature parsing in Solidity or Vyper.

While both provide authentication, they operate in different layers.

• JWT: A standardized off-chain token format (RFC 7519) for representing claims. It's verified by checking a cryptographic signature, often using the same elliptic curve cryptography (e.g., ES256K) used by blockchains.
• Native Signature: A raw ECDSA signature (like secp256k1) on a specific message or transaction hash. It's verified directly by the blockchain's EVM or node.

JWTs often wrap a native signature as proof, creating a portable, claim-based credential.

Using JWTs in blockchain contexts introduces specific security requirements.

• Key Management: The private key used to sign the JWT must be secured with the same rigor as a blockchain wallet key.
• Expiry & Revocation: Implement short expiry times (exp) and consider mechanisms for token revocation, as JWTs are stateless.
• Signature Verification: Always verify the signature algorithm (alg header) to prevent algorithm confusion attacks. Reject tokens using none or weak algorithms.
• Claim Validation: Rigorously validate all standard claims (iss, aud, sub, exp) to ensure the token is intended for your service and is valid.

A JWT is a compact, URL-safe string composed of three Base64Url-encoded segments separated by dots.

• Header: Specifies the token type (JWT) and the signing algorithm (e.g., HS256 or RS256).
• Payload: Contains the claims—statements about an entity (e.g., user ID, iss issuer, exp expiry).
• Signature: Created by signing the encoded header and payload with a secret or private key to verify integrity.

Example decoded header: {"alg": "HS256", "typ": "JWT"}

JWS (RFC 7515) is the standard defining how to digitally sign or provide integrity protection for JWTs and other payloads. It is the mechanism that produces the signature part of a JWT.

• Specifies how to create the JWS Signature and the JWS Protected Header.
• Defines serialization formats: Compact Serialization (the common dot-separated string) and JSON Serialization.
• The alg (algorithm) header parameter in a JWT is defined by the JWS specification.

JWE (RFC 7516) is the standard for encrypting JWTs, providing confidentiality in addition to the integrity provided by JWS.

• Encrypts the payload so the contents are hidden from parties without the decryption key.
• Structure: JWE Header, Encrypted Key, Initialization Vector, Ciphertext, and Authentication Tag.
• While JWTs are often signed (JWS), they can also be encrypted (JWE) or signed-then-encrypted for full security.

JWK (RFC 7517) defines a JSON data structure for representing cryptographic keys used with JWS and JWE.

• A JWK Set (JWKS) is a JSON object containing an array of JWKs, often exposed via a public endpoint (e.g., /.well-known/jwks.json).
• Used in public key cryptography where services can fetch the public JWK to verify a JWT's signature.
• Contains key parameters like kty (key type), kid (key ID), n/e (RSA modulus/exponent), or crv/x/y (Elliptic Curve).

JWA (RFC 7518) is the registry and specification for the cryptographic algorithms used with JWS, JWE, and JWK.

• Defines identifiers for signature algorithms (HS256, RS256, ES256, EdDSA).
• Defines key management algorithms for JWE (e.g., RSA-OAEP, dir).
• Defines content encryption algorithms for JWE (e.g., A128GCM).
• Ensures interoperability by standardizing algorithm implementation details.