🔐 Keycloak Client for .NET Core

<div align="center"> <img src="assets/kc_logo.svg" alt="Keycloak .NET Core Client Logo" width="200"> </div>

🚀 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.

---

---

<div align="center">

---

</div>

⚙️ Requirements

| Category | Supported Versions | | ------------ | ----------------------------------------------------------------------- | | .NET | 8.0, 9.0, 10.0 | | Dependencies | ASP.NET Core, Microsoft.Extensions.DependencyInjection, Newtonsoft.Json |

✅ Version Compatibility

| Keycloak Version | Support | | ---------------- | ------- | | 26.x | ✅ | | 25.x | ✅ | | 24.x | ✅ |

Note: Keycloak versions 20.x through 23.x and .NET 6.0/7.0 were supported in previous releases (v1.x). If you need support for these older versions, please use v1.0.2.

🌟 Key Features

• 🔄 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

📚 Table of Contents

• 🔐 Keycloak Client for .NET Core
  • ⚙️ Requirements
  • ✅ Version Compatibility
  • 🌟 Key Features
  • 📚 Table of Contents
  • 💻 Installation
  • 🚀 Getting Started
    • 📋 Prerequisites
    • 🔧 Basic Setup
  • 📖 Basic Usage
  • 📚 Documentation
  • 🧪 Testing
    • 📋 Test Documentation
    • 🔬 Key Testing Features
    • ⚡ Running Tests
  • 🤝 Contributing
  • 📄 License

💻 Installation

To integrate the Keycloak client library into your .NET Core application, simply add the NuGet package:

Install-Package Keycloak.NETCore.Client

🚀 Getting Started

📋 Prerequisites

• ✳️ .NET SDK (version 8.0 or later)
• 🖥️ A running Keycloak instance
• 🔑 Client credentials and realm configuration

🔧 Basic Setup

1. Add the Keycloak client to your services in Program.cs or Startup.cs:

services.AddKeycloakAuthentication(options =>
{
    options.KeycloakBaseUrl = "http://localhost:8080";
    options.RealmAdminCredentials = new KcClientCredentials
    {
        ClientId = "your-client-id",
        ClientSecret = "your-client-secret"
    };
});

📖 Basic Usage

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",
        ClientSecret = "your-client-secret"
    });

// Use the token for other operations
var users = await keycloakClient.Users.GetAsync(
    "your-realm",
    token.AccessToken,
    new KcUserFilter { Max = 10 });

📚 Documentation

Explore our comprehensive documentation for each module:

• 🔐 API Authentication

  • JWT Bearer Authentication
  • Role Claims Transformation
  • Security Best Practices

• 🛡️ Authorization

  • UMA 2.0 Authorization
  • Policy Enforcement
  • Protected Resources

• 📊 Response Types

  • Type-safe responses
  • Error handling
  • Response Models

• 📈 Monitoring and Metrics

  • Performance tracking
  • Health checks
  • System diagnostics

• 🔑 Authentication Management

  • Token lifecycle
  • Multiple auth flows
  • Security features

• 👥 User Management

  • User operations
  • Role management
  • Group handling

• ⚙️ Client Management

  • Configuration
  • Service accounts
  • Client scopes

🧪 Testing

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 Documentation

• 📘 Test Suite Guide

  • Test patterns
  • Setup instructions
  • Mock data structure

• 🔧 Ansible Setup Guide

  • Environment setup
  • Configuration management
  • Container orchestration

🔬 Key Testing Features

1. Version Coverage:

   • Supports Keycloak 20.x through 26.x
   • Automated environment setup per version
   • Parallel version testing

2. Test Categories:

   • Authentication flows
   • Authorization mechanisms
   • Client operations
   • Group management
   • User operations

3. Infrastructure:

   • Docker-based environments
   • Ansible automation
   • Continuous Integration ready
   • Comprehensive mock data

⚡ Running Tests

# Install test environment dependencies
cd NETCore.Keycloak.Client.Tests
make install_virtual_env

# Run tests for all supported versions
dotnet cake e2e_test.cake

👥 Contributors

Thanks to all the people who contribute to this project!

<a href="https://github.com/hasnimehdi91"><img src="https://github.com/hasnimehdi91.png" width="50" height="50" alt="hasnimehdi91" style="border-radius:50%"></a> <a href="https://github.com/ghaith100994"><img src="https://github.com/ghaith100994.png" width="50" height="50" alt="ghaith100994" style="border-radius:50%"></a>

<sub>Want to see your avatar here? Check our [Contributing Guidelines](CONTRIBUTING