ns_crypto::JWT method verify (public)

 <instance of ns_crypto::JWT> verify [ -alg alg ] [ -key key ] \
    [ -jwk jwk ] [ -jwks jwks ] [ -secret secret ] [ -kid kid ] \
    [ -requirekid ] [ -verifyclaims ] [ -aud aud ] [ -iss iss ] \
    [ -sub sub ] [ -clockskew clockskew ] [ -now now ] token

Defined in

Verify a JSON Web Token (JWT) and optionally validate claims. The method decodes the token, resolves a verification key, and verifies the signature according to the algorithm specified in the JWT header. Optionally, registered claims can be validated.

Switches:

-alg (optional)

Expected signature algorithm. When specified, the value must match the "alg" field in the JWT header.

-key (optional)

Public key in PEM format (string or file) used for verification.

-jwk (optional)

JWK representation of the public key used for verification

-jwks (optional)

JWK set (list or dictionary of JWKs). When specified, the key is selected based on the "kid" value.

-secret (optional)

Shared secret used for HS256, HS384, and HS512.

-kid (optional)

Expected key identifier. When specified, it must match the "kid" value in the JWT header.

-requirekid (optional)

When true, require that the JWT header contains a "kid" field.

-verifyclaims (optional)

When true, validate registered claims such as expiration, not-before, issuer, subject, and audience.

-aud (optional)

Expected audience claim.

-iss (optional)

Expected issuer claim.

-sub (optional)

Expected subject claim.

-clockskew (optional, defaults to "0")

Allowed clock skew in seconds when validating time-based claims.

-now (optional)

Reference time (seconds since epoch) used for claim validation. When not specified, the current time is used.

Parameters:

token (required)

JWT string in compact serialization format ("header.payload.signature").

Returns:

A Tcl dictionary containing: valid — boolean indicating successful verification header — parsed JWT header as Tcl dictionary payload — parsed JWT payload as Tcl dictionary kid — resolved key identifier (may be empty) alg — algorithm used for verification

Testcases:

No testcase defined.

Source code:

lassign [:split_token $token] headerB64 payloadB64 sigB64

set headerJson  [ns_base64urldecode -- $headerB64]
set payloadJson [ns_base64urldecode -- $payloadB64]
set signature   [ns_base64urldecode -binary -- $sigB64]

set header  [ns_json parse $headerJson]
set payload [ns_json parse $payloadJson]

set tokenAlg [dict get $header alg]
if {$alg ne "" && $alg ne $tokenAlg} {
    error "JWT algorithm mismatch: expected \"$alg\", got \"$tokenAlg\""
}

if {$tokenAlg eq "none"} {
    error "unsigned JWTs (alg=none) are not accepted by verify"
}

set signingInput "${headerB64}.${payloadB64}"
set resolvedKid [expr {[dict exists $header kid] ? [dict get $header kid] : ""}]

if {$requirekid && $resolvedKid eq ""} {
    error "JWT header does not contain required kid"
}
if {$kid ne "" && $resolvedKid ne $kid} {
    error "JWT kid mismatch: expected \"$kid\", got \"$resolvedKid\""
}

if {$tokenAlg in {HS256 HS384 HS512}} {
    if {$secret eq ""} {
        error "missing shared secret; provide -secret"
    }
    if {![:verify_hmac -alg $tokenAlg -secret $secret -data $signingInput -signature $signature]} {
        error "JWT signature verification failed"
    }

} else {

    set verifyPem [:resolve_verification_key_pem  -alg $tokenAlg  -key $key  -jwk $jwk  -jwks $jwks  -kid $resolvedKid]

    set verifySpec [:alg_to_verify_spec $tokenAlg]

    if {![:verify_signature  -spec $verifySpec  -pem $verifyPem  -data $signingInput  -signature $signature]} {
        error "JWT signature verification failed"
    }
}

if {$verifyclaims} {
    :verify_registered_claims  -payload $payload  -aud $aud  -iss $iss  -sub $sub  -clockskew $clockskew  -now $now
}

return [dict create  valid 1  header $header  payload $payload  kid $resolvedKid  alg $tokenAlg]

XQL Not present:

Generic, PostgreSQL, Oracle