lua-resty-jwt

To use the library, you must add the library's path to the lua_package_path directive in your nginx.conf so that require "resty.jwt" can locate the files.

# nginx.conf
http {
    lua_package_path "/path/to/lua-resty-jwt/lib/?.lua;;";
    ...
}

You can protect Nginx locations by using an access_by_lua_file directive that points to a guard script. This pattern typically involves setting a $jwt_secret variable in the Nginx configuration which the Lua script then uses to validate incoming JWTs found in either the query string or cookies.

To implement this, define your secret in the location block and call your guard script via access_by_lua_file.

location / {
    access_log off;
    default_type text/plain;

    set $jwt_secret "your-own-jwt-secret";
    access_by_lua_file /etc/nginx/lua/guard.lua;

    echo "i am protected by jwt guard";
}

You can install the library using OPM, LuaRocks, or by downloading the source directly.

Dependencies: This library requires an Nginx build with OpenSSL, the ngx_lua module, LuaJIT 2.0, lua-resty-hmac (specifically the one from jkeys089, not the LuaRocks version), and lua-resty-string).

# Using OPM
opm get SkyLothar/lua-resty-jwt

# Using LuaRocks
luarocks install lua-resty-jwt

For more advanced setups, you can use a kid (Key ID) to identify which key to use for verification and store those keys in a Redis instance. This allows for dynamic key rotation without restarting Nginx.

In your Nginx configuration, you must define the Redis connection parameters (host and port) before calling the Lua script that handles the Redis-backed JWT verification.

location / {
    set $redhost "127.0.0.1";
    set $redport 6379;
    # set $reddb 1;
    # set $redauth "your-redis-pass";
    access_by_lua_file /etc/nginx/lua/redjwt.lua;

    echo "i am protected jwt guard";
}

Instead of complex claim_spec tables, you can pass a validation_options table to jwt:load or jwt:verify_jwt_obj.

Warning: You cannot mix legacy options with other claim_spec validators. If you need both, pass them as separate arguments to the function.

Available Options:

• lifetime_grace_period: (Number) Leeway in seconds for nbf and exp claims. Automatically requires nbf or exp to exist.
• require_nbf_claim: (Boolean) If true, the nbf claim must be present.
• require_exp_claim: (Boolean) If true, the exp claim must be present.
• valid_issuers: (Array of strings) A whitelist of allowed iss values.

local jwt_obj = jwt:verify(key, jwt_token, {
    lifetime_grace_period = 120,
    require_exp_claim = true,
    valid_issuers = { "my-trusted-issuer" }
})

Use jwt:verify(key, jwt_token [, claim_spec [, ...]]) to verify a token.

Key parameter types:

• A pre-shared key (string).
• A function that takes a single parameter (the kid value from the header) and returns the pre-shared key (string) or nil if the lookup fails.

local jwt = require "resty.jwt"

-- Using a string key
local jwt_obj = jwt:verify("secret", "token_string")

-- Using a function for KID lookup
local jwt_obj = jwt:verify(function(kid) 
    if kid == "key-1" then return "secret-1" end
    return nil
end, "token_string")

If you have a parsed JWT object (or want to handle the kid lookup and verification in one step), use these methods:

1. jwt:load_jwt(jwt_token): Parses the token into a jwt_obj table.
2. jwt:verify_jwt_obj(key, jwt_obj [, claim_spec [, ...]]): Verifies an existing object.

Combining these allows you to load a JWT, check for a kid, and then verify it with the correct key automatically.

local jwt = require "resty.jwt"

-- Combined pattern: load then verify
local jwt_obj = jwt:load_jwt(jwt_token)
local verified_obj = jwt:verify_jwt_obj(key, jwt_obj)

Use the jwt:sign(key, table_of_jwt) method to generate a JWT token from a Lua table. The alg argument in the header determines the hashing algorithm (e.g., HS256, HS512, RS256).

local jwt = require "resty.jwt"

local jwt_token = jwt:sign(
    "your-secret-key",
    {
        header={typ="JWT", alg="HS256"},
        payload={foo="bar"}
    }
)

You can sign a JWE using the same jwt:sign method, but with specific header arguments:

• alg: The hashing algorithm for encrypting the key (e.g., dir).
• enc: The hashing algorithm for encrypting the payload (e.g., A128CBC-HS256, A256CBC-HS512).

local jwt_token = jwt:sign(
    "key",
    {
        header={typ="JWE", alg="dir", enc="A128CBC-HS256"},
        payload={foo="bar"}
    }
)