EmDzej.KeycloakApiKeyAuthentication 0.1.0

.NET 10.0

dotnet add package EmDzej.KeycloakApiKeyAuthentication --version 0.1.0

NuGet\Install-Package EmDzej.KeycloakApiKeyAuthentication -Version 0.1.0

This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.

<PackageReference Include="EmDzej.KeycloakApiKeyAuthentication" Version="0.1.0" />

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="EmDzej.KeycloakApiKeyAuthentication" Version="0.1.0" />
                    

                            Directory.Packages.props

<PackageReference Include="EmDzej.KeycloakApiKeyAuthentication" />
                    

                            Project file

For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.

paket add EmDzej.KeycloakApiKeyAuthentication --version 0.1.0

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: EmDzej.KeycloakApiKeyAuthentication, 0.1.0"

#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.

#:package EmDzej.KeycloakApiKeyAuthentication@0.1.0

#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.

#addin nuget:?package=EmDzej.KeycloakApiKeyAuthentication&version=0.1.0
                    

                            Install as a Cake Addin

#tool nuget:?package=EmDzej.KeycloakApiKeyAuthentication&version=0.1.0
                    

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

EmDzej.KeycloakApiKeyAuthentication

ASP.NET Core authentication handler that validates API keys issued by keycloak-api-keys by exchanging them for Keycloak access tokens, then populating HttpContext.User with the resulting claims so [Authorize] and policy-based auth work without extra wiring.

Installation

dotnet add package EmDzej.KeycloakApiKeyAuthentication

Quick start

// Program.cs
builder.Services
    .AddAuthentication(KeycloakApiKeyExtensions.DefaultScheme)
    .AddKeycloakApiKeyAuthentication(options =>
    {
        options.ServerUrl    = "https://auth.example.com";
        options.Realm        = "my-realm";
        options.ClientId     = "my-app";
        options.ClientSecret = builder.Configuration["Keycloak:ClientSecret"]; // optional
    });

builder.Services.AddAuthorization();

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

Protect an endpoint:

app.MapGet("/protected", (ClaimsPrincipal user) => $"Hello {user.Identity?.Name}")
   .RequireAuthorization();

Call it with an API key:

GET /protected HTTP/1.1
X-API-Key: myapp_abc123...

Options

Property	Default	Description
`ServerUrl`	(required)	Keycloak base URL, e.g. `https://auth.example.com`
`Realm`	(required)	Keycloak realm name
`ClientId`	(required)	Client ID for the token exchange
`ClientSecret`	`null`	Client secret (required for confidential clients)
`HeaderName`	`X-API-Key`	HTTP header the handler reads the key from
`CacheTtlSeconds`	`300`	Max seconds to cache a successful exchange result

Claims

After a successful exchange the following claims are available on HttpContext.User:

Claim	Source
`ClaimTypes.NameIdentifier` / `sub`	Keycloak user ID
`ClaimTypes.Name` / `preferred_username`	Keycloak username
`ClaimTypes.Email`	Keycloak email
`ClaimTypes.Role`	Realm roles (enables `[Authorize(Roles = "admin")]`)
`client_role`	Client roles as `<clientId>:<role>`
`api_key_id`	ID of the API key used
`scope`	Granted scopes

Using with authorization policies

builder.Services.AddAuthorization(options =>
{
    options.AddPolicy("RequireAdmin", policy =>
        policy.RequireRole("admin"));
});

Custom cache

Swap the default in-memory cache for a distributed one:

builder.Services.AddSingleton<ITokenCache<ApiKeyClaimsInfo>, MyRedisTokenCache>();
builder.Services
    .AddAuthentication(KeycloakApiKeyExtensions.DefaultScheme)
    .AddKeycloakApiKeyAuthentication(options => { ... });

Custom HttpClient (retry, circuit breaker)

builder.Services
    .AddHttpClient(KeycloakTokenExchangeClient.HttpClientName)
    .AddStandardResilienceHandler();   // Microsoft.Extensions.Http.Resilience

Multiple schemes

builder.Services
    .AddAuthentication()
    .AddKeycloakApiKeyAuthentication("realm-a", options => { options.Realm = "a"; ... })
    .AddKeycloakApiKeyAuthentication("realm-b", options => { options.Realm = "b"; ... });

Product	Compatible and additional computed target framework versions.
.NET	net10.0 is compatible. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed.

Compatible target framework(s)

Included target framework(s) (in package)

Learn more about Target Frameworks and .NET Standard.

net10.0
- No dependencies.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version	Downloads	Last Updated
0.1.0	146	3/20/2026