Keycloak.AuthServices

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

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

Getting Started

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

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

services.AddKeycloakAuthentication(configuration);

var app = builder.Build();

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

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

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

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
    .GetSection(KeycloakAuthenticationOptions.Section)
    .Get<KeycloakAuthenticationOptions>();

services.AddKeycloakAuthentication(authenticationOptions);

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;

host.ConfigureKeycloakConfigurationSource();
// conventional registration from keycloak.json
services.AddKeycloakAuthentication(configuration);

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
        });
    })
    .AddKeycloakAuthorization(configuration);

var app = builder.Build();

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

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

app.Run();