{"id":17047474,"url":"https://github.com/djmgit/resty-asap-proxy","last_synced_at":"2026-05-16T08:34:03.756Z","repository":{"id":104035936,"uuid":"582580014","full_name":"djmgit/resty-asap-proxy","owner":"djmgit","description":"Openresty based middle man proxy for generating and injecting asap token header on the fly.","archived":false,"fork":false,"pushed_at":"2023-01-01T18:56:56.000Z","size":87,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-29T13:27:21.203Z","etag":null,"topics":["asap","authentication","middleman","nginx","proxy","web"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/djmgit.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":"2022-12-27T09:13:41.000Z","updated_at":"2022-12-30T09:12:11.000Z","dependencies_parsed_at":null,"dependency_job_id":"b45263b8-c398-4cd9-b94a-f6878101cd00","html_url":"https://github.com/djmgit/resty-asap-proxy","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/djmgit/resty-asap-proxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djmgit%2Fresty-asap-proxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djmgit%2Fresty-asap-proxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djmgit%2Fresty-asap-proxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djmgit%2Fresty-asap-proxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/djmgit","download_url":"https://codeload.github.com/djmgit/resty-asap-proxy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/djmgit%2Fresty-asap-proxy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269969264,"owners_count":24505427,"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","status":"online","status_checked_at":"2025-08-11T02:00:10.019Z","response_time":75,"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":["asap","authentication","middleman","nginx","proxy","web"],"created_at":"2024-10-14T09:49:34.376Z","updated_at":"2026-05-16T08:33:58.721Z","avatar_url":"https://github.com/djmgit.png","language":"Lua","funding_links":[],"categories":[],"sub_categories":[],"readme":"# resty-asap-proxy\n\nresty-asap-proxy is a openresty based proxy which can generate asap tokens on the fly and inject them as headers into a request in order to\nauth with a asap authenticated service. This can be used as a middle man when a service which does not know/use asap needs to communnicate with\na service that uses asap as its primary auth framework. The upstream service must allow/whitelist the proxy and its asap issuer.\nIt goes without saying that the when using such a middle man proxy, the upstream service must have a way to verify the client service at application\nlevel to make sure the client is trusted.\n\n## What is ASAP?\n\nASAP stands for Atlassian service to service authentication Protocol, a mechanism used by a resource server to authenticate requests from the\nclient in a client-server communication scenario between software services. Its based on JWT. You can read the full specification \u003ca href=\"https://s2sauth.bitbucket.io/spec/\"\u003ehere\u003c/a\u003e.\n\n## What is Openresty?\n\nOpenresty is a server platform based on top of Nginx and comes bundled nginx-lua module. With Openresty you get the power of lua scripting with\nnginx out of the box. You can find more about it \u003ca href=\"https://openresty.org/en/\"\u003ehere\u003c/a\u003e.\n\n## Getting started\n\nresty-asap-proxy can be run directly on your system using openresty or via docker. I assume that you have already generated your asap keys. The public\nkey has been uploaded to the key server and the key and issuer is trusted by the upstream service. The private key will be used by the proxy\nserver to auth with the upstream service. The proxy assumes that the upstream server uses tls and uses [https] to forward. This can be changed in\nthe conf file.\nAlso the instructions are for Linux and MacOS, I have not tried running it on Windows, but it should\nnot be much different.\n\n### Running resty-asap-proxy on system without docker\n\n- First you need to make sure you have openresty installed on your system. You follow the instructions given on their official \u003ca href=\"https://openresty.org/en/\"\u003esite\u003c/a\u003e.\n\n- Clone this repo and open it in your terminal.\n\n- Export your asap issuer - ```export ASAP_ISSUER=\u003cyour asap issuer\u003e```. This is a issuer trusted by your targeted upstream service.\n- Export your asap private key - ```export ASAP_PRIVATE_KEY=\u003cthe asap private key\u003e```.\n\n- Create a directory for logs named logs using ```mkdir logs```. Nginx conf is configured to dump http access logs and error into logs/http.log.\n  You can modify the conf file if you want.\n  \n- Now you can run the server using ```openresty -p `pwd`/ -c conf/nginx.conf```. Additionally you can do a ```tail -f logs/http.log``` to keep\n  a watch on the logs.\n  \n- The proxy should be running on port 8080.\n\n### Running via Docker\n\n- Make sure you have Docker installed on your system.\n\n- Clone this repo and open it in your terminal.\n\n- Build the docker image using ```docker build -t resty-asap-proxy:v1 .```\n\n- Create and run the container using ```docker run -p 8080:8080 -e ASAP_ISSUER=\u003casap issuer\u003e -e ASAP_PRIVATE_KEY=\u003casap private key\u003e resty-asap-proxy:v1```\n\n- The proxy should be runing on port 8080. The access and error logs will be streamed to stdout.\n\n## Sending requests to upstream services using resty-asap-proxy\n\nThe proxy server expects you to send requests in a specific format. This format makes sure that the proxy is able to extract target service host, the\ntarget uri and the desired asap issuer form the request itself and generate the asap token.\nThe request format is -\n\n```http://127.0.0.1:8080/proxy/upstream_service_host/remaining_uri```\n\nIn short the uri should begin with **/proxy** then the upstream service host (fqdn) then the uri for the upstream host and url params if any.\n\nExmaple:\n```http://127.0.0.1:8080/proxy/myservice.mycompany.com/api/home/1```\n\nIf we use the above request url, resty-asap-proxy will use myservice.mycompany.com as the upstream service host, /api/home/1 as the target uri and\nasap audience as ```myservice``` that is the frist part of the domain or the service name. So basically the proxy will initiate a new request to\n```https://myservice.mycompany.com/api/home/1``` with the generated asap token in header.\n\n## How does resty-asap-proxy work?\n\nRequest flow:\n\n![Unable to load request flow image](resources/resty-asap.jpg?raw=true \"Request flow\")\n\nI will use the request url ```http://127.0.0.1:8080/proxy/myservice.mycompany.com/api/home/1``` for running through the request flow.\n\n- On receiving the request, resty-asap-proxy will execute the lua-resty-asap module lua script by calling the desired module function.\n\n- The lua script will capture the request_uri and will extract the following things from it:\n    - the upstream service host name - myservice.mycompany.com\n    - The upstream service uri - /api/home/1\n    - The asap audience which is basically the first part of the host name (pqdn) as of now - myservice\n\n- The lua script then invokes a python script which uses ```asap-authentication-python``` library to generate the asap token. The required asap private\n  key, asap issuer and audience is passed to the py script from lua via stdin. The lua script itself gets the asap issuer and asap private key from env\n  vars.\n \n- The py script sends the generated asap token to stdout.\n\n- The lua script reads the asap token from the stdout and injects it as the ```Authorization``` header in the request.\n\n- It is to be noted that the lua-resty-asap lua module uses the shell module provided by openresty to invoke the py script via non blocking IO.\n\n- Next the lua script populates the predefined nginx var ```target_host``` with the extracted upstream service host name. This var is used by\n  proxy_pass as the remote host. This is how we are able to dynamically decide the upstream service host per request on the fly. The target\n  service can be anything and the request will be accordingly proxied with correct asap token.\n  \n- Lastly the lua module sets the uri to the extracted target uri - ```/api/home/1```\n\n- Nginx finally will forward the request with proper uri to the desired target host via proxy_pass. The final outgoing request will be\n  ```https://myservice.mycompany.com/api/home/1```\n\n\n## NOTES\n\n- The lua-resty-asap module can be extracted from this repo and used with any openresty configuration.\n\n- Right now the proxy considers the upstream service name as the asap audience. The proxy needs a way to override this.\n\n- It always assumes the upstream service is behind tls.\n\n- The nginx conf is very minimalistic, it does not use server names etc. Thats done intentionally, please edit the conf as required. My primary focus\n  was the lua module.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjmgit%2Fresty-asap-proxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdjmgit%2Fresty-asap-proxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdjmgit%2Fresty-asap-proxy/lists"}