Keycloak.Net.Sdk 1.2.0

Keycloak.Net.Sdk

A modular .NET 8 SDK for integrating with Keycloak using IHttpClientFactory, typed services, and built-in retry policies.

📦 NuGet: Keycloak.Net.Sdk

Features

• Sign up / sign in users
• Manage users (get, enable/disable, set password, delete)
• Manage client roles (get, assign/remove to users)
• Manage realm roles (get, create, delete, assign/remove to users and groups)
• Manage clients (get, create, delete, enable service accounts)
• Manage client scopes
• Manage realms
• Manage groups (create, delete, get, add/remove users)
• Token management (get service-account token, revoke token)
• Built-in retry policy via Polly
• Auth handler that automatically attaches Bearer tokens to requests
• Fully supports IHttpClientFactory and dependency injection

Requirements

• .NET 8+
• A running Keycloak server (v21+)
• A confidential client with Service Accounts Enabled

Installation

dotnet add package Keycloak.Net.Sdk

Configuration

1. appsettings.json

"keycloak": {
  "ServerUrl": "https://your-keycloak-host/",
  "RealmName": "your-realm",
  "ClientId": "your-client-id",
  "ClientSecret": "your-client-secret",
  "ClientUuid": "your-client-uuid",
  "AdminUsername": "admin",
  "AdminPassword": "admin-password",
  "NumberOfRetries": 3,
  "DelayBetweenRetryRequestsInSeconds": 2
}

2. Register Services

builder.Services.AddKeycloak(builder.Configuration);

Usage

Inject the interface you need:

public class MyService(IUserManagement users, IRoleManagement roles)
{
    public async Task CreateAndAssignAsync()
    {
        var signup = await users.SignupAsync(new SignupRequestDto
        {
            Username  = "john.doe",
            Email     = "john@example.com",
            FirstName = "John",
            LastName  = "Doe",
            Password  = "Secret@123"
        });

        await roles.AssignClientRoleToUser(userId: signup.Response.Id, roleId: "role-uuid");
    }
}

Use IRoleManagement for both client roles and realm roles:

public class RoleService(IRoleManagement roles)
{
    // Realm role CRUD
    public async Task CreateRealmRoleAsync()
    {
        await roles.CreateRealmRoleAsync(new CreateRealmRoleRequestDto
        {
            Name        = "admin",
            Description = "Full access role"
        });
    }

    // Assign a realm role to a user
    public async Task AssignRealmRoleToUserAsync(string userId, string roleId, string roleName)
    {
        await roles.AssignRealmRoleToUserAsync(userId, roleId, roleName);
    }

    // Assign a realm role to a group
    public async Task AssignRealmRoleToGroupAsync(string groupId, string roleId, string roleName)
    {
        await roles.AssignRealmRoleToGroupAsync(groupId, roleId, roleName);
    }
}

Or use IGroupManagement to organize users into groups:

public class GroupService(IGroupManagement groups)
{
    public async Task AssignUserToGroupAsync(string userId, string groupId)
    {
        await groups.AddUserToGroupAsync(userId, groupId);
    }

    public async Task<List<GroupResponseDto>> GetUserGroupsAsync(string userId)
    {
        var result = await groups.GetUserGroupsAsync(userId);
        return result.Response;
    }
}

Available Interfaces

Running Tests

Unit Tests

Unit tests use a fake HttpMessageHandler no external dependencies required.

dotnet test Keycloak.Net.Sdk.UnitTests/Keycloak.Net.Sdk.UnitTests.csproj

Integration Tests

Integration tests spin up a real Keycloak instance via Testcontainers. Docker must be running.

dotnet test Keycloak.Net.Sdk.IntegrationTests/Keycloak.Net.Sdk.IntegrationTests.csproj

The fixture automatically handles the full setup sequence:

1. Starts a Keycloak container
2. Creates a dedicated test realm
3. Creates a confidential client with service accounts
4. Grants realm-admin role to the service account
5. Creates a test user, client role, realm role, and group

The first run pulls the Keycloak Docker image (~500 MB). Subsequent runs reuse the cached image.

All Tests

dotnet test

Project Structure

Keycloak.Net.Sdk/                  # SDK source
├── Athentications/                # TokenProvider, TokenManagement, KeycloakAuthHandler
├── Clients/                       # ClientManagement + DTOs
├── Configurations/                # KeycloakConfiguration
├── Contracts/                     # Shared response types (KeycloakBaseResponse)
├── Extensions/                    # ServiceRegistrations, ExceptionHandler
├── Groups/                        # GroupManagement + DTOs
├── Realms/                        # RealmManagement
├── Roles/                         # RoleManagement + DTOs
└── Users/                         # UserManagement + DTOs

Keycloak.Net.Sdk.UnitTests/        # Unit tests (Moq, FakeHttpMessageHandler)
Keycloak.Net.Sdk.IntegrationTests/ # Integration tests (Testcontainers.Keycloak)

License

MIT

Contact

Questions or feedback: miladrivandi73@gmail.com or open an issue.