Understanding JWT Claims and Token Renewal Strategies

JWT (JSON Web Token) carries a JSON payload that contains a set of statements called claims, which represent the data to be transmitted.

The JWT standard defines several standard claims:

iss (Issuer) : the entity that issued the token.

sub (Subject) : the token's owner.

aud (Audience) : the intended recipient.

exp (Expiration time) : when the token expires.

nbf (Not Before) : when the token becomes valid.

iat (Issued at) : the issuance time.

jti (JWT ID) : a unique identifier for the token.

In addition to these, custom claims can be added. The following Java snippet (using the Auth0 library) creates a token with an expiration time and a custom claim:

String token = JWT.create()
    .withIssuer(ISSUER)
    .withIssuedAt(new Date(currentTime)) // signing time
    .withExpiresAt(new Date(currentTime + EXPIRES_IN * 1000 * 60)) // expiration timestamp
    .withClaim("username", username) // custom parameter
    .sign(Algorithm.HMAC256(user.getPassword()));

The methods used are:

withIssuer() sets the issuer.

withIssuedAt() sets the issuance time.

withExpiresAt() sets the expiration timestamp (duration defined by EXPIRES_IN in seconds).

withClaim() adds a custom claim.

When a token expires, the client must obtain a new one, which can be handled through various renewal schemes.

Single‑Token Renewal Scheme

1. Set token expiration (e.g., 15 minutes). 2. Front‑end sends a request; back‑end checks token validity. 3. If expired, front‑end requests a refresh; back‑end returns a new token. 4. Front‑end uses the new token for subsequent requests. 5. To force re‑login after a longer period (e.g., 72 hours), the back‑end records the last login time and rejects refresh requests that exceed this interval. Additional controls can limit the number of refreshes (e.g., max 50).

Double‑Token Renewal Scheme

1. After successful login, the server returns an access_token and a refresh_token . 2. The client uses the access_token for API calls; if it expires, the client sends the refresh_token to obtain a new access_token . 3. The server validates the refresh_token ; if it is also expired, the client must re‑authenticate. 4. Upon receiving a new access_token , the client retries the original request. 5. Logging out or changing the password invalidates both tokens.

WeChat web authorization also follows a double‑token model based on OAuth2.0: a short‑lived access_token (2 hours) and a long‑lived refresh_token (30 days). The user first obtains a code (valid for 10 minutes) which can be exchanged once for the tokens.

Another implementation option is to store tokens in Redis with an expiration time; the absence of a token key indicates expiration.

Overall, choosing the appropriate renewal strategy depends on security requirements, user experience, and system constraints.