🚀 A powerful and feature-rich .NET Core client library for Keycloak that simplifies integration with Keycloak's authentication and authorization services. This enterprise-ready library provides a comprehensive implementation of Keycloak's REST API, with full support for OpenID Connect, OAuth 2.0, and User-Managed Access (UMA 2.0) protocols.
| Category | Supported Versions |
|---|---|
| .NET | 8.0, 9.0, 10.0 |
| Dependencies | ASP.NET Core, Microsoft.Extensions.DependencyInjection, Newtonsoft.Json |
| Keycloak Version | Support |
|---|---|
| 26.x | ✅ |
| 25.x | ✅ |
| 24.x | ✅ |
| 23.x | ✅ |
| 22.x | ✅ |
| 21.x | ✅ |
| 20.x | ✅ |
- 🔄 Complete Keycloak REST API integration
- 🛡️ Robust security with OpenID Connect and OAuth 2.0
- 📊 Built-in monitoring and performance metrics
- 🔍 Comprehensive error handling and debugging
- 🚦 Automated token management and renewal
- 👥 Advanced user and group management
- 🔑 Multiple authentication flows support
- 📈 Enterprise-grade scalability
- 📊 Organizations support
To integrate the Keycloak client library into your .NET Core application, simply add the NuGet package:
Install-Package Keycloak.NETCore.Client- ✳️ .NET Core SDK (version 6.0 or later)
- 🖥️ A running Keycloak instance
- 🔑 Client credentials and realm configuration
- Add the Keycloak client to your services in
Program.csorStartup.cs:
services.AddKeycloakAuthentication(options =>
{
options.KeycloakBaseUrl = "http://localhost:8080";
options.RealmAdminCredentials = new KcClientCredentials
{
ClientId = "your-client-id",
Secret = "your-client-secret"
};
});Here's a quick example of how to use the library:
// Create Keycloak client
var keycloakClient = new KeycloakClient("http://localhost:8080");
// Authenticate
var token = await keycloakClient.Auth.GetClientCredentialsTokenAsync(
"your-realm",
new KcClientCredentials
{
ClientId = "your-client-id",
Secret = "your-client-secret"
});
// Check for authentication errors
if (token.IsError)
{
Console.WriteLine($"Authentication error: {token.ErrorMessage}");
return;
}
// Get the actual token from the Response property
var accessToken = token.Response.AccessToken;
Console.WriteLine($"Successfully authenticated. Access token obtained.");
// Use the token for other operations
var users = await keycloakClient.Users.GetAsync(
"your-realm",
token.AccessToken,
new KcUserFilter { Max = 10 });var client = new KeycloakClient("http://localhost:8080");
var token = await client.Auth.GetClientCredentialsTokenAsync(realm, credentials);
// Get count of all organizations
var count = await client.Organizations.CountAsync(realm, token.Response.AccessToken);
// List organizations with filter
var filter = new KcOrganizationFilter
{
Search = "test",
Exact = false,
Max = 50
};
var orgs = await client.Organizations.ListAsync(realm, token.Response.AccessToken, filter);
// Get specific organization
var org = await client.Organizations.GetAsync(realm, token.Response.AccessToken, orgId);var client = new KeycloakClient("http://localhost:8080");
var token = await client.Auth.GetClientCredentialsTokenAsync(realm, credentials);
// Get all members of an organization
var members = await client.Organizations.GetMembersAsync(
realm,
token.Response.AccessToken,
organizationId);
// Get count of members
var count = await client.Organizations.GetMembersCountAsync(
realm,
token.Response.AccessToken,
organizationId);
// Filter members by membership type
var filter = new KcOrganizationMemberFilter
{
MembershipType = KcMembershipType.Managed,
Search = "john",
Exact = false,
Max = 50
};
var managedMembers = await client.Organizations.GetMembersAsync(
realm,
token.Response.AccessToken,
organizationId,
filter);
// Add an existing user as a member of the organization
var addResult = await client.Organizations.AddMemberAsync(
realm,
token.Response.AccessToken,
organizationId,
userId);
// Invite a user by email (sends invitation or registration link)
var emailInvite = new KcInviteUserByEmailRequest
{
Email = "user@example.com",
FirstName = "John",
LastName = "Doe"
};
var inviteByEmailResult = await client.Organizations.InviteUserByEmailAsync(
realm,
token.Response.AccessToken,
organizationId,
emailInvite);
// Invite an existing user to the organization (by user ID)
var inviteResult = await client.Organizations.InviteExistingUserAsync(
realm,
token.Response.AccessToken,
organizationId,
userId);
// Remove a member from the organization
var removeResult = await client.Organizations.RemoveMemberAsync(
realm,
token.Response.AccessToken,
organizationId,
memberId);
// Get all organizations associated with a member
var memberOrgs = await client.Organizations.GetMemberOrganizationsAsync(
realm,
token.Response.AccessToken,
organizationId,
memberId);
// Get full representation of member's organizations (not just brief)
var memberOrgsFilter = new KcOrganizationFilter
{
BriefRepresentation = false
};
var memberOrgsFull = await client.Organizations.GetMemberOrganizationsAsync(
realm,
token.Response.AccessToken,
organizationId,
memberId,
memberOrgsFilter);Explore our comprehensive documentation for each module:
-
- JWT Bearer Authentication
- Role Claims Transformation
- Security Best Practices
-
- UMA 2.0 Authorization
- Policy Enforcement
- Protected Resources
-
- Type-safe responses
- Error handling
- Response Models
-
- Performance tracking
- Health checks
- System diagnostics
-
- Token lifecycle
- Multiple auth flows
- Security features
-
- User operations
- Role management
- Group handling
-
- Configuration
- Service accounts
- Client scopes
Our library includes an extensive test suite ensuring reliability across multiple Keycloak versions (20.x through 26.x). The testing infrastructure leverages Docker and Ansible for automated setup and execution.
-
- Test patterns
- Setup instructions
- Mock data structure
-
- Environment setup
- Configuration management
- Container orchestration
-
Version Coverage:
- Supports Keycloak 20.x through 26.x
- Automated environment setup per version
- Parallel version testing
-
Test Categories:
- Authentication flows
- Authorization mechanisms
- Client operations
- Group management
- User operations
-
Infrastructure:
- Docker-based environments
- Ansible automation
- Continuous Integration ready
- Comprehensive mock data
# Install test environment dependencies
cd NETCore.Keycloak.Client.Tests
make install_virtual_env
# Run tests for all supported versions
dotnet cake e2e_test.cakeThis project is licensed under the MIT License - see the LICENSE file for details.
We welcome contributions from the community! Please check our Contributing Guidelines for details on:
- Branch naming conventions
- Code style and formatting rules
- Pull request process
- Security guidelines
⭐ Star us on GitHub | 📫 Report Issues | 📚 Read the Docs