LowCodeHub.Keycloak.Authentication.JwtBearer 0.0.11

LowCodeHub.Keycloak.Authentication.JwtBearer

Keycloak JWT Bearer authentication for ASP.NET Core. The package wires up AddJwtBearer, validates Keycloak options at startup, configures OpenID Connect metadata and JWKS retrieval, and maps Keycloak realm/client roles into normal ASP.NET Core role claims.

Why This Library?

Installation

dotnet add package LowCodeHub.Keycloak.Authentication.JwtBearer

Quick Start

using LowCodeHub.Keycloak.Authentication.JwtBearer.Extensions;

builder.Services.AddKeycloakJwtBearerAuthentication(options =>
{
    options.KeycloakBaseUrl = "https://keycloak.example.com";
    options.Realm = "my-realm";
    options.Audience = "my-api";
});

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/me", (ClaimsPrincipal user) => new
{
    Name = user.Identity?.Name,
    Roles = user.FindAll("role").Select(c => c.Value)
}).RequireAuthorization();

app.Run();

Tokens issued by Keycloak are validated against the configured issuer and audience. Realm roles from realm_access.roles and client roles from resource_access.{Audience}.roles are copied to the configured role claim type, so standard ASP.NET Core authorization works:

app.MapGet("/admin", () => "ok")
   .RequireAuthorization(policy => policy.RequireRole("admin"));

Configuration

Code-Based Configuration

builder.Services.AddKeycloakJwtBearerAuthentication(options =>
{
    options.KeycloakBaseUrl = "https://keycloak.example.com";
    options.Realm = "my-realm";
    options.Audience = "orders-api";
    options.RequireHttpsMetadata = true;
});

appsettings.json

builder.Services.AddKeycloakJwtBearerAuthentication(builder.Configuration);

{
  "Keycloak": {
    "KeycloakBaseUrl": "https://keycloak.example.com",
    "Realm": "my-realm",
    "Audience": "orders-api",
    "RequireHttpsMetadata": true
  }
}

Use a custom section name when needed:

builder.Services.AddKeycloakJwtBearerAuthentication(
    builder.Configuration,
    sectionName: "Authentication:Keycloak");

Options

Computed URLs:

Role Mapping

Keycloak stores roles in JSON claims, not as simple repeated role claims:

{
  "realm_access": {
    "roles": ["admin", "support"]
  },
  "resource_access": {
    "orders-api": {
      "roles": ["orders.read", "orders.write"]
    }
  }
}

The package registers IClaimsTransformation and copies those roles into the configured RoleClaimType (role by default). It is idempotent, so repeated transformations do not duplicate role claims.

builder.Services.AddKeycloakJwtBearerAuthentication(options =>
{
    options.KeycloakBaseUrl = "https://keycloak.example.com";
    options.Realm = "my-realm";
    options.Audience = "orders-api";
    options.RoleClaimType = ClaimTypes.Role;
});

Named Authentication Scheme

By default, the package registers the normal Bearer scheme as the default authenticate/challenge scheme.

For apps with multiple authentication schemes, pass a custom scheme name:

builder.Services.AddKeycloakJwtBearerAuthentication(options =>
{
    options.KeycloakBaseUrl = "https://keycloak.example.com";
    options.Realm = "my-realm";
    options.Audience = "orders-api";
}, authenticationScheme: "KeycloakBearer");

app.MapGet("/secure", () => "ok")
   .RequireAuthorization(new AuthorizeAttribute
   {
       AuthenticationSchemes = "KeycloakBearer"
   });

JWKS Options

Use JwksOption to tune metadata/JWKS refresh behavior or supply a custom backchannel handler.

builder.Services.AddKeycloakJwtBearerAuthentication(options =>
{
    options.KeycloakBaseUrl = "https://keycloak.example.com";
    options.Realm = "my-realm";
    options.Audience = "orders-api";

    options.JwksOption = new JwksOptions
    {
        AutomaticRefreshInterval = TimeSpan.FromHours(6),
        RefreshInterval = TimeSpan.FromMinutes(2)
    };
});

For local development with self-signed certificates:

options.JwksOption.BackchannelHttpHandler = new HttpClientHandler
{
    ServerCertificateCustomValidationCallback =
        HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
};

Do not use that certificate bypass in production.

Query String Tokens

Bearer tokens should normally be sent in the Authorization header. Some browser-based transports, such as Server-Sent Events or WebSockets, may need query string tokens.

options.AcceptTokenFromQueryString = true;

When enabled, the package reads ?access_token= during OnMessageReceived.

Failure Headers

For SPA clients that need a simple refresh signal, enable failure headers:

options.EmitFailureResponseHeaders = true;

Authentication failures can emit:

This can reveal authentication details, so keep it disabled for public APIs unless clients require it.

Common Gotchas

RequireHttpsMetadata now defaults to true

Starting with version 0.0.3, RequireHttpsMetadata defaults to true, matching the ASP.NET Core framework default. This is a behavioral change: plain-HTTP development setups (e.g., http://localhost:8080 Keycloak) must now opt out explicitly:

options.RequireHttpsMetadata = false; // development only

Keycloak audience must match Audience

ASP.NET Core validates the JWT aud claim. Many Keycloak clients do not include your API/client ID in aud by default.

If validation fails with an audience error, add an audience mapper in Keycloak:

1. Open your client in Keycloak Admin Console.
2. Go to Client scopes or Mappers.
3. Add an Audience mapper.
4. Include your API/client ID in the access token audience.

azp and aud are different claims. This package validates aud.

Reverse proxies can change the issuer

If Keycloak is reached internally at one URL but tokens contain an external issuer URL, override Issuer:

options.KeycloakBaseUrl = "http://keycloak:8080";
options.Issuer = "https://auth.example.com/realms/my-realm";

Middleware order matters

Use authentication before authorization:

app.UseAuthentication();
app.UseAuthorization();

How It Works

1. AddKeycloakJwtBearerAuthentication binds and validates KeycloakOptions.
2. AddJwtBearer is configured with authority, metadata address, issuer, audience, lifetime, name claim, and role claim settings.
3. JWKS retrieval uses the configured certs endpoint and refresh intervals.
4. KeycloakRolesClaimsTransformation maps Keycloak realm/client roles into standard role claims.
5. Optional events handle query string tokens and failure response headers.

Requirements

• .NET 10 or later
• ASP.NET Core
• Keycloak access tokens with a valid issuer and audience

License

MIT