Keycloak auth services

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

Package	Purpose
Keycloak.AuthServices.Authentication	JWT Bearer (Web API) and OpenID Connect (Web App) authentication
Keycloak.AuthServices.Authorization	RBAC (realm/client roles), Authorization Server client, [ProtectedResource] attribute, organization authorization
Keycloak.AuthServices.Sdk	Hand-written Admin REST API + Protection API HTTP clients
Keycloak.AuthServices.Sdk.Kiota	Auto-generated (Kiota) Admin REST API client, full API coverage
Keycloak.AuthServices.Common	Shared configuration (KeycloakInstallationOptions), claims utilities
Keycloak.AuthServices.OpenTelemetry	Metrics and tracing instrumentation
Keycloak.AuthServices.Aspire.Hosting	.NET Aspire KeycloakResource integration
Keycloak.AuthServices.Templates	dotnet new project templates

---

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:

Property	Description
realm	Keycloak realm name
auth-server-url	Keycloak server URL (e.g., http://localhost:8080/)
resource	Client ID
ssl-required	none, external, or all
verify-token-audience	Validate audience claim against resource
credentials.secret	Client secret (confidential clients)

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