{"id":34709619,"url":"https://github.com/tsuru/lua-resty-libjwt","last_synced_at":"2026-05-22T20:32:01.166Z","repository":{"id":277167332,"uuid":"928305472","full_name":"tsuru/lua-resty-libjwt","owner":"tsuru","description":"Lua bindings to libjwt (https://github.com/benmcollins/libjwt) using FFI","archived":false,"fork":false,"pushed_at":"2025-10-16T18:42:38.000Z","size":158,"stargazers_count":4,"open_issues_count":3,"forks_count":1,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-10-17T17:46:17.516Z","etag":null,"topics":["authentication","authorization","jwt","lua","nginx","openresty"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsuru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-06T12:18:42.000Z","updated_at":"2025-10-16T18:42:24.000Z","dependencies_parsed_at":"2025-02-12T14:38:32.519Z","dependency_job_id":"6edd8405-94e0-42ca-9750-c25121546dca","html_url":"https://github.com/tsuru/lua-resty-libjwt","commit_stats":null,"previous_names":["tsuru/lua-resty-libjwt"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/tsuru/lua-resty-libjwt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsuru%2Flua-resty-libjwt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsuru%2Flua-resty-libjwt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsuru%2Flua-resty-libjwt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsuru%2Flua-resty-libjwt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsuru","download_url":"https://codeload.github.com/tsuru/lua-resty-libjwt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsuru%2Flua-resty-libjwt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33366519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-21T12:23:38.849Z","status":"online","status_checked_at":"2026-05-22T02:00:06.671Z","response_time":265,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","jwt","lua","nginx","openresty"],"created_at":"2025-12-24T23:54:44.193Z","updated_at":"2026-05-22T20:32:01.160Z","avatar_url":"https://github.com/tsuru.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# lua-resty-libjwt\n\n[![LuaRocks](https://img.shields.io/badge/LuaRocks-lua--resty--libjwt-blue.svg)](https://luarocks.org/modules/tsuru/lua-resty-libjwt)\n\n## Overview\n\nThe **lua-resty-libjwt** module is a **Lua** library with **C** bindings that validates JWT tokens directly in **Nginx**. Built with **OpenResty** and leveraging **FFI** (Foreign Function Interface), it provides Lua bindings to [libjwt](https://github.com/benmcollins/libjwt). By handling JWT validation at the Nginx level, it prevents unauthorized requests from reaching the API, reducing the load on application servers.\n\n## Requirements\n\n* [Nginx](https://nginx.org) with the [Lua module](https://github.com/openresty/lua-nginx-module)\n* [libjwt](https://github.com/benmcollins/libjwt) (≥ 3.2.0)\n* [lua-cjson](https://luarocks.org/modules/openresty/lua-cjson) (≥ 2.1.0)\n\n## Install\n\nYou can easily install it with [Luarocks](https://luarocks.org):\n\n```bash\nluarocks install lua-resty-libjwt\n```\n\n## Configuration and Usage\n\nTo use **Libjwt**, you need to provide the path to the **jwks.json** file, which contains the public keys for JWT token verification.\n\n### Configuration Parameters\n\nThe module accepts the following parameters:\n\n### `jwks_files` (Required)\n\n- An **array of paths** pointing to files containing **JWKS (JSON Web Key Set)** keys.\n- At least one file must be valid; otherwise, an error will be returned.\n\n**Configuration example:**\n\n```lua\nlibjwt.validate({\n    jwks_files = {\"/usr/share/tokens/jwks.json\"}\n})\n```\n\n### `header_token` (Optional)\n\n- Defines the **HTTP header field** where the JWT token will be retrieved.\n- The default value is **\"Authorization\"**.\n- If the token is in a different header, this value can be modified.\n\n**Example:**\n\n```lua\nlibjwt.validate({\n    jwks_files = {\"/usr/share/tokens/jwks.json\"},\n    header_token = \"X-Custom-Token\"\n})\n```\n\n### `return_unauthorized_default` (Optional)\n\n- Defines whether a **401 Unauthorized** response should be automatically returned if the token is invalid.\n- The default value is **true** (automatically generates an error).\n- If set to **false**, the error must be handled manually in `nginx.conf`.\n\n**Example:**\n\n```lua\nlibjwt.validate({\n    jwks_files = {\"/usr/share/tokens/jwks.json\"},\n    return_unauthorized_default = false\n})\n\n```\n\nIf `return_unauthorized_default` is **false**, the error must be handled directly:\n\n```lua\nlocal token, err = libjwt.validate({\n    jwks_files = {\"/usr/share/tokens/jwks.json\"},\n    return_unauthorized_default = false\n})\n```\n\n## Example Nginx Configuration\n\nHere is an example of how to configure **libjwt** in `nginx.conf`:\n\n```perl\nserver {\n    listen 80;\n    location /private {\n        access_by_lua_block {\n            local libjwt = require(\"resty.libjwt\")\n            local token, err = libjwt.validate({\n                jwks_files = {\"/usr/share/tokens/jwks.json\"}\n            })\n            if token then\n                -- You may add logic as needed, accessing the JWT claims:\n                -- token.claim.sub\n                -- token.claim.iss\n            end\n        }\n\n        proxy_pass http://your_backend;\n    }\n}\n\n```\n\n### JWT Token Validation\n\nThe `libjwt.validate()` function returns the **decoded claim** of the token or an error if the token is invalid.\n\n**Example:**\n\n```lua\nlocal token, err = libjwt.validate()\nif token then\n    ngx.log(ngx.ERR, \"Valid JWT token: \", token)\nelse\n    ngx.log(ngx.ERR, \"Token validation error: \", err)\nend\n\n```\n\n### Claims-based Authorization\n\nSome backends are restricted so that only certain users can access them, allowing us to restrict access based on [Claims].\n\nSee the Lua configuration `validate_claims` below:\n\n```lua\nlocal libjwt = require(\"resty.libjwt\")\nlibjwt.validate({\n    jwks_files = {\"/etc/nginx/jwks.json\"},\n    validate_claims = {\n        iss = {exact = \"myiss\"},\n        aud = {one_of = {\"audience1\", \"audience2\"}},\n        sub = {pattern = \".*@mycompany%.com\"},\n    },\n})\n```\n\n#### Validation Types\n\nNote that we have 3 types of validations:\n\n* `{exact = \"TERM\"}`: ensures that a claim must be exactly equal to TERM, otherwise the user will receive a 403 (Forbidden)\n* `{one_of = {\"TERM1\", \"TERM2\"}}`: allows a list of permitted CLAIMS, if not in the list the user will receive a 403 (Forbidden)\n* `{pattern = \".*@mycompany%.com\"}`: Allows validation using [Lua Pattern Matching](https://www.lua.org/pil/20.2.html), an expression language similar to Regex. In the example above, we can ensure that only users from the mycompany.com domain can access; if the expression doesn't match, the user will receive a 403 (Forbidden)\n\n\n## Final Considerations\n\n- Ensure that the **jwks.json** file is accessible by Nginx.\n- If using a **custom header_token**, make sure the client is sending it correctly.\n- The module improves system efficiency by preventing unauthorized requests from reaching the API.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsuru%2Flua-resty-libjwt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsuru%2Flua-resty-libjwt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsuru%2Flua-resty-libjwt/lists"}