Verification of claims

[toonetown]

The way that the "auth" function of the code at https://github.com/auth0/nginx-jwt is pretty nice. It seems to me that this would be a nicer (and more flexible) alternative to the verification code that is currently being worked on.

Basically, you specify a table with claims you want to verify. Existence of a claim key requires the presence of it. The value of the claims can either be a string (in which case, it's matched against the string value in the payload), or a function which takes a single parameter (the value from the payload) and returns true or false.

It seems that the current validation of nbf and exp (and the grace period and issuers check) could be done using this mechanism instead, if it were available.

I actually have some code that does this, and am willing to put together a pull request if it would be something that is desired.

[SkyLothar]

sounds like my proposal combined with @fermaem 's.
have a little discusstion at #19 , check it out

[toonetown]

Looks great - I'd love to join in the discussion and/or help put together something that would also be a bit more flexible (i.e. to add the ability to validate a subject, or something else application-specific). Would that be best to do on #19 or would it be better to work up some kind of proposal (in the form of a PR) and carry on the discussion in a new issue (or this issue)?

[SkyLothar]

hmm...
let's discuss in this issue 🎉

[toonetown]

Agreed that this now makes the validators table look kind of weird. I would almost say that we replace the timeframe and iss validator options with some exposed functions that can be used just as a table of claims.

[SkyLothar]

yep, i agree.

hi @fermaem , any thoughts?

[fermaem]

I'm not sure that every claim validation should be allowed to be overridden now (ie. YAGNI): For instance, the lifecycle validator. On the other hand, it may make sense to provide the user with a callback for him/her to feed/override the base validator with some additional data.

@toonetown Any chance you could wrap up a client API proposal mock?

[toonetown]

WARNING: Super long post follows.

I actually really like the simplicity of the API that is used by the auth function by https://github.com/auth0/nginx-jwt (which, BTW, uses this project for their underlying JWT work). Particularly, I really like both the readability and simplicity of defining claims to be checked as a table that matches the claims themselves. i.e.:

{
    sub = "^[a-z]+$",
    iss = function(val)
        for _, value in pairs({ "first", "second" }) do
            if value == val then return true end
        end
        return false
    end
}

The auth0/nginx-jwt project contains a single helper function - table_contains that would allow you to simplify this second statement thusly:

{
    iss = function(val) return nginx_jwt.table_contains({ "first", "second" }, val) end
}

I would, however, propose to simplify the API even one step further by defining it as this:

local verified = jwt:verify_jwt_obj(key, jwt_obj [, claim_spec])
-- OR --
local verified = jwt:verify(key, jet_token [, claim_spec])

From a purely "readability" point of view, this tells me "verify the object with the given key against the given claim_spec."

I would define a claim_spec as a lua table where each key in the table is the name of a claim which is being verified. The value corresponding to each key is a function which has the following signature:

function(val, claim, jwt_obj)

Where val is the value of the claim from jwt_obj (or nil if it doesn't exist), claim is the name of the claim that is being verified, and jwt_obj is the object that is being verified. This function would return either true or false (That is, I would simplify the API a bit from what auth0/nginx-jwt has done and remove the ability to specify a string value). Any validator MAY raise an error, and the validation will be treated as a failure, and the error that was raised will be put into the reason field of the resulting object.

Then, I would provide a library of "validator" functions that would return an appropriate validator function. Since I would anticipate this set of validator functions, I might suggest placing them in a separate file and module (jwt-validators.lua in this example). One could then verify a token (or alternatively, a loaded object using verify_jwt_obj) by doing:

local jwt = require "resty.jwt"
local validators = require "resty.jwt_validators"
local leeway = 300

local verified = jwt:verify(key, jwt_token, {
    sub = validators.required_matches("^[a-z]+$"),
    iss = validators.required_equals_any_of({ "first", "second" }),
    nbf = validators.required_not_before(leeway),
    exp = validators.required_expiration(leeway),
    myclaim = validators.required(),
    ...
})

Or, put another way, what is now defined as:

local jwt_obj = jwt:verify(key, jwt_token,
    {
        lifetime_grace_period = 120,
        require_exp_claim = true,
        valid_issuers = { "my-trusted-issuer", "my-other-trusteed-issuer" },
        claims = { sub = "My Test Subject" }
    }
)

Could be done as:

local jwt_obj = jwt:verify(key, jwt_token,
    {
        exp = validators.required_expiration(120)
        iss = validators.required_equals_any_of({ "my-trusted-issuer", "my-other-trusteed-issuer" }),
        sub = validators.required_equals("My Test Subject")
    }
)

It just seems a bit clearer what is trying to be verified, and what is happening. It also cleans up code which uses this library a bit and makes it more readable.

Suggested functions to include in the jwt_validators module (all of these functions would actually return a validator function - one that takes a single parameter and returns true or false if they match):

--[[
    Returns a validator that returns false if a value doesn't exist.  If
    the value exists and a chain_function is specified, then the value of 
        chain_function(val, claim, jwt_obj)
    will be returned, otherwise, true will be returned.  This allows for 
    specifying that a value is both required *and* it must match some 
    additional check.  This function will be used in the "required_*" shortcut
    functions for simplification.
]]-
function jwt_validators.required([chain_function])

--[[
    Returns a validator that checks if a value exactly equals the given check_value.
    If the value is nil, then this check succeeds.
]]-
function jwt_validators.equals(check_val)

--[[
    Returns a validator that checks if a value matches the given pattern.  If the
    value is nil, then this check succeeds.
]]-
function jwt_validators.matches(pattern)

--[[
    Returns a validator that checks if a value exactly equals any of the given values.
    If the value is nil, then this check succeeds.
]]-
function jwt_validators.equals_any_of(check_values)

--[[
    Returns a validator that checks if a value matches any of the given patterns.
    If the value is nil, then this check succeeds.
]]-
function jwt_validators.matches_any_of(check_patterns)

--[[
    Returns a validator that checks if a date is not before the current time (within
    the given optional leeway).  If leeway is not specified, it defaults to 0.  An
    optional date_value can also be given - which is helpful for writing unit tests.
    If date_value is not specified, then the current time is used.  If the value is 
    nil, then this check succeeds.
]]--
function jwt_validators.not_before([leeway [, date_value]])

--[[
    Returns a validator that checks if the current time is equal to or before
    a date (within the given optional leeway).  If leeway is not specified, it defaults 
    to 0.  An optional date_value can also be given - which is helpful for writing 
    unit tests.  If date_value is not specified, then the current time is used.  If the
    value is nil, then this check succeeds.
]]--
function jwt_validators.expiration([leeway [, date_value]])

--[[
    These functions are just shortcuts to prevent the need to type, for example:
    jwt_validators.required(jwt_validators.equals(check_val)).  They take the same
    parameters as their non-required counterparts (i.e required_equals_any_of takes the
    same parameters as equals_any_of).
]]--
function jwt_validators.required_equals(check_val)
function jwt_validators.required_matches(pattern)
function jwt_validators.required_equals_any_of(check_values)
function jwt_validators.required_matches_any_of(check_patterns)
function jwt_validators.required_not_before([leeway [, date_value]])
function jwt_validators.required_expiration([leeway [, date_value]])

I think that this will provide flexibility as well as ease of use of the library. It also seems like it simplifies things within the library so that there are fewer places for potential bugs. Also, the functions provided by the validators library can be expanded upon and improved over time.

I'd appreciate hearing any feedback or suggestions about this that you would have. I'm also willing to code this up and submit it as a PR if it would be easier to evaluate in that format.

[toonetown]

It might even be nice to have the verify functions take multiple claim_spec parameters, and it merges them all together into a single claim_spec to use (later ones override earlier-specified ones). Then, an adapter function could be provided in jwt_validators that returns an appropriate claim_spec which takes validation_options (as they are defined currently surrounding lifecycle). For example:

--[[
    Returns a `claim_spec` table follows the lifetime-specific validation_options
]]--
function jwt_validators.lifetime_spec(validation_options)

You could then do something like this:

local jwt_obj = jwt:verify(key, jwt_token, validators.lifetime_spec(
    {
        lifetime_grace_period = 120,
        require_exp_claim = true
    }
))

Or, to use the full above example:

local jwt_obj = jwt:verify(key, jwt_token,
    validators.lifetime_spec({
        lifetime_grace_period = 120,
        require_exp_claim = true
    }), {
        iss = validators.required_equals_any_of({ "my-trusted-issuer", "my-other-trusteed-issuer" }),
        sub = "My Test Subject"
    }
)

That's just a thought. I kind of like the ability to merge multiple claim_spec tables.