{"id":13646998,"url":"https://github.com/haproxytech/haproxy-lua-oauth","last_synced_at":"2025-12-30T00:17:16.959Z","repository":{"id":42790904,"uuid":"167039734","full_name":"haproxytech/haproxy-lua-oauth","owner":"haproxytech","description":"JWT Validation implementation for HAProxy Lua host","archived":false,"fork":false,"pushed_at":"2024-06-15T13:03:24.000Z","size":49,"stargazers_count":104,"open_issues_count":1,"forks_count":49,"subscribers_count":10,"default_branch":"master","last_synced_at":"2024-08-02T01:26:37.593Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/haproxytech.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":"2019-01-22T17:49:32.000Z","updated_at":"2024-07-22T15:51:40.000Z","dependencies_parsed_at":"2024-08-02T01:25:20.221Z","dependency_job_id":null,"html_url":"https://github.com/haproxytech/haproxy-lua-oauth","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haproxytech%2Fhaproxy-lua-oauth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haproxytech%2Fhaproxy-lua-oauth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haproxytech%2Fhaproxy-lua-oauth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/haproxytech%2Fhaproxy-lua-oauth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/haproxytech","download_url":"https://codeload.github.com/haproxytech/haproxy-lua-oauth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223880391,"owners_count":17219112,"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":[],"created_at":"2024-08-02T01:03:17.970Z","updated_at":"2025-12-30T00:17:16.905Z","avatar_url":"https://github.com/haproxytech.png","language":"Lua","readme":"# OAuth 2 library for HAProxy\n\nThis is a Lua library for HAProxy that will verify OAuth 2 JWT tokens.\n\n## Install\n\nThe `jwtverify.lua` file has these dependencies:\n\n* base64 (included in this repository)\n* [lua-json](https://github.com/rxi/json.lua)\n* [luaossl](https://github.com/wahern/luaossl)\n* [luasocket](https://github.com/diegonehab/luasocket)\n\nInstall like so:\n\n```\ngit clone https://github.com/haproxytech/haproxy-lua-oauth.git\ncd haproxy-lua-oauth\nchmod +x ./install.sh\nsudo ./install.sh luaoauth\n```\n\nThis installs jwtverify.lua and its dependencies to **/usr/local/share/lua/5.4/jwtverify.lua**.\n\n## Usage\n\n1. Sign up for an account with an OAuth token provider, such as https://auth0.com\n1. Create a new API on the Auth0 website\n1. Create a new \"Machine to Machine Application\" on the Auth0 website, optionally granting it \"scopes\"\n1. Download the public key certificate for your application on the Auth0 website via *Applications \u003e My App \u003e Settings \u003e Show Advanced Settings \u003e Certificates \u003e Download Certificate*. Auth0 signs tokens using this key. Convert it  using `openssl x509 -pubkey -noout -in ./mycert.pem \u003e pubkey.pem`.\n1. Update the HAProxy configuration file by:\n    * Copy *haproxy-example.cfg* to **/etc/haproxy/haproxy.cfg** and restart HAProxy via `sudo systemctl restart haproxy`\n    * *or* run it from this directory via `sudo haproxy -f ./haproxy-example.cfg`\n1. Get a JSON web token (JWT) from your authentication server by following the *Quick Start* on the Auth0 website, under the Applications tab, for your Machine to Machine application.\n1. Make requests to your API and attach the JWT in the Authorization header. You should get a successful response.\n\n## Supported Signing Algorithms\n\n* RS256\n* HS256\n* HS512\n\n## Support for multiple audiences\n\nThis library support specifying multiple audience values in the JWT token. They should be specified as a JSON array of strings.\nYou can also accept multiple audience values in the `OAUTH_AUDIENCE` environment variable in the **haproxy.cfg** file. Separate each value\nwith a space and surround it with double quotes:\n\n```\nsetenv OAUTH_AUDIENCE \"https://api.mywebsite.com https://api2.mywebsite.com\"\n```\n\n## Output variables\n\nAfter calling `http-request lua.jwtverify`, you get access to variables for each of the claims in the token.\n\n*Examples*\n\n* `var(txn.oauth.aud)`\n* `var(txn.oauth.clientId)`\n* `var(txn.oauth.iss)`\n* `var(txn.oauth.scope)`\n\nFor example, you could track rate limiting based on the clientId or set different rate limit thresholds based on the scope.\n\n## Example\n\nTry it out using the Docker Compose.\n\n1. Sign up for a free account at https://auth0.com/ and create a new API.\n1. Give the API any name, such as \"My OAuth Test\" and set the identifier to \"https://api.mywebsite.com\".\n1. Once created, go to the API's \"Permissions\" tab and add permissions (aka scopes) that grant users different levels of access. The colon syntax is just a personal style, and colons do not mean anything special.\n\n   | permission  | description           |\n   |-------------|-----------------------|\n   | read:myapp  | Read access to my app |\n   | write:myapp | Write access to myapp | \n\n1. Now that you have an API defined in Auth0, add an application that is allowed to authenticate to it. Go to the \"Applications\" tab and add a new \"Machine to Machine Application\" and select the API you just created. Give it the \"read:myapp\" and \"write:myapp\"permissions (or only one or the other).\n1. On the Settings page for the new application, go to **Advanced Settings \u003e Certificates** and download the certificate in PEM format. HAProxy will validate the access tokens against this certificate, which was signed by the OAuth provider, Auth0.\n\n1. Convert it first using `openssl x509 -pubkey -noout -in ./mycert.pem \u003e pubkey.pem` and save **pubkey.pem** to **/example/haproxy/pem/pubkey.pem**.\n1. Edit **example/haproxy/haproxy.cfg**: \n\n   * replace the `OAUTH_ISSUER` variable in the global section with the Auth0 domain URL with your own, such as https://myaccount.auth0.com/. \n   * replace the `OAUTH_AUDIENCE` variable with your API name in Auth0, such as \"https://api.mywebsite.com\". \n   * replace the `OAUTH_PUBKEY_PATH` variable with the path to your PEM certificate. (also update the docker-compose file)\n\n1. Create the environment with Docker Compose:\n    ```\n    $ docker compose -f docker-compose.ubuntu.example.yml build\n    $ docker compose -f docker-compose.ubuntu.example.yml up\n    ```\n1. Get a JSON web token (JWT) from your authentication server by going to your application on the Auth0 website and following the *Quick Start*.\n1. Make requests to https://localhost/api/myapp and attach the JWT in the Authorization header. You should get a successful response.\n\n   ```\n   $ curl --request GET \\\n      -k \\\n      --url https://localhost/api/myapp \\\n      --header 'authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlJEVkNSVFZHTmpZNU5rVTJSVUV3TnpoRk56UkJRalU0TjBFeU5EWTNSRU01TWtaRFJqTkNNUSJ9.eyJpc3MiOiJodHRwczovL25pY2tyYW00NC5hdXRoMC5jb20vIiwic3ViIjoicm9DTHRDTlZycW0zNmVYTzJxcE84cjEzeFBmQno1NklAY2xpZW50cyIsImF1ZCI6Imh0dHBzOi8vYXBpLm15d2Vic2l0ZS5jb20iLCJpYXQiOjE2NDgzMTQ2NjAsImV4cCI6MTY0ODQwMTA2MCwiYXpwIjoicm9DTHRDTlZycW0zNmVYTzJxcE84cjEzeFBmQno1NkkiLCJzY29wZSI6InJlYWQ6bXlhcHAgd3JpdGU6bXlhcHAiLCJndHkiOiJjbGllbnQtY3JlZGVudGlhbHMifQ.tEhJ0hKlqy9KRrS00we1Z6Y0CwGg5tAOmZ3qQYLYEwl1uymZ8OfJD9iGgPe5QhLJCTD-iwC18hWSwBMzNRLrjcjp1__hHOOyJRRoqekezS7NoHCMOKGLRis5EcfXMyb58yVxwrKIovHSRaEf0emg5NovQ2bdI3UpMThXnzlLhIH_SX5yRUtTxQ_qvO7xS9lZBNVYG9lYlNtU_Ih6dKCKNRUrMm8xsj2jLyR5_v3LcxgwzhK2VF01DZ9wyEgfHgs3H2AP6yJEZkmd9B1chO5Xf3f4klujsxvAb6RqTCwpGWmjRPY6SENkY2QX-PHOYVAc4zPvuauwx9Ojd4khA_KKfA'\n   ```\n\n   A successful response:\n\n   ```\n   [\"robo-hamster\",\"space-hamster\",\"commando-hamster\",\"pirate-hmaster\"]\n   ```","funding_links":[],"categories":["Lua"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaproxytech%2Fhaproxy-lua-oauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhaproxytech%2Fhaproxy-lua-oauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhaproxytech%2Fhaproxy-lua-oauth/lists"}