Search
Varnish Cache Plus

JWT

Description

Varnish Module for manipulating, creating, and verifying JWT and JWS tokens.

Examples

Verifying

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
}

Creating/Modifying

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.
	}
}

JWT Reader Functions

A JWT Reader object is used for reading and verifying JWT/JWS tokens. The reader’s context is request scoped.

reader

OBJECT jwt.reader()

Creates a JWT Reader Object. must be called in vcl_init.

Returns

A JWT Reader Object.

parse

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.

set_key

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.

set_jwk

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.

verify

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.

get_alg

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.

get_typ

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.

get_b64

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.

is_jwt

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.

get_sub

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.

get_iss

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.

get_jti

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.

has_exp

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.

get_exp

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.

has_nbf

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.

get_nbf

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.

has_iat

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.

get_iat

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.

get_header

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.

get_header_encoded

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.

get_payload

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.

get_payload_encoded

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.

to_string

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.

from_string

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.

JWT Writer Functions

A JWT Writer object is used for manipulating and creating JWT/JWS tokens. The writer’s context is request scoped.

writer

OBJECT jwt.writer()

Creates a JWT Writer Object. must be called in vcl_init.

Returns

A JWT Writer Object.

set_header

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.

set_header_encoded

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.

set_payload

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.

set_payload_encoded

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.

parse

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.

from_string

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.

error

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.

generate

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 .

to_string

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.

reset

STRING writer.reset()

Reset all data on the writer including the error flag.

Arguments

None

Returns

Nothing.

set_alg

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

set_typ

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

set_b64

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

set_sub

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

set_iss

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

set_jti

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

set_exp

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

delete_exp

VOID writer.delete_exp()

Delete the exp parameter of the token payload.

Arguments

None

Returns

Nothing

set_nbf

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

delete_nbf

VOID writer.delete_nbf()

Delete the nbf parameter of the token payload.

Arguments

None

Returns

Nothing

set_iat

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

delete_iat

VOID writer.delete_iat()

Delete the iat parameter of the token payload.

Arguments

None

Returns

Nothing

set_duration

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