OpenParable
Skip to content
← Back to skills

Keycloak Auth Services

Development
keycloak-auth-services

Keycloak Auth Services is an Agent Skill for development published in the NikiforovAll/keycloak-authorization-services-dotnet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Implementation guide for Keycloak.AuthServices .NET library — authentication (JWT Bearer, OIDC, RFC 8414), authorization (RBAC, resource protection, Authorization Server, organizations, multi-tenancy), Admin REST API SDK, Protection API SDK, and developer experience tooling (.NET Aspire, templates, OpenTelemetry). Trigger phrases include Keycloak.AuthServices, ProtectedResource, Admin SDK, Protection API, organization, RFC 8414, token introspection.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/NikiforovAll/keycloak-authorization-services-dotnet/blob/HEAD/skills/keycloak-auth-services/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/keycloak-auth-services, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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

PackagePurpose
Keycloak.AuthServices.AuthenticationJWT Bearer (Web API) and OpenID Connect (Web App) authentication
Keycloak.AuthServices.AuthorizationRBAC (realm/client roles), Authorization Server client, [ProtectedResource] attribute, organization authorization
Keycloak.AuthServices.SdkHand-written Admin REST API + Protection API HTTP clients
Keycloak.AuthServices.Sdk.KiotaAuto-generated (Kiota) Admin REST API client — full API coverage
Keycloak.AuthServices.CommonShared configuration (KeycloakInstallationOptions), claims utilities
Keycloak.AuthServices.OpenTelemetryMetrics and tracing instrumentation
Keycloak.AuthServices.Aspire.Hosting.NET Aspire KeycloakResource integration
Keycloak.AuthServices.Templatesdotnet 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:

PropertyDescription
realmKeycloak realm name
auth-server-urlKeycloak server URL (e.g., http://localhost:8080/)
resourceClient ID
ssl-requirednone, external, or all
verify-token-audienceValidate audience claim against resource
credentials.secretClient 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