JWT authentication for a stateless API

A JSON Web Token is three base64url-encoded parts joined by dots: header.payload.signature. The header names the signing algorithm ({"alg":"HS256","typ":"JWT"}); the payload carries claims such as sub (subject), exp (expiry, seconds since the epoch), nbf (not before), iss (issuer), aud (audience) and scope; the signature is computed over the first two parts.

The payload is encoded, not encrypted. Anyone holding the token can read every claim, so a JWT must never carry a password or other secret. What the signature gives you is integrity: change one character of the header or payload and the signature no longer matches.

1import javax.crypto.Mac;2import javax.crypto.spec.SecretKeySpec;3import java.nio.charset.StandardCharsets;4import java.security.MessageDigest;5import java.util.*;6 7public class Solution {8    static final Base64.Encoder ENC = Base64.getUrlEncoder().withoutPadding();9    static final byte[] SECRET = "demo-secret-for-lessons-only-32b!".getBytes(StandardCharsets.UTF_8);10 11    static String b64(String json) { return ENC.encodeToString(json.getBytes(StandardCharsets.UTF_8)); }12 13    static String hmac(String data) throws Exception {14        Mac mac = Mac.getInstance("HmacSHA256");15        mac.init(new SecretKeySpec(SECRET, "HmacSHA256"));16        return ENC.encodeToString(mac.doFinal(data.getBytes(StandardCharsets.UTF_8)));17    }18 19    static boolean verify(String token) throws Exception {20        String[] p = token.split("\\.", -1);21        String expected = hmac(p[0] + "." + p[1]);22        return MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8), p[2].getBytes(StandardCharsets.UTF_8));23    }24 25    public static List<String> run() throws Exception {26        String header = b64("{\"alg\":\"HS256\",\"typ\":\"JWT\"}");27        String payload = b64("{\"sub\":\"ana\",\"role\":\"user\"}");28        String token = header + "." + payload + "." + hmac(header + "." + payload);29 30        String decoded = new String(Base64.getUrlDecoder().decode(token.split("\\.")[1]), StandardCharsets.UTF_8);31        String forgedPayload = b64("{\"sub\":\"ana\",\"role\":\"admin\"}");32        String forged = header + "." + forgedPayload + "." + token.split("\\.")[2];33 34        return List.of(35            "token: " + token,36            "anyone can read: " + decoded,37            "original verifies: " + verify(token),38            "role changed to admin verifies: " + verify(forged));39    }40}

HS256 versus RS256

HS256 is an HMAC with a shared secret: whoever can verify a token can also mint one, so the secret must stay inside services you fully trust. RS256 and ES256 sign with a private key held only by the authorization server; resource servers verify with the public key, usually fetched from the issuer's JWK Set endpoint. For anything with more than one service, asymmetric keys are the norm.

Validation order

A token is checked in an order that never trusts unverified data:

1. It has exactly three parts that decode.
2. Its algorithm is one the server expects. A server that lets the token choose — including "alg":"none", which means "unsigned" — accepts forgeries. Pin the algorithm.
3. The signature is valid, compared in constant time.
4. Only now are the claims trusted: exp and nbf against the clock (with a small allowance for clock skew), then iss and aud.

Checking exp before the signature is not a security hole by itself, but it means reasoning about claims an attacker wrote.

Spring Boot as a resource server

With spring-boot-starter-oauth2-resource-server and

spring.security.oauth2.resourceserver.jwt.issuer-uri=https://auth.example.com

Boot configures a JwtDecoder that discovers the issuer's keys, verifies signatures, and validates / (with 60 seconds of clock skew by default) and the issuer. A reads , and the (or ) claim becomes authorities prefixed with , so a token with passes .