Keycloak.AuthServices.Authentication 1.6.0

This package has a SemVer 2.0.0 package version: 1.6.0+build.98.
dotnet add package Keycloak.AuthServices.Authentication --version 1.6.0
NuGet\Install-Package Keycloak.AuthServices.Authentication -Version 1.6.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="Keycloak.AuthServices.Authentication" Version="1.6.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Keycloak.AuthServices.Authentication --version 1.6.0
#r "nuget: Keycloak.AuthServices.Authentication, 1.6.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.
// Install Keycloak.AuthServices.Authentication as a Cake Addin
#addin nuget:?package=Keycloak.AuthServices.Authentication&version=1.6.0

// Install Keycloak.AuthServices.Authentication as a Cake Tool
#tool nuget:?package=Keycloak.AuthServices.Authentication&version=1.6.0


Build CodeQL NuGet contributionswelcome Conventional Commits License

Easy Authentication and Authorization with Keycloak in .NET and ASP.NET Core.

Package Version Description
Keycloak.AuthServices.Authentication Nuget Keycloak Authentication JWT + OICD
Keycloak.AuthServices.Authorization Nuget Authorization Services. Use Keycloak as authorization server
Keycloak.AuthServices.Sdk Nuget HTTP API integration with Keycloak

GitHub Actions Build History

Getting Started

// Program.cs
var builder = WebApplication.CreateBuilder(args);

var host = builder.Host;
var configuration = builder.Configuration;
var services = builder.Services;


var app = builder.Build();


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


In this example, configuration is based on appsettings.json.

    "Keycloak": {
        "realm": "Test",
        "auth-server-url": "http://localhost:8080/",
        "ssl-required": "none",
        "resource": "test-client",
        "verify-token-audience": false,
        "credentials": {
        "secret": ""
        "confidential-port": 0

It's fetched based on well-known section "Keycloak". AddKeycloakAuthentication uses KeycloakAuthenticationOptions.Section under the hood.

You can always fetch the corresponding authentication options like this:

var authenticationOptions = configuration


AddKeycloakAuthentication method has several overloads. It allows to override some conventions, for example:

public static AuthenticationBuilder AddKeycloakAuthentication(
    this IServiceCollection services,
    IConfiguration configuration,
    string? keycloakClientSectionName,
    Action<JwtBearerOptions>? configureOptions = default)
    /* implementation */

Example. Authentication + Authorization

Here is how to add JWT-based authentication and custom authorization policy.

var builder = WebApplication.CreateBuilder(args);

var host = builder.Host;
var configuration = builder.Configuration;
var services = builder.Services;

// conventional registration from keycloak.json

services.AddAuthorization(options =>
        options.AddPolicy("RequireWorkspaces", builder =>
            builder.RequireProtectedResource("workspaces", "workspaces:read") // HTTP request to Keycloak to check protected resource
                .RequireRealmRoles("User") // Realm role is fetched from token
                .RequireResourceRoles("Admin"); // Resource/Client role is fetched from token

var app = builder.Build();


app.MapGet("/workspaces", () => "[]")



Add OpenID Connect + JWT Bearer token authentication.

For example, see Getting Started

Adapter File. Optional

Using appsettings.json is a recommended and it is an idiomatic approach for .NET, but if you want a standalone "adapter" (installation) file - keycloak.json. You can use ConfigureKeycloakConfigurationSource. It adds dedicated configuration source.

// add configuration from keycloak file
// add authentication services, OICD JwtBearerDefaults.AuthenticationScheme
services.AddKeycloakAuthentication(configuration, o =>
    o.RequireHttpsMetadata = false;

Client roles are automatically transformed into user role claims KeycloakRolesClaimsTransformation.

See Keycloak.AuthServices.Authentication -

Keycloak installation file:

// confidential client
  "realm": "<realm>",
  "auth-server-url": "http://localhost:8088/auth/",
  "ssl-required": "external", // external | none
  "resource": "<clientId>",
  "verify-token-audience": true,
  "credentials": {
    "secret": ""
// public client
  "realm": "<realm>",
  "auth-server-url": "http://localhost:8088/auth/",
  "ssl-required": "external",
  "resource": "<clientId>",
  "public-client": true,
  "confidential-port": 0


services.AddAuthorization(authOptions =>
    authOptions.AddPolicy("<policyName>", policyBuilder =>
        // configure policies here

See Keycloak.AuthServices.Authorization -


Keycloak API clients.

Service Description
IKeycloakClient Unified HTTP client - IKeycloakRealmClient, IKeycloakProtectedResourceClient
IKeycloakRealmClient Keycloak realm API
IKeycloakProtectedResourceClient Protected resource API
IKeycloakUserClient Keycloak user API
IKeycloakProtectionClient Authorization server API, used by AddKeycloakAuthorization
// requires confidential client

// based on token forwarding HttpClient middleware and IHttpContextAccessor

See Keycloak.AuthServices.Sdk -

Build and Development

dotnet cake --target build

dotnet pack -o ./Artefacts

Blog Posts

For more information and real world examples, please see my blog posts related to Keycloak and .NET


Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (6)

Showing the top 5 NuGet packages that depend on Keycloak.AuthServices.Authentication:

Package Downloads

Package Description


Package Description


Package Description


Package Description


Package Description

GitHub repositories (1)

Showing the top 1 popular GitHub repositories that depend on Keycloak.AuthServices.Authentication:

Repository Stars
Authentication and Authorization with Keycloak and ASP.NET Core 🔐
Version Downloads Last updated
1.6.0 102,356 10/25/2023
1.5.2 189,934 5/27/2023
1.5.1 140,313 1/17/2023
1.5.0 639 1/17/2023
1.4.1 2,778 1/12/2023
1.4.0 5,487 1/4/2023
1.3.0 4,114 12/28/2022
1.2.1 68,296 9/22/2022
1.2.0 6,569 8/24/2022
1.1.0 11,879 1/30/2022
1.0.5 144 1/29/2022
1.0.4 3,013 1/28/2022
1.0.3 121 1/28/2022
1.0.2 119 1/23/2022
1.0.1 638 1/19/2022
1.0.0 933 1/19/2022