A lightweight, self-hosted authentication gateway built with Go, Gin, and Keycloak, designed to simplify authentication in microservices architectures.
🚀 Why I built short-auth
Authentication is one of those things that can become unnecessarily complicated when building backend systems, especially microservices.
You have two common options:
- Managed authentication services like Auth0 and Clerk. They're convenient, but costs can grow as your application scales.
- Self-hosted Identity Providers like Keycloak. They're powerful and flexible, but integrating them directly into your applications requires dealing with clients, scopes, OAuth2/OIDC flows, token lifecycles, roles, permissions, and more.
Keycloak is an excellent Identity Provider. However, I wanted a simpler way to use its capabilities without having to handle all its configuration and integration details in every project.
What if we could put a lightweight API layer on top of Keycloak and get a straightforward authentication service that works across multiple backend applications?
That's the idea behind short-auth.
🏗️ How it works
short-auth combines two main components:
- Go + Gin: Provides the authentication API, middleware, and local token verification.
- Keycloak: Handles identity management, user authentication, and OAuth2/OIDC flows.
Both are packaged into a single Docker image.
The architecture separates authentication operations from token verification:
1. Authentication operations
Registration, login, password management, and other identity operations are delegated to Keycloak through its APIs.
2. Token verification
Instead of requesting token validation from Keycloak on every incoming request, short-auth verifies JWT signatures locally using cached RSA public keys obtained through JWKS.
This allows downstream microservices to validate tokens without making an external Identity Provider request for every verification.
✨ Key Features
Here's what short-auth currently provides:
- 🔐 Authentication API: Register, Login, Refresh, Logout, Change Password, and Forgot Password.
- ⚡ Local JWT Verification: RSA signature verification using cached JWKS public keys.
- 🌐 Google OAuth2: Preconfigured social login integration.
- 🛡️ Role-Based Access Control: Authentication middleware and role enforcement.
- 🍪 Secure Cookies: HttpOnly, Secure, and SameSite support.
- 🚦 Rate Limiting: 64-shard in-memory rate limiter to reduce lock contention under concurrency.
- 🔄 Refresh Token Rotation: Token rotation and revocation.
- 🗄️ Database Support: PostgreSQL and MySQL.
- 📦 Single Docker Image: Go authentication gateway and Keycloak packaged together.
- 🔄 Automatic Database Initialization: Keycloak provisions its database tables on first startup.
📊 Performance Benchmarks
One of the interesting parts of this project was optimizing local JWT verification.
I used Grafana k6 and hey to benchmark the verification endpoint under concurrent load.
Here are the recorded results:
| Metric | Result |
|---|---|
| Peak Throughput / Arrival Rate | 10,000 RPS |
| Verification Latency | 489.5 µs |
| Total Requests | 439,362 |
| HTTP Errors | 0.00% |
The tests were performed on both PostgreSQL and MySQL integration setups.
The benchmark results, execution logs, and tuning notes are available in the repository.
These numbers represent the tested environment, not a guarantee of identical performance in every deployment.
🐳 Getting Started
The easiest way to try short-auth is with Docker Compose.
1. Clone the repository
git clone https://github.com/mohnasr137/short-auth.git cd short-auth 2. Configure your environment
cp .env.example .env Configure your database connection and credentials in .env.
3. Start the service
docker compose up -d 4. Check the health endpoint
curl http://localhost:3000/health On the first startup, Keycloak initializes its database tables and imports the authentication realm. This may take around 20–40 seconds.
You can also use the provided integration examples to run short-auth with PostgreSQL or MySQL.
🔌 API Overview
All authentication endpoints are prefixed with /api/auth.
| Method | Endpoint | Description |
|---|---|---|
| POST | /register | Register a user |
| POST | /login | Authenticate and issue tokens |
| POST | /refresh | Refresh tokens |
| POST | /logout | Revoke session |
| GET | /verify | Verify access token |
| GET | /me | Get authenticated user |
| PUT | /change-password | Change password |
| POST | /forgot-password | Request password reset |
| GET | /google | Start Google OAuth2 |
A ready-to-use Postman collection is also included in the repository.
🔮 What's Next?
short-auth is still evolving.
My goal is to make it easier for backend developers to integrate self-hosted authentication into their applications without having to build and maintain the entire authentication infrastructure themselves.
There are still areas I'd like to improve, and feedback from other developers would be extremely valuable.
🤝 I'd Love Your Feedback
I'm particularly interested in hearing your thoughts on:
- Would you use a dedicated authentication gateway instead of integrating Keycloak directly into each microservice?
- What do you think about packaging Go and Keycloak in a single container?
- Are there architectural or security concerns you'd address differently?
- What features would make a project like this more useful in real-world applications?
If you're interested in the project, contributions, issues, and suggestions are welcome.
🔗 GitHub: https://github.com/mohnasr137/short-auth
🐳 Docker Hub: https://hub.docker.com/r/mohnasr137/short-auth
Built with Go. Powered by Keycloak. Open Source.
Thanks for reading! 🚀