Keycloak.AuthServices

🔐 Easy Authentication and Authorization with Keycloak in .NET.

Package	Version	Description
Keycloak.AuthServices.Authentication		Keycloak Authentication JWT + OIDC
Keycloak.AuthServices.Authorization		Authorization Services. Use Keycloak as authorization server
Keycloak.AuthServices.Authorization.TokenIntrospection		Token introspection for lightweight access tokens (KC 24+)
Keycloak.AuthServices.Authorization.Uma		UMA 2.0 support — permission ticket challenges, RPT exchange
Keycloak.AuthServices.Sdk		HTTP API integration with Keycloak
Keycloak.AuthServices.Sdk.Kiota		HTTP API integration with Keycloak based on OpenAPI
Keycloak.AuthServices.OpenTelemetry		OpenTelemetry support
Keycloak.AuthServices.Templates		dotnet new templates

Documentation

For Developer Documentation see: https://nikiforovall.github.io/keycloak-authorization-services-dotnet

API Reference

See: https://nikiforovall.github.io/keycloak-authorization-services-dotnet-docs

Getting Started

Install packages:

dotnet add package Keycloak.AuthServices.Authentication

// Program.cs
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();

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

//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
    }
}

Example - Add Authorization

With Keycloak.AuthServices.Authorization, you can implement role-based authorization in your application. This package allows you to define policies based on roles. Also, you can use Keycloak as Authorization Server. It is a powerful way to organize and apply authorization polices centrally.

var builder = WebApplication.CreateBuilder(args);

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

services.AddKeycloakWebApiAuthentication(configuration);

services.AddAuthorization(options =>
    {
        options.AddPolicy("AdminAndUser", builder =>
        {
            builder
                .RequireRealmRoles("User") // Realm role is fetched from token
                .RequireResourceRoles("Admin"); // Resource/Client role is fetched from token
        });
    })
    .AddKeycloakAuthorization(configuration);

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/hello", () => "[]")
    .RequireAuthorization("AdminAndUser");

app.Run();

Example - Invoke Admin API

var services = new ServiceCollection();
services.AddKeycloakAdminHttpClient(new KeycloakAdminClientOptions
{
    AuthServerUrl = "http://localhost:8080/",
    Realm = "master",
    Resource = "admin-api",
});

var sp = services.BuildServiceProvider();
var client = sp.GetRequiredService<IKeycloakRealmClient>();

var realm = await client.GetRealmAsync("Test");

Build and Development

dotnet cake --target build

dotnet cake --target test

dotnet pack -o ./Artefacts