fenixkit

Posted on May 13

Why I stopped rolling my own auth and switched to Keycloak

#keycloak #dotnet #authentication #api

Every developer has built it at least once. A UsersController, a POST /auth/login endpoint, a PasswordHasher, a JwtService that generates tokens. It feels like the natural thing to do — auth is just another feature, right?

It isn't. And I learned that the hard way.

What "rolling your own JWT auth" actually means

On the surface it looks simple:

var token = new JwtSecurityToken(
    issuer: "myapp",
    claims: claims,
    expires: DateTime.UtcNow.AddHours(1),
    signingCredentials: credentials);

But that's just the token. The moment you decide to own your auth stack, you're signing up for all of this:

Password storage — hashing, salting, choosing the right algorithm (bcrypt? Argon2? PBKDF2?), migrating if you get it wrong
Refresh token rotation — storing refresh tokens, invalidating old ones, handling concurrent requests that race to refresh
Token revocation — JWTs are stateless, so revoking one before expiry means a blacklist, which means a database lookup on every request
Brute force protection — rate limiting login attempts, lockout logic, alerting
Forgot password flow — secure token generation, expiry, one-time use enforcement
Email verification — same problem
MFA — TOTP, backup codes, recovery flows
Session management — single sign-out, concurrent session limits
Security patches — when a vulnerability is found in your approach, you fix it

Together they are a significant, ongoing maintenance burden — and they have nothing to do with your actual product.

The moment I realised I was building an identity provider

I was three days into a project without doing a single line of domain code.

That's when it clicked. I wasn't building a feature. I was building an identity provider — badly, from scratch, under time pressure. Companies spend years hardening this stuff.

The question isn't "can I build this?" — of course you can. The question is "should I?"

What Keycloak actually is

Keycloak is an open-source identity and access management solution. It handles everything in the list above — and more — out of the box. You run it as a container, configure a realm, and your application stops caring about any of it.

Your API's only job becomes: validate the token.

// This is the entire auth setup in your API
builder.Services
    .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "http://localhost:8080/realms/myrealm";
        options.Audience  = "my-api-client";
    });

That's it. ASP.NET Core fetches the OIDC discovery document from Keycloak (/.well-known/openid-configuration), and validates every incoming token. No database lookup per request. No code to maintain.

But what about "JWT normal"?

When people say "just use JWT" they usually mean: generate tokens yourself, validate them yourself, store user data yourself. This is fine for a toy project or a quick internal tool.

The problem is that JWT is a token format, not an auth system. It tells you how to structure and sign a token. It tells you nothing about:

How to manage users
How to handle token revocation
How to implement refresh flows securely
How to add MFA later without rewriting everything

Keycloak uses JWT — it just handles all the surrounding complexity so you don't have to.

The honest trade-offs

Keycloak is not the right answer for every situation.

	Roll your own	Keycloak
Setup time	Fast initially	Slower initially
Maintenance	You own everything	Keycloak team maintains it
Flexibility	Total control	Configurable but opinionated
Resource usage	Minimal	Needs a container
MFA, SSO, social login	Build it yourself	Already there
Security patches	Your problem	Keycloak's problem

For a side project with no users yet — rolling your own might be fine. For anything with real users, a team, compliance requirements, or plans to grow — Keycloak wins on every axis that matters.

The .NET integration gotcha nobody warns you about

If you switch from rolling your own JWT to Keycloak in ASP.NET Core, there's one thing that will silently break: role claims.

ASP.NET Core remaps JWT claim names by default. sub becomes ClaimTypes.NameIdentifier, email becomes a long URN string — and roles gets ignored entirely because Keycloak puts realm roles in a non-standard location.

The fix is two lines, but you have to know to add them:

// Before builder.Services.AddAuthentication()
JwtSecurityTokenHandler.DefaultInboundClaimTypeMap.Clear();
JsonWebTokenHandler.DefaultInboundClaimTypeMap.Clear();

Without this, User.IsInRole("admin") always returns false and you spend an afternoon debugging a problem that isn't in your code.

You also need to tell the JWT Bearer middleware where Keycloak puts roles (in my case):

options.TokenValidationParameters = new()
{
    RoleClaimType = "roles",
    NameClaimType = "preferred_username",
    // ...
};

With these in place, [Authorize(Roles = "admin")] and User.IsInRole("admin") work exactly as expected.

The result

Once it's wired up, protecting any endpoint is a single line:

group.MapGet("/",        GetAll).RequireAuthorization("Authenticated");
group.MapDelete("/{id}", Delete).RequireAuthorization("AdminOnly");

Forgot password, MFA, social login, token revocation, brute force protection — all handled. You never wrote a PasswordHasher. You never debugged a refresh token rotation race condition. You just built your product.

Where to go from here

If you want to try Keycloak with .NET 8, the official docs are a reasonable starting point.

I spent time getting all of this right and packaged it into a starter kit — FenixKit MongoDB + Keycloak Edition — a .NET 8 Minimal API template with Keycloak pre-configured, a pre-built realm that imports at startup, and two test users ready to go. If you want to skip the setup and get straight to building, it's at fenixkit.dev.

If you want to find out more on how I built it, go to FenixKit GitHub.

DEV Community