{"id":22268122,"url":"https://github.com/curityio/nginx-lua-oauth-proxy-plugin","last_synced_at":"2025-07-28T12:30:59.576Z","repository":{"id":40271449,"uuid":"390699535","full_name":"curityio/nginx-lua-oauth-proxy-plugin","owner":"curityio","description":"A LUA plugin for getting access tokens from encrypted cookies. The plugin implements the OAuth Proxy component from the Token Handler pattern.","archived":false,"fork":false,"pushed_at":"2024-06-14T16:55:07.000Z","size":217,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-06-14T18:19:54.678Z","etag":null,"topics":["api-gateway","nginx","oauth-proxy","oauth2","token-handler"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/curityio.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}},"created_at":"2021-07-29T11:21:45.000Z","updated_at":"2024-06-14T16:57:06.000Z","dependencies_parsed_at":"2024-06-05T21:05:31.201Z","dependency_job_id":null,"html_url":"https://github.com/curityio/nginx-lua-oauth-proxy-plugin","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fnginx-lua-oauth-proxy-plugin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fnginx-lua-oauth-proxy-plugin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fnginx-lua-oauth-proxy-plugin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/curityio%2Fnginx-lua-oauth-proxy-plugin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/curityio","download_url":"https://codeload.github.com/curityio/nginx-lua-oauth-proxy-plugin/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227905532,"owners_count":17837906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api-gateway","nginx","oauth-proxy","oauth2","token-handler"],"created_at":"2024-12-03T11:11:37.038Z","updated_at":"2024-12-03T11:11:37.603Z","avatar_url":"https://github.com/curityio.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OAuth Proxy Plugin for NGINX LUA Systems\n\n[![Quality](https://img.shields.io/badge/quality-test-yellow)](https://curity.io/resources/code-examples/status/)\n[![Availability](https://img.shields.io/badge/availability-binary-blue)](https://curity.io/resources/code-examples/status/)\n\nA LUA plugin that is used during API calls from SPA clients, to forward JWTs to APIs.\\\nThis is part of a `Backend for Frontend` solution for SPAs, in line with [best practices for browser based apps](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps).\n\n## The Token Handler Pattern\n\nThe [Token Handler Pattern](https://curity.io/resources/learn/the-token-handler-pattern/) is a modern evolution of a Backend for Frontend approach.\\\nThe SPA uses only SameSite encrypted HTTP Only cookies in the browser, and sends them during API requests.\\\nThis plugin performs the role of an `OAuth Proxy` in this solution, to make API calls work seamlessly:\n\n![Logical Components](/images/logical-components.png)\n\nThe plugin translates from encrypted cookies to tokens, so that APIs receive JWTs in the standard way.\n\n## Components\n\nThe plugin can be used standalone, or in conjunction with the [Phantom Token Plugin](https://curity.io/resources/learn/phantom-token-pattern/):\n\n![API Flow](/images/api-flow.png)\n\nSee also the following resources:\n\n- The [Example SPA](https://github.com/curityio/web-oauth-via-bff), which acts as a client to this plugin.\n- The [OAuth Agent API](https://github.com/curityio/token-handler-node-express), which issues the secure cookies for the SPA.\n\n## Installation\n\n### Kong API Gateway\n\nIf you are using luarocks, execute the following command to install the plugin:\n\n```bash\nluarocks install kong-oauth-proxy 1.3.0\n```\n\nOr deploy the .lua files into Kong's plugin directory, eg `/usr/local/share/lua/5.1/kong/plugins/oauth-proxy`.\n\n### OpenResty\n\nIf you are using luarocks, execute the following command to install the plugin:\n\n```bash\nluarocks install lua-resty-oauth-proxy 1.3.0\n```\n\nOr deploy the `access.lua` file to `resty/oauth-proxy.lua`, where the resty folder is in the `lua_package_path`.\\\nA typical install location for LUA files is at `/usr/local/openresty/luajit/share/lua/5.1/resty`.\n\n## Required Configuration Directives\n\nAll of the settings in this section are required:\n\n#### cookie_name_prefix\n\n\u003e **Syntax**: **`cookie_name_prefix`** `string`\n\u003e\n\u003e **Context**: `location`\n\nThe prefix used in the SPA's cookie name, typically representing a company or product name.\\\nThe value supplied must not be empty, and `example` would lead to full cookie names such as `example-at`.\n\n#### encryption_key\n\n\u003e **Syntax**: **`encryption_key`** `string`\n\u003e\n\u003e **Context**: `location`\n\nThis must be a 32 byte encryption key expressed as 64 hex characters.\\\nIt is used to decrypt AES256 encrypted secure cookies.\\\nThe key is initially generated with a tool such as `openssl`, as explained in Curity tutorials.\n\n#### trusted_web_origins\n\n\u003e **Syntax**: **`trusted_web_origins`** `string[]`\n\u003e\n\u003e **Context**: `location`\n\nA whitelist of at least one web origin from which the plugin will accept requests.\\\nMultiple origins could be used in special cases where cookies are shared across subdomains.\n\n#### cors_enabled\n\n\u003e **Syntax**: **`cors_enabled`** `boolean`\n\u003e\n\u003e **Default**: *true*\n\u003e\n\u003e **Context**: `location`\n\nWhen enabled, the OAuth proxy returns CORS response headers on behalf of the API.\\\nWhen an origin header is received that is in the trusted_web_origins whitelist, response headers are written.\\\nThe [access-control-allow-origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin) header is returned, so that the SPA can call the API.\\\nThe [access-control-allow-credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials) header is returned, so that the SPA can send secured cookies to the API.\n\n## Optional Configuration Directives\n\n#### allow_tokens\n\n\u003e **Syntax**: **`allow_tokens`** `boolean`\n\u003e\n\u003e **Default**: *false*\n\u003e\n\u003e **Context**: `location`\n\nIf set to true, then requests that already have a bearer token are passed straight through to APIs.\\\nThis can be useful when web and mobile clients share the same API routes.\n\n#### remove_cookie_headers\n\n\u003e **Syntax**: **`remove_cookie_headers`** `boolean`\n\u003e\n\u003e **Default**: *true*\n\u003e\n\u003e **Context**: `location`\n\nIf set to true, then cookie and CSRF headers are not forwarded to APIs.\\\nThis provides cleaner requests to APIs, which only receive a JWT in the HTTP Authorization header.\n\n#### cors_allow_methods\n\n\u003e **Syntax**: **`cors_allow_methods`** `string[]`\n\u003e\n\u003e **Default**: *['OPTIONS', 'GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE']*\n\u003e\n\u003e **Context**: `location`\n\nWhen CORS is enabled, these values are returned in the [access-control-allow-methods](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Methods) response header.\\\nThe SPA is then allowed to call a particular API endpoint with those HTTP methods (eg GET, POST).\\\nA '*' wildcard value should not be configured here, since it will not work with credentialed requests.\n\n#### cors_allow_headers\n\n\u003e **Syntax**: **`cors_allow_headers`** `string[]`\n\u003e\n\u003e **Default**: *['x-example-csrf']*\n\u003e\n\u003e **Context**: `location`\n\nWhen CORS is enabled, the plugin returns these values in the [access-contol-allow-headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers) response header.\\\nInclude here any additional [non-safelisted request headers](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_request_header) that the SPA needs to send in API requests.\\\nTo implement data changing requests, include the CSRF request header name, eg `x-example-csrf`.\\\nA '*' wildcard value should not be configured here, since it will not work with credentialed requests.\n\n#### cors_expose_headers\n\n\u003e **Syntax**: **`cors_expose_headers`** `string[]`\n\u003e\n\u003e **Default**: *[]*\n\u003e\n\u003e **Context**: `location`\n\nWhen CORS is enabled, the plugin returns these values in the [access-contol-expose-headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers) response header.\\\nInclude here any additional [non-safelisted response headers](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header) that the SPA needs to read from API responses.\\\nA '*' wildcard value should not be configured here, since it will not work with credentialed requests.\n\n#### cors_max_age\n\n\u003e **Syntax**: **`cors_max_age`** `number`\n\u003e\n\u003e **Default**: *86400*\n\u003e\n\u003e **Context**: `location`\n\nWhen CORS is enabled, the plugin returns this value in the [access-contol-max-age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age) response header.\\\nWhen a value is configured, this prevents excessive pre-flight OPTIONS requests to improve efficiency.\n\n## Example Configurations\n\nStandard settings would be expressed similar to the following if expressed in an nginx configuration file:\n\n```nginx\nlocal config = {\n    cookie_name_prefix = 'example',\n    encryption_key = '4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50',\n    trusted_web_origins = {\n        'http://www.example.com'\n    },\n    cors_enabled = true\n}\n```\n\nThe equivalent Kong configuration is expressed via YAML when using declarative configuration:\n\n```yaml\nplugins:\n  - name: oauth-proxy\n    config:\n      cookie_name_prefix: example\n      encryption_key: 4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50\n      trusted_web_origins:\n      - http://www.example.com\n      cors_enabled: true\n```\n\nAll API endpoints will then return these CORS headers to browsers in response headers:\n\n```text\naccess-control-allow-origin: http://www.example.com\naccess-control-allow-credentials: true\naccess-control-allow-methods: OPTIONS,HEAD,GET,POST,PUT,PATCH,DELETE\naccess-control-allow-headers: x-example-csrf\naccess-control-max-age: 86400\n```\n\nIf you prefer you can override default settings:\n\n```text\nlocal config = {\n    cookie_name_prefix = 'example',\n    encryption_key = '4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50',\n    trusted_web_origins = {\n        'http://www.example.com'\n    },\n    cors_enabled = true,\n    allow_tokens = false,\n    remove_cookie_headers = true,\n    cors_allow_methods = {\n        'OPTIONS', 'GET', 'POST'\n    },\n    cors_allow_headers = {\n        'my-header',\n        'x-example-csrf'\n    },\n    cors_expose_headers = {\n    },\n    cors_max_age = 600\n}\n```\n\nOr in Kong this would be configured like this:\n\n```yaml\nplugins:\n  - name: oauth-proxy\n    config:\n      cookie_name_prefix: example\n      encryption_key: 4e4636356d65563e4c73233847503e3b21436e6f7629724950526f4b5e2e4e50\n      trusted_web_origins:\n      - http://www.example.com\n      cors_enabled: true\n      allow_tokens: false\n      remove_cookie_headers: true\n      cors_allow_methods:\n      - OPTIONS\n      - GET\n      - POST\n      cors_allow_headers:\n      - my-header\n      - x-example-csrf\n      cors_expose_headers: []\n      cors_max_age: 600\n```\n\nIf you prefer you can configure `cors_enabled=false`, in which case you'll need to handle CORS in your API.\n\n## Deployment\n\nThe example [Docker Compose File](/docker/docker-compose.yml) provides OpenResty and Kong deployment examples.\n\n## Development and Testing\n\nThe following resource provides further details on how to make code changes to this repo:\n\n- [Wiki](https://github.com/curityio/nginx-lua-oauth-proxy-plugin/wiki)\n\n## More Information\n\nPlease visit [curity.io](https://curity.io/) for more information about the Curity Identity Server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fnginx-lua-oauth-proxy-plugin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcurityio%2Fnginx-lua-oauth-proxy-plugin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcurityio%2Fnginx-lua-oauth-proxy-plugin/lists"}