$ opm get taylorking/lua-resty-jwt

Name

lua-resty-jwt - JWT for ngx_lua and LuaJIT

version

0.1.2

Status

This library is still under active development and is considered production ready.

Description

This library requires an nginx build with OpenSSL, the ngx_lua module, the LuaJIT 2.0, the lua-resty-hmac, and the lua-resty-string,

Synopsis

        # nginx.conf:
    
        lua_package_path "/path/to/lua-resty-jwt/lib/?.lua;;";
    
        server {
            default_type text/plain;
            location = /verify {
                content_by_lua '
                    local cjson = require "cjson"
                    local jwt = require "resty.jwt"
    
                    local jwt_token = "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9" ..
                        ".eyJmb28iOiJiYXIifQ" ..
                        ".VAoRL1IU0nOguxURF2ZcKR0SGKE1gCbqwyh8u2MLAyY"
                    local jwt_obj = jwt:verify("lua-resty-jwt", jwt_token)
                    ngx.say(cjson.encode(jwt_obj))
                ';
            }
            location = /sign {
                content_by_lua '
                    local cjson = require "cjson"
                    local jwt = require "resty.jwt"
    
                    local jwt_token = jwt:sign(
                        "lua-resty-jwt",
                        {
                            header={typ="JWT", alg="HS256"},
                            payload={foo="bar"}
                        }
                    )
                    ngx.say(jwt_token)
                ';
            }
        }

Methods

To load this library,

1. you need to specify this library's path in ngx_lua's lua_package_path directive. For example, lua_package_path "/path/to/lua-resty-jwt/lib/?.lua;;";.

2. you use require to load the library into a local Lua variable:

        local jwt = require "resty.jwt"

sign

syntax: local jwt_token = jwt:sign(key, table_of_jwt)

sign a table_of_jwt to a jwt_token.

The alg argument specifies which hashing algorithm to use (HS256, HS512, RS256).

sample of table_of_jwt

    {
        "header": {"typ": "JWT", "alg": "HS512"},
        "payload": {"foo": "bar"}
    }

verify

syntax: local jwt_obj = jwt:verify(key, jwt_token, [, leeway])

verify a jwt_token and returns a jwt_obj table

load & verify

    syntax: local jwt_obj = jwt:load_jwt(jwt_token)
    syntax: local verified = jwt:verify_jwt_obj(key, jwt_obj, [, leeway])

verify = load_jwt + verify_jwt_obj

load jwt, check for kid, then verify it with the correct key

sample of jwt_obj

    {
        "raw_header": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9",
        "raw_payload: "eyJmb28iOiJiYXIifQ",
        "signature": "wrong-signature",
        "header": {"typ": "JWT", "alg": "HS256"},
        "payload": {"foo": "bar"},
        "verified": false,
        "valid": true,
        "reason": "signature mismatche: wrong-signature"
    }

sign-jwe

syntax: local jwt_token = jwt:sign(key, table_of_jwt)

sign a table_of_jwt to a jwt_token.

The alg argument specifies which hashing algorithm to use for encrypting key (DIR). The enc argument specifies which hashing algorithm to use for encrypting payload (A128CBC_HS256, A256CBC_HS512)

sample of table_of_jwt

    {
        "header": {"typ": "JWE", "alg": "DIR", "enc":"A128CBC_HS256"},
        "payload": {"foo": "bar"}
    }

verify

syntax: local jwt_obj = jwt:verify(key, jwt_token, [, leeway])

verify a jwt_token and returns a jwt_obj table

Examples

• JWT Auth With Query and Cookie

• JWT Auth With KID and Store Your Key in Redis

Installation

It is recommended to use the latest ngx_openresty bundle directly.

Also, You need to configure the lua_package_path directive to add the path of your lua-resty-jwt source tree to ngx_lua's Lua module search path, as in

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

and then load the library in Lua:

        local jwt = require "resty.jwt"

Testing With Docker

    docker build -t lua-resty-jwt .
    docker run --rm -it -v `pwd`:/lua-resty-jwt lua-resty-jwt make test

See Also

• the ngx_lua module: http://wiki.nginx.org/HttpLuaModule