Keycloak.NETCore.Clientv2 1.4.0

🔐 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

✅ Version Compatibility

🌟 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
• 📊 Organizations support

📚 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 Core SDK (version 6.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",
        Secret = "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",
        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 });

📊 Organizations

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

📊 Organization Members

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

📚 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

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

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