Winche.KeycloakClient 2.0.0

KeycloakClient

An opinionated ASP.NET Core integration for the Keycloak Admin API and the Phase Two webhook plugin. Configure once via appsettings.json, then inject IKeycloakClientService and write event handlers.

Features

• Service-account IKeycloakClientService — backed by client-credentials token management (Duende.AccessTokenManagement). Works for background jobs and unauthenticated callers.
• Optional delegated IKeycloakClientService — forwards the incoming request's bearer token to the Admin API. Operations run with the caller's privileges.
• Admin API coverage — users (CRUD, search, count, reset-password, action emails), groups, user/group membership.
• Webhook intake — app.UseKeycloakWebHooks() mounts an endpoint, validates the shared secret in constant time, and dispatches typed events to your handlers.
• Automatic registration — registers (or removes) the webhook on startup based on appsettings.json.

Requirements

• .NET 10 (net10.0)
• ASP.NET Core 10
• A Keycloak realm with a confidential client (for the service-account flow)
• The Phase Two webhook plugin installed in Keycloak (only if you use webhook features)

Installation

dotnet add package Winche.KeycloakClient

Configuration

Add a Keycloak section to appsettings.json:

{
  "Keycloak": {
    "Server": "https://id.example.com",
    "Realm": "myrealm",
    "Resource": "myapp",
    "Agent": "MyApp/1.0",
    "Credentials": {
      "Secret": "REPLACE_ME"
    },
    "Webhook": {
      "Enabled": true,
      "URL": "https://myapp.example.com/webhooks/keycloak",
      "Secret": "shared-secret-with-keycloak"
    }
  }
}

Authentication & authorization

This package also configures ASP.NET Core JWT bearer authentication and Keycloak-aware authorization (role policies + UMA / Authorization Services) when you call the dedicated extensions.

appsettings.json

Both sections are optional; add only what you use.

{
  "Keycloak": {
    "Server": "https://id.example.com",
    "Realm": "myrealm",
    "Resource": "myapp",
    "Credentials": { "Secret": "REPLACE_ME" },

    "Authentication": {
      "ValidateAudience": true,
      "RolesSource": "RealmAndResource",
      "RealmRolePrefix": null,
      "ResourceRolePrefix": null,
      "AdditionalResourceClients": []
    },

    "Authorization": {
      "CacheDuration": null,
      "DecisionStrategy": "Unanimous"
    }
  }
}

Registration

using Winche.KeycloakClient.DependencyInjection;

builder.Services
    .AddKeycloakClient(builder.Configuration)
    .AddKeycloakAuthentication(builder.Configuration)
    .AddKeycloakAuthorization(builder.Configuration, c => c
        .AddRealmRolePolicy("admin")
        .AddResourceRolePolicy("editor")
        .AddProtectedResourcePolicy("can-read-doc", "document", "read"));

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

Usage

Role-based — [Authorize] with realm/resource roles:

app.MapGet("/admin/users", () => "ok").RequireAuthorization("admin");
app.MapGet("/editor/doc", () => "ok").RequireAuthorization("editor");

After authentication, both realm and resource roles are exposed as ClaimTypes.Role claims, so [Authorize(Roles = "admin")] and User.IsInRole("admin") also work.

Original OIDC claim names are preserved on ClaimsPrincipal — User.FindFirstValue("sub"), User.FindFirstValue("email"), User.FindFirstValue("preferred_username") work directly. The JwtBearer handler's default inbound-claim remapping (which would rewrite sub to …/nameidentifier, email to …/emailaddress, etc.) is disabled.

Endpoint-level UMA — [ProtectedResource] attribute or kc:protected:* policy:

app.MapGet("/documents", [ProtectedResource("document", "read")] () => "ok");

// Equivalent:
app.MapGet("/documents", () => "ok")
    .RequireAuthorization("kc:protected:document:read");

Both forms cause KeycloakProtectedResourceHandler to ask Keycloak whether the current token is granted read on document. A denial returns 403.

Resource-instance UMA — imperative IKeycloakAuthorizationService:

app.MapGet("/documents/{id:int}", async (
        int id,
        IKeycloakAuthorizationService authz,
        IDocumentStore store,
        CancellationToken ct) =>
{
    await authz.RequireAsync($"document:{id}", "read", ct);
    return Results.Ok(await store.GetAsync(id, ct));
}).RequireAuthorization();

RequireAsync throws KeycloakAuthorizationException on deny; let it bubble and exception-handling middleware can translate to 403. Use AuthorizeAsync (returns bool) when you need to branch on the decision.

Quick start

Registration

using Winche.KeycloakClient.DependencyInjection;

const string DelegatedClientKey = "user";

builder.Services
    .AddKeycloakClient(builder.Configuration, c => c.AddDelegatedClient(DelegatedClientKey))
    .AddKeycloakWebHooks(c => c.AddEventHandler<MyUserCreatedHandler>());

AddDelegatedClient is optional — only register it if you want token-forwarding endpoints.

Service-account client

Resolves the default IKeycloakClientService. Uses the configured client credentials for every call — no caller context needed.

app.MapGet("/users", async (IKeycloakClientService client, CancellationToken ct) =>
    Results.Ok(await client.GetUsersAsync(cancellationToken: ct)));

Delegated client

Resolves the keyed IKeycloakClientService registered via AddDelegatedClient(key). The handler reads the incoming Authorization: Bearer <token> header and forwards it. Throws InvalidOperationException if called outside of an HTTP request scope or if the request has no bearer token — fail fast rather than silently issuing unauthorized requests.

app.MapGet("/me/users", async (
        [FromKeyedServices("user")] IKeycloakClientService client,
        CancellationToken ct) =>
    Results.Ok(await client.GetUsersAsync(cancellationToken: ct)))
    .RequireAuthorization();

The forwarded token must carry the right realm-management roles for the operation to succeed (Keycloak enforces this server-side).

Webhook endpoint

app.UseKeycloakWebHooks(); // mounts POST /webhooks/keycloak by default

Pass a different path if you want: app.UseKeycloakWebHooks("/hooks/kc");. The endpoint validates X-Webhook-Secret against Keycloak:Webhook:Secret using a constant-time comparison.

Event handlers

Derive from KeycloakEventHandler, declare the event types you care about, and implement HandleAsync:

using Winche.KeycloakClient.Abstraction;
using Winche.KeycloakClient.Models;

public sealed class UserCreatedHandler(ILogger<UserCreatedHandler> logger) : KeycloakEventHandler
{
    public override IReadOnlySet<string> Types { get; } = new HashSet<string>
    {
        "access.REGISTER",
        "admin.USER-CREATE"
    };

    public override Task HandleAsync(KeycloakWebhookEvent @event, CancellationToken ct)
    {
        logger.LogInformation("Got '{Type}' for {Username}", @event.Type, @event.Representation?.Username);
        return Task.CompletedTask;
    }
}

Register the handler when wiring webhooks: c.AddEventHandler<UserCreatedHandler>(). Handlers are invoked in parallel; exceptions from one handler don't affect others.

Webhook lifecycle

On startup, the library:

1. Reads Keycloak:Webhook from configuration.
2. If Url is blank → skip.
3. Otherwise, find any existing Keycloak webhook with the same Url and delete it.
4. If Enabled = true → create a fresh webhook with the configured URL, secret, and the union of all Types from registered handlers.
5. If Enabled = false → stop after step 3 (a configuration toggle that also tidies up upstream).

Always delete-and-recreate keeps the secret in sync with appsettings.json, since Keycloak's webhook GET endpoint does not return secrets.

License

MIT