DEV Community

mohnasr137
mohnasr137

Posted on

Building a Self-Hosted Authentication Gateway with Go and Keycloak

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
Enter fullscreen mode Exit fullscreen mode

2. Configure your environment

cp .env.example .env
Enter fullscreen mode Exit fullscreen mode

Configure your database connection and credentials in .env.

3. Start the service

docker compose up -d
Enter fullscreen mode Exit fullscreen mode

4. Check the health endpoint

curl http://localhost:3000/health
Enter fullscreen mode Exit fullscreen mode

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! ๐Ÿš€

Top comments (0)