JWT For The Great Openresty
Perl Lua Makefile
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 2 commits ahead of theganyo:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
examples
lib/resty
t
.dockerignore
.gitignore
AUTHORS.md
Dockerfile
LICENSE
Makefile
README.md
dist.ini

README.md

Name

lua-resty-jwt - JWT for ngx_lua and LuaJIT

version

0.1.2

Table of Contents

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)
            ';
        }
    }

Back to TOC

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"

Back to TOC

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 Back to TOC

Examples

Back to TOC

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"

Back to TOC

Testing With Docker

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

Back to TOC

See Also

Back to TOC