{"id":17871075,"url":"https://github.com/timwolla/haproxy-auth-request","last_synced_at":"2025-04-04T16:14:19.593Z","repository":{"id":28339417,"uuid":"116866778","full_name":"TimWolla/haproxy-auth-request","owner":"TimWolla","description":"auth-request allows you to add access control to your HTTP services based on a subrequest to a configured HAProxy backend.","archived":false,"fork":false,"pushed_at":"2024-12-17T19:40:38.000Z","size":91,"stargazers_count":154,"open_issues_count":4,"forks_count":31,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-03-28T15:07:36.846Z","etag":null,"topics":["authentication","authentication-service","haproxy","haproxy-lua","http","lua-script","subrequests"],"latest_commit_sha":null,"homepage":"https://bl.duesterhus.eu/20180119/","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/TimWolla.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":"2018-01-09T20:23:26.000Z","updated_at":"2025-03-16T18:45:08.000Z","dependencies_parsed_at":"2024-12-25T11:12:56.924Z","dependency_job_id":"8a2b94db-d9cf-4535-8b50-da20448c2303","html_url":"https://github.com/TimWolla/haproxy-auth-request","commit_stats":{"total_commits":95,"total_committers":6,"mean_commits":"15.833333333333334","dds":0.08421052631578951,"last_synced_commit":"3c1df73b07f4301318f98002b78b860cf89e54e4"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimWolla%2Fhaproxy-auth-request","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimWolla%2Fhaproxy-auth-request/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimWolla%2Fhaproxy-auth-request/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimWolla%2Fhaproxy-auth-request/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimWolla","download_url":"https://codeload.github.com/TimWolla/haproxy-auth-request/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247208145,"owners_count":20901570,"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":["authentication","authentication-service","haproxy","haproxy-lua","http","lua-script","subrequests"],"created_at":"2024-10-28T10:22:54.122Z","updated_at":"2025-04-04T16:14:19.570Z","avatar_url":"https://github.com/TimWolla.png","language":"Lua","readme":"# auth-request ![Test](https://github.com/TimWolla/haproxy-auth-request/workflows/Test/badge.svg)\n\nauth-request allows you to add access control to your HTTP services based on a\nsubrequest to a configured HAProxy backend. The workings of this Lua script are\nloosely based on the [ngx_http_auth_request_module] module for nginx.\n\n## Requirements\n\n- HAProxy 1.8.4+ (2.2.0+ recommended)\n  - Only the latest version of each HAProxy branch is supported.\n- `USE_LUA=1` must be set at compile time.\n- [haproxy-lua-http] must be available within the Lua path.\n  - A `json` library within the Lua path (dependency of haproxy-lua-http).\n  - With HAProxy 2.1.3+ you can use the [`lua-prepend-path`] configuration\n    option to specify the search path.\n\n## Usage\n\n1. Load this Lua script in the `global` section of your `haproxy.cfg`:\n    ```haproxy\n    global\n        # *snip*\n        lua-prepend-path /usr/share/haproxy/?/http.lua # If haproxy-lua-http is saved as /usr/share/haproxy/haproxy-lua-http/http.lua\n        lua-load /usr/share/haproxy/auth-request.lua\n    ```\n\n2. Define a backend that is used for the subrequests:\n    ```haproxy\n    backend auth_request\n        mode http\n        server auth_request 127.0.0.1:8080 check\n    ```\n\n3. Execute the subrequest in your frontend (as early as possible):\n    ```haproxy\n    frontend http\n        mode http\n        bind :::80 v4v6\n\n        # *snip*\n\n        # auth-request syntax:\n        #                             Backend name     Path to request\n        http-request lua.auth-request auth_request     /is-allowed\n\n        # auth-intercept syntax:                                           (Headers to copy)\n        #                               Backend name  Path         Method  Request  Success  Failure\n        http-request lua.auth-intercept auth_request  /is-allowed  HEAD    *        -        -\n    ```\n\n4. Act on the results:\n    ```haproxy\n    frontend http\n        # *snip*\n\n        http-request deny if ! { var(txn.auth_response_successful) -m bool }\n    ```\n\n### Parameters\n\nThe scripts receive a list of parameters used to build the authentication\nrequest:\n\n* **Backend name**: is the name of an HAProxy backend. See the\n[Inner Workings](#inner-workings) section.\n* **Path to request**: the request URL sent to the auth-request backend.\n\nThe following parameters are only available in the `auth-intercept` script:\n\n* **Method**: the HTTP method that should be used. Use an asterisk `*` to ask\n`auth-intercept` to copy the same method used by the client. `auth-request`\nuses the `HEAD` method.\n* **Headers to copy on Request**: a comma-separated list of a simplified glob\npattern that should match the HTTP header names to copy from the client to the\nauth-intercept backend. Use a dash `-` to not copy any header.\n* **Headers to copy on Success**: a comma-separated list of a simplified glob\npattern that should match the HTTP header names to copy from the auth-intercept\nbackend to the protected backend server, if the auth-intercept backend respond\nwith 2xx response code and the request succeed. All headers received from the\nauth-intercept will override headers with the same name provided by the client.\nUse `*` to copy all headers, or use a dash `-` to not copy any header. HAProxy\nvariables are always created, see the [Available Variables](#available-variables)\nsection.\n* **Headers to copy on Failure**: a comma-separated list of a simplified glob\npattern that should match the HTTP header names to copy from the auth-intercept\nbackend to the client, if the request failed. `auth-intercept` will use the\nsame HTTP method and body sent by the auth-intercept backend to respond to the\nclient, closing the transaction. The protected backend server will not be used.\nUse `*` to copy all headers. Use a dash `-` to not close the transaction and\nleave to the HAProxy configuration the task to deny the request based on the\n`txn.auth_response_successful` variable. HAProxy variables are always created,\nsee the [Available Variables](#available-variables) section.\n\nSimplified glob pattern: use an asterisk `*` to match any sequence of\ncharacters and `?` to match a single char. `*` will match any header name.\n`x-*` will match all header names started with `x-`. `x-????` will match\n`x-user` but will not match neither `x-token` nor `x-id`.\n\nHAProxy 2.1 or older: the On Failure param (the last one) will close the\ntransaction and respond to the client if the value is not a dash `-`, however\nthis feature is only supported on HAProxy 2.2 or newer. The only supported\noption on 2.1 and older is a dash `-`.\n\n### Available Variables\n\nauth-request uses HAProxy variables to communicate the results back to you. The\n[`var()` sample fetch] can be used to retrieve the variable contents.\n\nThe following list of variables may be set.\n\n\u003cdl\u003e\n\u003cdt\u003e\u003ccode\u003etxn.auth_response_successful\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\nSet to \u003ccode\u003etrue\u003c/code\u003e if the subrequest returns an HTTP status code in the\n\u003ccode\u003e2xx\u003c/code\u003e range. \u003ccode\u003efalse\u003c/code\u003e otherwise.\n\u003c/dd\u003e\n\n\u003cdt\u003e\u003ccode\u003etxn.auth_response_code\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\nThe HTTP status code of the subrequest. If the subrequest did not return a\nvalid HTTP response the value will be \u003ccode\u003e500\u003c/code\u003e.\n\u003c/dd\u003e\n\n\u003cdt\u003e\u003ccode\u003etxn.auth_response_location\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\nThe \u003ccode\u003elocation\u003c/code\u003e response header of the subrequest.\n\nThis variable is only set if the HTTP status code of the subrequest indicates a\nredirect (i.e. \u003ccode\u003e301\u003c/code\u003e, \u003ccode\u003e302\u003c/code\u003e, \u003ccode\u003e303\u003c/code\u003e,\n\u003ccode\u003e307\u003c/code\u003e, or \u003ccode\u003e308\u003c/code\u003e).\n\u003c/dd\u003e\n\n\u003cdt\u003e\u003ccode\u003ereq.auth_response_header.*\u003c/code\u003e\n\u003cdd\u003e\nThese variables store the subrequest’s response headers. The values of\nduplicate response headers will be merged with a comma.\n\nHAProxy variables may only contain alphanumeric characters, the dot\n(\u003ccode\u003e.\u003c/code\u003e), and an underscore \u003ccode\u003e_\u003c/code\u003e. Any non-alphanumeric\ncharacters will be replaced with an underscore to be representable. If the\nresponse contains duplicate response headers \u003cem\u003eafter\u003c/em\u003e normalizing the\nheader name the result for these headers will be undefined.\n\nNormalization examples:\n\u003cdl\u003e\n\u003cdt\u003e\u003ccode\u003eX-Authenticated-User\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003ccode\u003ereq.auth_response_header.x_authenticated_user\u003c/code\u003e\u003c/dd\u003e\n\u003cdt\u003e\u003ccode\u003eSuccess\u003c/code\u003e\u003c/dt\u003e\n\u003cdd\u003e\u003ccode\u003ereq.auth_response_header.success\u003c/code\u003e\u003c/dd\u003e\n\u003c/dl\u003e\n\nPlease note: The scope of the response header variables is \u003ccode\u003ereq\u003c/code\u003e\ncompared to \u003ccode\u003etxn\u003c/code\u003e for the other variables. The contents will no\nlonger be available during response processing to save memory. Copy the values\nof interest into a \u003ccode\u003etxn.\u003c/code\u003e variable if you need access them during\nresponse processing.\n\u003c/dd\u003e\n\u003c/dl\u003e\n\n## Inner Workings\n\nThe Lua script will make a HTTP request to the *first* server in the given\nbackend that is either marked as `UP` or that does not have checks enabled.\nThis allows for basic health checking of the auth-request backend. If you need\nmore complex processing of the request forward the auth-request to a separate\nHAProxy *frontend* that performs the required modifications to the request and\nresponse.\n\nThe requested URL is the one given in the second parameter.\n\nAny request headers will be forwarded as-is to the auth-request backend, with\nthe exception of the `content-length` header which will be stripped, because\nthe request body will not be forwarded.\n\n## Known limitations\n\n- The Lua script only supports basic health checking, without redispatching or\n  load balancing of any kind.\n- The backend must not be using TLS.\n\n[ngx_http_auth_request_module]: http://nginx.org/en/docs/http/ngx_http_auth_request_module.html\n[haproxy-lua-http]: https://github.com/haproxytech/haproxy-lua-http\n[`lua-prepend-path`]: http://cbonte.github.io/haproxy-dconv/2.1/configuration.html#lua-prepend-path\n[`var()` sample fetch]: http://cbonte.github.io/haproxy-dconv/2.2/configuration.html#7.3.2-var\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimwolla%2Fhaproxy-auth-request","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftimwolla%2Fhaproxy-auth-request","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftimwolla%2Fhaproxy-auth-request/lists"}