{"id":23300396,"url":"https://github.com/gregorykogan/jwt-microservice","last_synced_at":"2026-04-04T22:32:49.327Z","repository":{"id":268168656,"uuid":"903412801","full_name":"GregoryKogan/jwt-microservice","owner":"GregoryKogan","description":"A high-performance JWT authentication microservice written in Go, featuring Redis caching and Docker support.","archived":false,"fork":false,"pushed_at":"2025-06-17T21:36:14.000Z","size":57,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-26T11:49:57.972Z","etag":null,"topics":["authentication","auto-logout","caching","docker","docker-compose","go","high-performance","jwt","load-balancing","microservice","nginx","redis","security","structured-logging","testing","token-refresh","uuid"],"latest_commit_sha":null,"homepage":"","language":"Go","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/GregoryKogan.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":"2024-12-14T14:40:51.000Z","updated_at":"2025-06-17T21:36:17.000Z","dependencies_parsed_at":"2024-12-14T21:27:28.407Z","dependency_job_id":"20fd3641-fd59-4e9b-838d-a73b5983d3fa","html_url":"https://github.com/GregoryKogan/jwt-microservice","commit_stats":null,"previous_names":["gregorykogan/jwt-microservice"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/GregoryKogan/jwt-microservice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fjwt-microservice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fjwt-microservice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fjwt-microservice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fjwt-microservice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GregoryKogan","download_url":"https://codeload.github.com/GregoryKogan/jwt-microservice/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GregoryKogan%2Fjwt-microservice/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31416770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T20:09:54.854Z","status":"ssl_error","status_checked_at":"2026-04-04T20:09:44.350Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["authentication","auto-logout","caching","docker","docker-compose","go","high-performance","jwt","load-balancing","microservice","nginx","redis","security","structured-logging","testing","token-refresh","uuid"],"created_at":"2024-12-20T09:14:35.831Z","updated_at":"2026-04-04T22:32:49.307Z","avatar_url":"https://github.com/GregoryKogan.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# JWT Microservice \u0026nbsp; ![License MIT](https://img.shields.io/badge/license-MIT-green) ![Docker Ready](https://img.shields.io/badge/docker-ready-blue)\n\nA high-performance **JWT authentication microservice** written in Go, featuring Redis caching and Docker support.\n\n## 🚀 Features\n\n- 🔐 **JWT-based authentication**\n- ⚡ **High-performance Redis caching**\n- ♻️ **Token refresh mechanism**\n- 🔒 **Auto-logout functionality**\n- 📝 **Structured logging**\n- 🐳 **Docker support**\n- 🌐 **Fast and lightweight**\n- 🧪 **Comprehensive test coverage**\n\n## 🛠️ Architecture\n\n```mermaid\ngraph LR\n    Client --\u003e NGINX[🔀 NGINX]\n    subgraph Docker Network\n        NGINX --\u003e DNS[📡 Docker DNS]\n        DNS --\u003e JWT1[🟢 JWT Service 1]\n        DNS --\u003e JWT2[🟢 JWT Service 2]\n        DNS --\u003e JWTn[🟢 JWT Service n]\n    end\n    subgraph Shared State\n        direction LR\n        JWT1 --\u003e Redis[(💾 Redis)]\n        JWT2 --\u003e Redis\n        JWTn --\u003e Redis\n    end\n```\n\n## 📚 API Endpoints\n\n| Endpoint        | Method | Description              | Auth Required |\n| --------------- | ------ | ------------------------ | ------------- |\n| `/ping`         | GET    | Health check endpoint    | ❌ No         |\n| `/login`        | POST   | Login and get token pair | ❌ No         |\n| `/refresh`      | POST   | Refresh token pair       | ✅ Yes        |\n| `/logout`       | POST   | Invalidate token pair    | ✅ Yes        |\n| `/authenticate` | GET    | Validate access token    | ✅ Yes        |\n\n## 🚀 Quick Start\n\n### 📋 Prerequisites\n\n- 🐳 **Docker**\n- 🛠️ **Docker Compose**\n\n### ⚖️ Scaling\n\nThe service supports horizontal scaling through Docker's built-in DNS-based load balancing:\n\n```bash\ndocker compose up --build --scale jwt=5\n```\n\nThis command will:\n\n- 🏃‍♂️ Start 5 instances of the JWT service\n- 🌐 Register them with Docker's DNS service\n- 🔄 Enable automatic load balancing through Docker's embedded DNS server\n- 💾 Maintain shared state through Redis\n\nNGINX acts as a reverse proxy, forwarding requests to the Docker DNS service, which routes them to the appropriate JWT service instance.\n\n### 🎯 Running Locally\n\n1. **Clone the repository**\n\n   ```bash\n   git clone https://github.com/GregoryKogan/jwt-microservice.git\n   cd jwt-microservice\n   ```\n\n2. **Choose a startup option:**\n\n#### 🚀 Single Instance\n\n```bash\ndocker compose up --build\n```\n\n#### ⚖️ Multiple Instances (Scaled)\n\n```bash\n# Start 5 instances with load balancing\ndocker compose up --build --scale jwt=5\n```\n\n#### 🛠️ Development Mode\n\n```bash\n# Live-reloading for single instance\ndocker compose up --build --watch\n\n# Live-reloading with multiple instances\ndocker compose up --build --watch --scale jwt=3\n```\n\nThe service will be available at **`http://localhost:4000`**.\n\n### ⚙️ Configuration\n\nThe service is configured via `config.yml`:\n\n```yaml\nserver:\n  port: 8080\n  max_processors: 2 # sets GOMAXPROCS\n\nlogging:\n  mode: text # text or json\n  level: debug\n\ncache:\n  host: cache\n  port: 6379\n\nauth:\n  issuer: jwt-microservice\n  access_lifetime: 15m\n  refresh_lifetime: 720h\n  auto_logout: 24h\n```\n\nAlso, take a look at the `docker-compose.yml` file for more configuration options such as CPU resource limits and port mappings.\n\n### ✅ Testing\n\nRun all tests with cache mocking:\n\n```bash\ngo test ./... -v\n```\n\n## 📊 Load Testing\n\nLoad testing is performed using **Grafana K6**. To execute the load tests with the `load-test` profile, run:\n\n```bash\ndocker compose --profile load-test up --build --scale jwt=5\n```\n\nThe xk6 dashboard will be available at **`http://localhost:5665`** during load testing.\n\n### 📈 Load Testing Results\n\n| Instances | CPU Limit per Instance | Max Processors | Avg Response Time | RPS  | Error Rate |\n| --------- | ---------------------- | -------------- | ----------------- | ---- | ---------- |\n| 1         | 0.1                    | 1              | 895.21ms          | 974  | 72.51%     |\n| 2         | 0.1                    | 1              | 274.59ms          | 1097 | 53.54%     |\n| 4         | 0.2                    | 2              | 8.07ms            | 1163 | 0.39%      |\n| 8         | 0.25                   | 2              | 6.7ms             | 1154 | 0.21%      |\n| 16        | 0.5                    | 4              | 15.84ms           | 978  | 0.59%      |\n| 32        | -                      | -              | 91.54ms           | 1031 | 1.81%      |\n\n\u003e **Note:** Charts and graphs are generated on the fly using **xk6**. Here's an example of the performance chart:\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/user-attachments/assets/73e77aee-91ca-45f1-a0b7-cf20ab32d08d\" alt=\"xk6-chart\" width=\"75%\" /\u003e\n\u003c/p\u003e\n\n## 🛡️ Security Features\n\n- 🔑 **UUID-based token tracking**\n- 🔄 **Token Rotation Mechanism**\n- ❌ **Automatic token invalidation**\n- ⏰ **Configurable token lifetimes**\n- 🔄 **Secure token refresh mechanism**\n- 🕒 **Auto-logout for inactive users**\n\n### 🔄 Token Rotation Mechanism\n\nThe service implements a secure **token rotation mechanism** to enhance security:\n\n- **Single-Use Refresh Tokens:** Each refresh token is valid for only one use. Upon using it to obtain a new token pair, the old refresh token is invalidated.\n- **Prevents Replay Attacks:** This mechanism mitigates the risk of replay attacks by ensuring that stolen or leaked refresh tokens cannot be reused.\n- **Seamless User Experience:** Token rotation happens transparently, providing continuous access without requiring the user to re-authenticate.\n\n## 🧩 API Usage Examples\n\n### 🔑 Login\n\n```bash\ncurl -X POST http://localhost:8080/login \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"user_id\": 1}'\n```\n\n### ♻️ Refresh Token\n\n```bash\ncurl -X POST http://localhost:8080/refresh \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"refresh\": \"your-refresh-token\"}'\n```\n\n### ✅ Authenticate\n\n```bash\ncurl -X GET http://localhost:8080/authenticate \\\n  -H \"Authorization: Bearer your-access-token\"\n```\n\n### 🚪 Logout\n\n```bash\ncurl -X POST http://localhost:8080/logout \\\n  -H \"Authorization: Bearer your-access-token\"\n```\n\n## 🤝 Contributing\n\n1. **Fork the repository**\n2. **Create your feature branch** (`git checkout -b feature/amazing-feature`)\n3. **Commit your changes** (`git commit -m 'Add amazing feature'`)\n4. **Push to the branch** (`git push origin feature/amazing-feature`)\n5. **Open a Pull Request**\n\n## 📄 License\n\nThis project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregorykogan%2Fjwt-microservice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregorykogan%2Fjwt-microservice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregorykogan%2Fjwt-microservice/lists"}