Varnish Module for manipulating, creating, and verifying JWT and JWS tokens.
The following example verifys a token signed with the HS256
algorithm
that is in the Authorization
header.
vcl 4.1;
import jwt;
backend default None;
sub vcl_init {
new jwt_reader = jwt.reader();
}
sub vcl_recv {
if (!jwt_reader.parse(req.http.Authorization)) {
return (synth(401, "Invalid Authorization Token"));
}
if (!jwt_reader.set_key("secret")) {
return (synth(401, "Invalid Authorization Token"));
}
if (!jwt_reader.verify("HS256")) {
return (synth(401, "Invalid Authorization Token"));
}
# JWT token was valid
}
The following example takes an existing token, verifys it, and
extends its expiration to 6 hours from the current time then sets the new token
on the request Authorization
header.
vcl 4.1;
import jwt;
backend default None;
sub vcl_init {
new jwt_reader = jwt.reader();
new jwt_writer = jwt.writer();
}
sub vcl_recv {
if (!jwt_reader.parse(req.http.Authorization)) {
return (synth(401, "Invalid Authorization Token"));
}
if (!jwt_reader.set_key("secret")) {
return (synth(401, "Invalid Authorization Token"));
}
if (!jwt_reader.verify("HS256")) {
return (synth(401, "Invalid Authorization Token"));
}
# JWT token was valid, extend the lifetime.
jwt_writer.from_string(jwt_reader.to_string());
jwt_writer.set_exp(now + 6h);
if (jwt_writer.error()) {
# Something went wrong extending the expiration date.
}
set req.http.Authorization = jwt_writer.generate("secret");
if (jwt_writer.error()) {
# Something went wrong generating the new token.
}
}
A JWT Reader object is used for reading and verifying JWT/JWS tokens. The reader’s context is request scoped.
OBJECT jwt.reader()
Creates a JWT Reader Object. must be called in vcl_init
.
Returns
A JWT Reader Object.
BOOL reader.parse(STRING token)
Parse a JWT/JWS token into the reader and return whether it was able to be parsed successfully. You should always check the return of this method before calling any of the methods below.
Arguments
STRING token
- the JWT token to parse.Returns
A BOOL
that is TRUE
if it the token was successfully parsed
and FALSE
if it was not.
BOOL reader.set_key(STRING key)
Set the HMAC secret or RSA public key to use to verify the token.
Arguments
STRING key
- the HMAC secret or RSA public key to use to verify the token.Returns
A BOOL
that is TRUE
if the key was successfully set and FALSE
if
it was not.
INT reader.set_jwk(STRING jwk)
Set the RSA Public key(s) for the token via a JWK.
Arguments
STRING jwk
- the JWK to use to verify the token. this can be a single key
or a key set, currently JWKs are only supported for verifying RS256
,
RS384
, and RS512
.Returns
An INT
that is the number of usable keys that were parsed from the provided
JWK.
BOOL reader.verify(STRING expected_alg)
Verify the JWK/JWS token. This method supports verifying the
signature algorithms None
, HS256
, HS384
, HS512
, RS256
,
RS384
, and RS512
. The exp
, iat
, and nbf
payload parameters
are also checked when this method is called if they are present.
Arguments
STRING expected_alg
- the expected algorithm to use to verify the token.
If this does not match the algorithm of the passed in token verification will
fail. DO NOT USE get_alg()
to populate this argument as this will allow
an attacker to forge tokens by claiming the algorithm of the token is None
which does not require signature verification. The possible values for this
argument are None
, HS256
, HS384
, HS512
, RS256
,
RS384
, and RS512
.Returns
A BOOL
that is TRUE
if the expected_alg
matches the token’s
algorithm, the signature algorithm is on of the supported ones list above,
the signature is valid, and the exp
, iat
, and nbf
claims
are valid if they are present. If any of the aforementioned conditions are not
met the return value will be FALSE
.
STRING reader.get_alg()
Grabs the signature algorithm for the loaded JWT token ex: HS256
Arguments
None
Returns
A STRING
that is the signature algorithm of the loaded JWT token.
STRING reader.get_typ()
Gets the typ
parameter from the JWT token header ex: JWT
Arguments
None
Returns
A STRING
that is the typ
parameter from the JWT token header.
BOOL reader.get_b64()
Gets the b64
parameter from the JWT token header ex: TRUE
Arguments
None
Returns
A BOOL
that is the b64
parameter from the JWT token header. If the
parameter isn’t present it will return TRUE
.
BOOL reader.is_jwt()
Tell whether the token is a JWT or a JWS. A JWT token will either have the
typ
header parameter equal to JWT
or have a payload that is base64
encoded JSON, if both of these requirements aren’t met it is a JWS and this
method will return FALSE
.
Arguments
None
Returns
A BOOL
where the loaded token is a JWT token or not.
STRING reader.get_sub(STRING default = 0)
Get the sub
parameter of the JWT payload and return default
if
it does not exist.
Arguments
STRING default
optional
- what to return if the parameter does not exist,
by default this is an empty string.Returns
A STRING
that contains the sub
parameter value, if it was not
defined default
is returned instead.
STRING reader.get_iss(STRING default = 0)
Get the iss
parameter of the JWT payload and return default
if
it does not exist.
Arguments
STRING default
optional
- what to return if the parameter does not exist,
by default this is an empty string.Returns
A STRING
that contains the iss
parameter value, if it was not
defined default
is returned instead.
STRING reader.get_jti(STRING default = 0)
Get the jti
parameter of the JWT payload and return default
if
it does not exist.
Arguments
STRING default
optional
- what to return if the parameter does not exist,
by default this is an empty string.Returns
A STRING
that contains the jti
parameter value, if it was not
defined default
is returned instead.
BOOL reader.has_exp()
Get whether the JWT token has an exp
parameter. This MUST be called before
reader.get_exp()
to make sure you have an exp
to return.
Arguments
None
Returns
A BOOL
whether the JWT payload contains the exp
parameter.
TIME reader.get_exp()
Get the exp
parameter of the JWT payload. You must call reader.has_exp()
before calling this function to make sure you have an exp
to get.
Arguments
None
Returns
A TIME
that is the exp
parameter of the JWT payload.
BOOL reader.has_nbf()
Get whether the JWT token has an nbf
parameter. This MUST be called before
reader.get_nbf()
to make sure you have an nbf
to return.
Arguments
None
Returns
A BOOL
whether the JWT payload contains the nbf
parameter.
TIME reader.get_nbf()
Get the nbf
parameter of the JWT payload. You must call reader.has_nbf()
before calling this function to make sure you have an nbf
to get.
Arguments
None
Returns
A TIME
that is the nbf
parameter of the JWT payload.
BOOL reader.has_iat()
Get whether the JWT token has an iat
parameter. This MUST be called before
reader.get_iat()
to make sure you have an iat
to return.
Arguments
None
Returns
A BOOL
whether the JWT payload contains the iat
parameter.
TIME reader.get_iat()
Get the iat
parameter of the JWT payload. You must call reader.has_iat()
before calling this function to make sure you have an iat
to get.
Arguments
None
Returns
A TIME
that is the iat
parameter of the JWT payload.
STRING reader.get_header()
Get the header of the JWT token as a JSON string.
Arguments
None
Returns
A STRING
that is the decoded JSON of the JWT token header.
STRING reader.get_header_encoded()
Get the header of the JWT token as a JSON string that is base64 encoded.
Arguments
None
Returns
A STRING
that is the JSON of the JWT token header base64 encoded.
STRING reader.get_payload()
Get the payload of the JWT token as a JSON string.
Arguments
None
Returns
A STRING
that is the decoded JSON of the JWT token payload.
STRING reader.get_payload_encoded()
Get the payload of the JWT token as a JSON string that is base64 encoded.
Arguments
None
Returns
A STRING
that is the JSON of the JWT token payload base64 encoded.
STRING reader.to_string()
Gets a string representation of the token to pass to the writer’s
from_string
method
Arguments
None
Returns
A STRING
that can be passed to the writer’s from_string
method.
BOOL reader.from_string(STRING token)
Parse a JWT/JWS token into the reader and return whether it was able to be
parsed successfully. Primarily an alias to keep convention with the
reader
/writer
to
and from
methods. You should always
check the return of this method before calling any of the other reader methods.
Arguments
STRING token
- the JWT token to parse.Returns
A BOOL
that is TRUE
if it the token was successfully parsed and
FALSE
if it was not.
A JWT Writer object is used for manipulating and creating JWT/JWS tokens. The writer’s context is request scoped.
OBJECT jwt.writer()
Creates a JWT Writer Object. must be called in vcl_init
.
Returns
A JWT Writer Object.
VOID writer.set_header(STRING header)
Set the JSON header on the JWT/JWS token.
Arguments
STRING header
- the JSON string to set as the header of the JWT/JWS token.Returns
Nothing.
VOID writer.set_header_encoded(STRING header)
Set the Base64 encoded JSON header on the JWT/JWS token.
Arguments
STRING header
- the base64encoded JSON string to set as the header
of the JWT/JWS token.Returns
Nothing.
VOID writer.set_payload(STRING payload)
Set the JSON payload on the JWT/JWS token.
Arguments
STRING payload
- the JSON string to set as the payload of the JWT/JWS token.Returns
Nothing.
VOID writer.set_payload_encoded(STRING payload)
Set the Base64 encoded JSON payload on the JWT/JWS token.
Arguments
STRING payload
- the base64encoded JSON string to set as the payload
of the JWT/JWS token.Returns
Nothing.
VOID writer.parse(STRING token)
Set the header and payload the JWT/JWS token provided.
Arguments
STRING token
- the JWT/JWS token to use for the header and payload.Returns
Nothing.
VOID writer.from_string(STRING token)
Set the header and payload the JWT/JWS token provided. Primarily an alias of
parse
to keep convention with the reader
/writer
to
and
from
methods.
Arguments
STRING token
- the JWT/JWS token to use for the header and payload.Returns
Nothing.
BOOL writer.error()
Did any of the writer methods result in an error?
Arguments
None
Returns
A BOOL
indicating whether any the writer’s methods resulted in an error.
STRING writer.generate(STRING key)
Generate the full JWK/JWS token. This method supports creating with the
signature algorithms None
, HS256
, HS384
, HS512
, RS256
,
RS384
, and RS512
.
Arguments
STRING key
- the HMAC secret or RSA public key to use to create the token.Returns
A STRING
that is either the full JWT/JWS token or empty if an error
occurred .
STRING writer.to_string(STRING key)
Generate the full JWK/JWS token. This method supports creating with the
signature algorithms None
, HS256
, HS384
, HS512
, RS256
,
RS384
, and RS512
. Primarily an alias of generate
to keep
convention with the reader
/writer
to
and from
methods.
Arguments
STRING key
- the HMAC secret or RSA public key to use to create the token.Returns
A STRING
that is either the full JWT/JWS token or empty if an error
occurred.
STRING writer.reset()
Reset all data on the writer including the error
flag.
Arguments
None
Returns
Nothing.
VOID writer.set_alg(STRING alg)
Set the signature algorithm on the token. This method supports alg
being
None
, HS256
, HS384
, HS512
, RS256
,
RS384
, or RS512
.
Arguments
STRING alg
- the signature algorithm to set, possible values are
None
, HS256
, HS384
, HS512
, RS256
, RS384
, or RS512
.Returns
Nothing
VOID writer.set_typ(STRING typ)
Set the typ
parameter of the token header.
Arguments
STRING typ
- What to set as the typ
parameter of the token header.Returns
Nothing
VOID writer.set_b64(BOOL b64)
Set the b64
parameter of the token header.
Arguments
BOOL b64
- What to set as the b64
parameter of the token header.Returns
Nothing
VOID writer.set_sub(STRING sub)
Set the sub
parameter of the token payload.
Arguments
STRING sub
- What to set as the sub
parameter of the token payload.Returns
Nothing
VOID writer.set_iss(STRING iss)
Set the iss
parameter of the token payload.
Arguments
STRING iss
- What to set as the iss
parameter of the token payload.Returns
Nothing
VOID writer.set_jti(STRING jti)
Set the jti
parameter of the token payload.
Arguments
STRING jti
- What to set as the jti
parameter of the token payload.Returns
Nothing
VOID writer.set_exp(TIME time)
Set the exp
parameter of the token payload.
Arguments
TIME time
- What to set as the exp
parameter of the token payload.Returns
Nothing
VOID writer.delete_exp()
Delete the exp
parameter of the token payload.
Arguments
None
Returns
Nothing
VOID writer.set_nbf(TIME time)
Set the nbf
parameter of the token payload.
Arguments
TIME time
- What to set as the nbf
parameter of the token payload.Returns
Nothing
VOID writer.delete_nbf()
Delete the nbf
parameter of the token payload.
Arguments
None
Returns
Nothing
VOID writer.set_iat(TIME time)
Set the iat
parameter of the token payload.
Arguments
TIME time
- What to set as the iat
parameter of the token payload.Returns
Nothing
VOID writer.delete_iat()
Delete the iat
parameter of the token payload.
Arguments
None
Returns
Nothing
VOID writer.set_duration(DURATION duration)
Set the exp
parameter of the token payload duration
in the future from
the current time.
Arguments
DURATION duration
- How far into the future the exp
parameter should
be.Returns
Nothing