Keycloak.AuthServices.Common 2.0.0-pre-1

Prefix Reserved
This is a prerelease version of Keycloak.AuthServices.Common.
There is a newer version of this package available.
See the version list below for details.
dotnet add package Keycloak.AuthServices.Common --version 2.0.0-pre-1                
NuGet\Install-Package Keycloak.AuthServices.Common -Version 2.0.0-pre-1                
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.Common" Version="2.0.0-pre-1" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Keycloak.AuthServices.Common --version 2.0.0-pre-1                
#r "nuget: Keycloak.AuthServices.Common, 2.0.0-pre-1"                
#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.Common as a Cake Addin
#addin nuget:?package=Keycloak.AuthServices.Common&version=2.0.0-pre-1&prerelease

// Install Keycloak.AuthServices.Common as a Cake Tool
#tool nuget:?package=Keycloak.AuthServices.Common&version=2.0.0-pre-1&prerelease                

Keycloak.AuthServices

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;

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>(KeycloakInstallationOptions.KeycloakFormatBinder);

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();

Keycloak.AuthServices.Authentication

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
host.ConfigureKeycloakConfigurationSource("keycloak.json");
// 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 - README.md

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
}

Keycloak.AuthServices.Authorization

services.AddAuthorization(authOptions =>
{
    authOptions.AddPolicy("<policyName>", policyBuilder =>
    {
        // configure policies here
    });
}).AddKeycloakAuthorization(configuration);

See Keycloak.AuthServices.Authorization - README.md

Keycloak.AuthServices.Sdk

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
services.AddKeycloakAdminHttpClient(keycloakOptions);

// based on token forwarding HttpClient middleware and IHttpContextAccessor
services.AddKeycloakProtectionHttpClient(keycloakOptions);

See Keycloak.AuthServices.Sdk - README.md

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 https://nikiforovall.github.io/tags.html#keycloak-ref

Reference

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 (2)

Showing the top 2 NuGet packages that depend on Keycloak.AuthServices.Common:

Package Downloads
Keycloak.AuthServices.Sdk

HttpClient integration with Keycloak. Includes HTTP Admin REST API, Protection API.

Keycloak.AuthServices.Sdk.Kiota

Keycloak HTTP Admin API generated by Kiota

GitHub repositories (1)

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

Repository Stars
NikiforovAll/keycloak-authorization-services-dotnet
Authentication and Authorization with Keycloak and ASP.NET Core 🔐
Version Downloads Last updated
2.6.0 2,213 11/30/2024
2.5.5 1,294 11/27/2024
2.5.3 40,838 8/19/2024
2.5.2 38,990 6/15/2024
2.5.1 628 6/11/2024
2.5.0 8,934 6/2/2024
2.4.1 7,363 5/16/2024
2.4.0 848 5/12/2024
2.3.0 336 5/10/2024
2.3.0-pre-1 126 5/9/2024
2.2.1 631 5/9/2024
2.2.0 195 5/8/2024
2.1.0 2,640 5/7/2024
2.0.0 617 5/5/2024
2.0.0-pre-4 141 5/4/2024
2.0.0-pre-3 198 4/26/2024
2.0.0-pre-2 134 4/25/2024
2.0.0-pre-1 288 4/24/2024
1.7.0 2,948 4/23/2024
1.6.0 95,461 10/25/2023
1.5.2 73,523 5/27/2023
1.5.1 51,106 1/17/2023
1.5.0 610 1/17/2023
1.4.1 1,019 1/12/2023
1.4.0 507 1/4/2023
1.3.0 1,085 12/28/2022
1.2.1 9,830 9/22/2022
1.2.0 734 8/24/2022
1.1.0 14,814 1/30/2022
1.0.5 147 1/29/2022
1.0.4 3,333 1/28/2022
1.0.3 133 1/28/2022
1.0.2 138 1/23/2022
1.0.1 660 1/19/2022