Keycloak.AuthServices.Authentication
2.0.0-pre-1
Prefix Reserved
See the version list below for details.
dotnet add package Keycloak.AuthServices.Authentication --version 2.0.0-pre-1
NuGet\Install-Package Keycloak.AuthServices.Authentication -Version 2.0.0-pre-1
<PackageReference Include="Keycloak.AuthServices.Authentication" Version="2.0.0-pre-1" />
<PackageVersion Include="Keycloak.AuthServices.Authentication" Version="2.0.0-pre-1" />
<PackageReference Include="Keycloak.AuthServices.Authentication" />
paket add Keycloak.AuthServices.Authentication --version 2.0.0-pre-1
#r "nuget: Keycloak.AuthServices.Authentication, 2.0.0-pre-1"
#addin nuget:?package=Keycloak.AuthServices.Authentication&version=2.0.0-pre-1&prerelease
#tool nuget:?package=Keycloak.AuthServices.Authentication&version=2.0.0-pre-1&prerelease
Keycloak.AuthServices
Easy Authentication and Authorization with Keycloak in .NET and ASP.NET Core.
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 | Versions 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. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. 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. |
-
net6.0
- Microsoft.AspNetCore.Authentication.JwtBearer (>= 6.0.29)
- Microsoft.Extensions.Configuration.Abstractions (>= 8.0.0)
- Microsoft.Extensions.Configuration.Json (>= 8.0.0)
- Microsoft.Extensions.DependencyInjection.Abstractions (>= 8.0.1)
NuGet packages (17)
Showing the top 5 NuGet packages that depend on Keycloak.AuthServices.Authentication:
Package | Downloads |
---|---|
Gathrr.Framework.Infrastructure
Package Description |
|
Feijuca.Auth
Feijuca.Auth simplifies Keycloak integration for user management and multi-tenancy. It features TokenManager for centralized API calls to manage users and auth services for handling multiple tenants using Keycloak realms. Check the documentation for more details! |
|
MicroEthos.Common.Endpoints
Package Description |
|
Wcz.Layout
Package Description |
|
Manjalabs.Library
Package Description |
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on Keycloak.AuthServices.Authentication:
Repository | Stars |
---|---|
mehmetozkaya/EshopModularMonoliths
Modular Monoliths on .NET used ASP.NET Web API, Docker, PostgreSQL, Redis, RabbitMQ, Keycloak, Seq, MassTransit, Entity Framework Core, CQRS, MediatR, DDD, Vertical Slice Architecture and Outbox pattern implementation with using latest features of .NET 8 and C# 12
|
Version | Downloads | Last Updated |
---|---|---|
2.6.1 | 80,261 | 3/13/2025 |
2.6.0 | 168,132 | 11/30/2024 |
2.5.3 | 293,104 | 8/19/2024 |
2.5.2 | 170,527 | 6/15/2024 |
2.5.1 | 20,534 | 6/11/2024 |
2.5.0 | 18,718 | 6/2/2024 |
2.4.1 | 27,820 | 5/16/2024 |
2.4.0 | 3,811 | 5/12/2024 |
2.3.0 | 662 | 5/10/2024 |
2.3.0-pre-1 | 132 | 5/9/2024 |
2.2.1 | 1,253 | 5/9/2024 |
2.2.0 | 1,299 | 5/8/2024 |
2.1.0 | 5,069 | 5/7/2024 |
2.0.0 | 6,137 | 5/5/2024 |
2.0.0-pre-4 | 155 | 5/4/2024 |
2.0.0-pre-3 | 221 | 4/26/2024 |
2.0.0-pre-2 | 147 | 4/25/2024 |
2.0.0-pre-1 | 403 | 4/24/2024 |
1.6.0 | 426,941 | 10/25/2023 |
1.5.2 | 315,297 | 5/27/2023 |
1.5.1 | 187,097 | 1/17/2023 |
1.5.0 | 706 | 1/17/2023 |
1.4.1 | 5,189 | 1/12/2023 |
1.4.0 | 5,532 | 1/4/2023 |
1.3.0 | 4,819 | 12/28/2022 |
1.2.1 | 96,337 | 9/22/2022 |
1.2.0 | 6,802 | 8/24/2022 |
1.1.0 | 13,318 | 1/30/2022 |
1.0.5 | 181 | 1/29/2022 |
1.0.4 | 3,426 | 1/28/2022 |
1.0.3 | 150 | 1/28/2022 |
1.0.2 | 151 | 1/23/2022 |
1.0.1 | 739 | 1/19/2022 |
1.0.0 | 12,818 | 1/19/2022 |