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)

1. Organization Authorization (Multi-Tenancy) → Load

organization-authorization.md

1. RFC 8414 Server Metadata Discovery → Load authentication.md (see "Server Metadata

Discovery" section)

1. Custom Token Provider (IKeycloakAccessTokenProvider) → Load

resource-protection.md (see "IKeycloakAccessTokenProvider" section)

1. Extensible Policy Builder (IProtectedResourcePolicyBuilder) → Load

resource-protection.md (see "IProtectedResourcePolicyBuilder" section)

1. 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