{"id":19232732,"url":"https://github.com/makeomatic/ms-users-haproxy","last_synced_at":"2025-08-13T01:36:03.288Z","repository":{"id":42000650,"uuid":"450393157","full_name":"makeomatic/ms-users-haproxy","owner":"makeomatic","description":"HAProxy JWT token verification and blacklist plugin","archived":false,"fork":false,"pushed_at":"2022-04-19T16:40:20.000Z","size":220,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-01-05T00:24:31.330Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/makeomatic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-01-21T07:21:59.000Z","updated_at":"2022-11-14T01:19:28.000Z","dependencies_parsed_at":"2022-08-12T02:00:15.456Z","dependency_job_id":null,"html_url":"https://github.com/makeomatic/ms-users-haproxy","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeomatic%2Fms-users-haproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeomatic%2Fms-users-haproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeomatic%2Fms-users-haproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/makeomatic%2Fms-users-haproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/makeomatic","download_url":"https://codeload.github.com/makeomatic/ms-users-haproxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240310872,"owners_count":19781341,"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-11-09T16:07:19.390Z","updated_at":"2025-02-23T11:40:48.430Z","avatar_url":"https://github.com/makeomatic.png","language":"JavaScript","readme":"# HAPROXY JWT verification helper\n\nProvides JWT token verification script for HAProxy and Service that performs token validation.\n\n## Contents\n\n\u003c!-- @import \"[TOC]\" {cmd=\"toc\" depthFrom=1 depthTo=6 orderedList=false} --\u003e\n\n\u003c!-- code_chunk_output --\u003e\n\n- [HAPROXY JWT verification helper](#haproxy-jwt-verification-helper)\n  - [Contents](#contents)\n  - [Supported algorithms](#supported-algorithms)\n  - [Verification process](#verification-process)\n  - [Token Server](#token-server)\n    - [Installation](#installation)\n  - [HaProxy `verify-jwt` script](#haproxy-verify-jwt-script)\n    - [Installation](#installation-1)\n      - [Manual](#manual)\n      - [DOCKER image](#docker-image)\n      - [Configuration](#configuration)\n        - [Sample `haproxy.cfg`:](#sample-haproxycfg)\n        - [JWT Signing Keys](#jwt-signing-keys)\n  - [Request Headers and TXN vars](#request-headers-and-txn-vars)\n\n\u003c!-- /code_chunk_output --\u003e\n\n## Supported algorithms\n\n* HMAC{any} - secret based signature verification\n* RS/HS/ES{any} - public key verification\n\n## Verification process\n\n1. Verify the signature of the provided JWT token using the provided list of keys. Supports only `Authorization: JWT {token}` headers\n\n2. Verify the token payload and expiration using the `token-server` sidecar.\n\n## Token Server\n\nProvides caching and validation logic for the token verification process.\nBuilt on top of the `Microfleet`,`makeomatic/ms-users` and `Fastify`.\nUsed by the HaProxy LUA script as backend.\n\n### Installation\n\nBuild and deploy container image from `Dockerfile.token-server` file.\nConfigure HaProxy backend to monitor and use this server.\n\n```shell \n$@\u003e: docker build -f ./Dockerfile.token-server -t token-server .\n```\n\nSee `src/config` or `test/config` and consult https://github.com/microfleet/core for configuration examples.\n\n## HaProxy `verify-jwt` script\n\n### Installation\n\n#### Manual\nCopy `./src/lua` contents into `/usr/local/lib/lua/5.3/` and install dependencies.\n\n**Dependencies**\n\n```shell\n\u003e luarocks install lua-cjson 2.1.0-1;\n\u003e luarocks install LuaSocket;\n\u003e luarocks install luaossl;\n```\n\n#### DOCKER image\n\nOr just use `Dockerfile` to `docker build` self-contained `haproxy` image.\n\n```shell \n$@\u003e: docker build -f ./Dockerfile -t haproxy-jwt .\n```\n\n#### Configuration\n\n* `JWT_JWKS_FILE` - File that contains JWT verification keys.\n* `JWT_JWKS_URL` - Url of the file that contains JWT verification keys.\n* `JWT_SYNC_INTERVAL` - Seconds interval for the verification keys update.\n* `JWT_CACHE_TTL` - Seconds to cache `token-server` response.\n* `JWT_TOKEN_SERVER_BACKEND` - Backend that monitors `token-server`s and to resolve DNS to IP address.\n\n##### Sample `haproxy.cfg`:\n\n```conf\nglobal\n  setenv JWT_JWKS_FILE /usr/local/etc/haproxy/keys.json\n  setenv JWT_JWKS_URL http://host/keys.json\n  setenv JWT_SYNC_INTERVAL 400\n  setenv JWT_CACHE_TTL 3\n  setenv JWT_TOKEN_SERVER_BACKEND jwt-token-server\n\n  lua-load /usr/local/lib/lua/5.3/verify-jwt.lua\n\nlisten fe_main\n    bind :8080\n    http-request lua.verify-jwt\n    # ...\n\nbackend jwt-token-server\n  # server s1 host.docker.internal:4000 check\n  server s1 tester:4000 check inter 1s fall 5 rise 1\n\n```\n\n##### JWT Signing Keys\n\nSet `JWT_JWKS_FILE` or `JWT_JWKS_URL` source. JWT signature verification keys should be provided using specific structure:\n\n```json\n// keys.json\n[\n  {\n    \"kid\": \"keyID\",\n    \"secret\": \"your-super-secure-secret\" \n  },\n  {\n    \"kid\": \"keyID\",\n    \"cert\": \"contents of the public key\" \n  }\n]\n```\n\n## Request Headers and TXN vars\n\nScript appends additional request headers after token validation process:\n\n* `x-tkn-valid` - `enum[0, 1]` - signature validation result. `1` == success\n* `x-tkn-reason` - `enum[E_TKN_*]` - validation result - see https://github.com/makeomatic/ms-users/src/constants.js errors\n* `x-tkn-body` - JSON encoded token body\n* `x-tkn-stateless|x-tkn-legacy` - token version \n\nAnd additional variables added to the HaProxy `TXN` scope:\n\n* `txn.tkn.valid`\n* `txn.tkn.reason`\n* `txn.tkn.payload.*`\n* `txn.tkn.stateless`\n* `txn.tkn.legacy`","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeomatic%2Fms-users-haproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmakeomatic%2Fms-users-haproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmakeomatic%2Fms-users-haproxy/lists"}