Keycloak.AuthServices Implementation Guide

Quick Start

Choose your task and load the appropriate reference:

1. JWT Bearer Authentication (Web API) → Continue below
2. OIDC Authentication (Web App) → Load authentication.md
3. Authorization & RBAC → Load authorization.md
4. Resource Protection & Authorization Server → Load resource-protection.md
5. Admin REST API SDK → Load admin-sdk.md
6. Protection API SDK → Load protection-api.md
7. Developer Experience (Aspire, Templates) → Load devex.md
8. Configuration Reference → Load configuration.md
9. Recipes & Troubleshooting → Load troubleshooting.md
10. Token Introspection (Lightweight Tokens) → Load authorization.md (see "Token Introspection" section)
11. Organization Authorization (Multi-Tenancy) → Load organization-authorization.md
12. RFC 8414 Server Metadata Discovery → Load authentication.md (see "Server Metadata Discovery" section)
13. Custom Token Provider (IKeycloakAccessTokenProvider) → Load resource-protection.md (see "IKeycloakAccessTokenProvider" section)
14. Extensible Policy Builder (IProtectedResourcePolicyBuilder) → Load resource-protection.md (see "IProtectedResourcePolicyBuilder" section)
15. Pluggable Parameter Resolvers → Load resource-protection.md (see "Pluggable Parameter Resolvers" section)

Packages Overview

Minimal Web API Setup

dotnet add package Keycloak.AuthServices.Authentication
dotnet add package Keycloak.AuthServices.Common

using Keycloak.AuthServices.Authentication;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddKeycloakWebApiAuthentication(builder.Configuration);
builder.Services.AddAuthorization();

var app = builder.Build();
app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", () => "Hello World!").RequireAuthorization();
app.Run();

// appsettings.json — "Keycloak" section (kebab-case from adapter config)
{
  "Keycloak": {
    "realm": "Test",
    "auth-server-url": "http://localhost:8080/",
    "ssl-required": "none",
    "resource": "test-client",
    "verify-token-audience": true,
    "credentials": {
      "secret": "your-client-secret"
    }
  }
}

Configuration Section

All packages bind to "Keycloak" config section by default. Key properties:

Both kebab-case (Keycloak adapter format) and PascalCase are supported.

Adding Authorization (RBAC)

dotnet add package Keycloak.AuthServices.Authorization

builder.Services.AddKeycloakAuthorization(builder.Configuration)
    .AddAuthorizationBuilder()
    .AddPolicy("AdminOnly", policy => policy.RequireRealmRoles("admin"))
    .AddPolicy("EditorOnly", policy => policy.RequireResourceRoles("editor"));

Adding Authorization Server (Resource Protection)

builder.Services
    .AddKeycloakAuthorization()
    .AddAuthorizationServer(builder.Configuration);

app.MapGet("/workspaces", () => "Hello World!")
    .RequireProtectedResource("workspaces", "workspace:read");

Adding Admin SDK

dotnet add package Keycloak.AuthServices.Sdk

builder.Services.AddKeycloakAdminHttpClient(builder.Configuration);

app.MapGet("/users", async (IKeycloakUserClient client) =>
    await client.GetUsers("my-realm"));

Essential Patterns

• Configuration section: defaults to "Keycloak", override via configSectionName parameter
• IHttpClientBuilder: all HTTP clients return IHttpClientBuilder for resilience, handlers, etc.
• Token management: use Duende.AccessTokenManagement for service account tokens
• OpenTelemetry: AddKeycloakAuthServicesInstrumentation() for metrics and tracing
• Aspire: AddKeycloakContainer("keycloak") + AddRealm("Test") for local dev

Reference Documentation

• authentication.md — JWT Bearer and OIDC setup, all overloads, adapter file config, RFC 8414 server metadata discovery
• authorization.md — RBAC, realm/client roles, role claims transformation, token introspection
• organization-authorization.md — Organization-based multi-tenancy, membership requirements, parameter resolvers
• resource-protection.md — Authorization Server, Protected Resource Builder, dynamic resources, policy provider, IKeycloakAccessTokenProvider, IProtectedResourcePolicyBuilder, pluggable parameter resolvers
• admin-sdk.md — Admin REST API (hand-written + Kiota), access token management
• protection-api.md — UMA Protection API, resource/permission/policy management
• devex.md — .NET Aspire, templates, OpenTelemetry
• configuration.md — All configuration options, naming conventions, adapter file
• troubleshooting.md — Common issues, recipes, debugging