{jwtdecode:key:add_validity}

Description

Reads the Authorization request header, validates a Bearer JWT against the secret key, and returns the authenticated user id on success or an empty string on failure. The header must be of the form "Authorization: Bearer TOKEN"; the token must be a JWT signed with HS256 using the same secret key passed to jwtencode. On any failure - no header, a non-Bearer scheme, a bad signature, an expired or malformed token - it returns empty, so a non-empty result means the request is authenticated. The returned value is the user id stored in the token sub claim. The optional add_validity is a revocation check for Reader Management users (long id): it is an alias or AA code evaluated for that user and compared to the aaValid claim baked into the token; if they differ the token is rejected. This is request-dependent, so during normal page rendering (no Authorization header) it returns empty. Some Apache or mod_fcgid setups drop the Authorization header; FcgidPassHeader Authorization in the server config restores it. Use jwtencode to mint the token that jwtdecode verifies.

Parameters

key required

The secret signing key, the same key that was passed to jwtencode when the token was created. jwtdecode verifies the Bearer token against it. Required - an empty key always returns an empty string.

add_validity optional

Optional revocation check. An alias or AA expression evaluated for the authenticated user; jwtdecode compares the result against the aaValid claim stored in the token (set by jwtencode) and rejects the token if they differ. This lets you invalidate older tokens - for example by updating a logout-time field on logout. Works only for Reader Management users (those with a long id); for other users this extra check is skipped.

Examples

test[{jwtdecode:}]

Expected[]

Actual[]

With no secret key there is nothing to verify against, so the command returns an empty string. The square brackets only frame the empty result.

test[{jwtdecode:my-secret-key}]

Expected[]

Actual[]

A key is given, but this page request carries no Authorization Bearer header, so there is no token to check and the result is empty. This is the everyday case on a normal page render - jwtdecode only returns a user id when the request actually carries a valid token.

virtual{jwtdecode:my-secret-key}

Expected(the authenticated user id, e.g. 1234, or empty if no valid token)

The core use. When the request carries a valid Authorization Bearer token signed with this key, jwtdecode returns the user id stored in the token (its sub claim). Here that would be the id of the signed-in reader; with no or an invalid token it returns empty.

virtual{if:{jwtdecode:my-secret-key}:Welcome back:Please sign in}

Expected(Welcome back when a valid token is present, otherwise Please sign in)

ActualPlease sign in

Because jwtdecode returns the user id when authenticated and empty otherwise, you can branch on it directly. With a valid token the visitor sees Welcome back; without one, Please sign in.

virtual{jwtdecode:my-secret-key:_#EXITTIME}

Expected(the user id if the token is still valid, otherwise empty)

The second parameter repeats the add_validity expression used by jwtencode. jwtdecode evaluates it for the token user and compares it to the aaValid claim baked into the token; if the value changed (for example because a logout updated the EXITTIME field) the token is rejected and the result is empty. Works only for Reader Management users.

← All expressions