KeyCloak.ManagementApi 1.4.2

KeyCloak.ManagementApi

A .NET Standard 2.0 library for interacting with KeyCloak's Management API, designed with a similar API structure to Auth0.ManagementApi for easier migration from Auth0 to KeyCloak.

Compatibility

• .NET Standard 2.0 (compatible with .NET Framework 4.6.1+ and .NET Core 2.0+)
• .NET Framework 4.6.1+
• .NET Core 2.0+
• .NET 5.0+
• .NET 6.0+
• .NET 8.0+

Installation

You can reference this project directly or package it as a NuGet package.

To create a NuGet package:

dotnet pack -c Release

Getting Started

Authentication

First, you need to obtain an access token from KeyCloak. This can be done using client credentials flow:

using System;
using System.Net.Http;
using System.Collections.Generic;
using System.Threading.Tasks;

public async Task<string> GetAccessTokenAsync(
    string keycloakUrl,
    string realm,
    string clientId,
    string clientSecret)
{
    using (var httpClient = new HttpClient())
    {
        var tokenEndpoint = $"{keycloakUrl}/realms/{realm}/protocol/openid-connect/token";

        var content = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("grant_type", "client_credentials"),
            new KeyValuePair<string, string>("client_id", clientId),
            new KeyValuePair<string, string>("client_secret", clientSecret)
        });

        var response = await httpClient.PostAsync(tokenEndpoint, content);
        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync();
        dynamic result = Newtonsoft.Json.JsonConvert.DeserializeObject(json);
        return result.access_token;
    }
}

Initialize the Management API Client

using KeyCloak.ManagementApi;

var keycloakUrl = "https://keycloak.example.com";
var realm = "master";
var accessToken = await GetAccessTokenAsync(keycloakUrl, realm, clientId, clientSecret);

var client = new ManagementApiClient(keycloakUrl, realm, accessToken);

Usage Examples

User Management

Get all users

var users = await client.Users.GetAllAsync();
foreach (var user in users)
{
    Console.WriteLine($"{user.Username} - {user.Email}");
}

Get a specific user

var user = await client.Users.GetAsync("user-id-here");
Console.WriteLine($"User: {user.Username} ({user.Email})");

Create a new user

using KeyCloak.ManagementApi.Models;

var newUser = new UserCreateRequest
{
    Username = "john.doe",
    Email = "john.doe@example.com",
    FirstName = "John",
    LastName = "Doe",
    Enabled = true,
    EmailVerified = true,
    Credentials = new List<Credential>
    {
        new Credential
        {
            Type = "password",
            Value = "SecurePassword123!",
            Temporary = false
        }
    }
};

var userId = await client.Users.CreateAsync(newUser);
Console.WriteLine($"Created user with ID: {userId}");

Update a user

var updateRequest = new UserUpdateRequest
{
    Email = "newemail@example.com",
    FirstName = "John",
    LastName = "Doe",
    Enabled = true
};

await client.Users.UpdateAsync("user-id-here", updateRequest);

Delete a user

await client.Users.DeleteAsync("user-id-here");

Reset user password

await client.Users.ResetPasswordAsync("user-id-here", "NewPassword123!", temporary: false);

Role Management

Get all roles

var roles = await client.Roles.GetAllAsync();
foreach (var role in roles)
{
    Console.WriteLine($"Role: {role.Name} - {role.Description}");
}

Create a new role

var newRole = new RoleCreateRequest
{
    Name = "premium-user",
    Description = "Premium user role with additional privileges"
};

await client.Roles.CreateAsync(newRole);

Assign roles to a user

// Get the roles you want to assign
var roles = await client.Roles.GetAllAsync();
var premiumRole = roles.Find(r => r.Name == "premium-user");

await client.Users.AssignRolesAsync("user-id-here", new List<Role> { premiumRole });

Get user's roles

var userRoles = await client.Users.GetRolesAsync("user-id-here");
foreach (var role in userRoles)
{
    Console.WriteLine($"User has role: {role.Name}");
}

Client (Application) Management

Get all clients

var clients = await client.Clients.GetAllAsync();
foreach (var c in clients)
{
    Console.WriteLine($"Client: {c.ClientId} - {c.Name}");
}

Create a new client

var newClient = new ClientCreateRequest
{
    ClientId = "my-app",
    Name = "My Application",
    Enabled = true,
    PublicClient = false,
    StandardFlowEnabled = true,
    DirectAccessGrantsEnabled = true,
    ServiceAccountsEnabled = true,
    RedirectUris = new List<string>
    {
        "https://myapp.example.com/callback"
    },
    WebOrigins = new List<string>
    {
        "https://myapp.example.com"
    }
};

var clientId = await client.Clients.CreateAsync(newClient);
Console.WriteLine($"Created client with ID: {clientId}");

Get client secret

var secret = await client.Clients.GetSecretAsync("client-id-here");
Console.WriteLine($"Client secret: {secret}");

Regenerate client secret

var newSecret = await client.Clients.RegenerateSecretAsync("client-id-here");
Console.WriteLine($"New client secret: {newSecret}");

Group Management

Get all groups

var groups = await client.Groups.GetAllAsync();
foreach (var group in groups)
{
    Console.WriteLine($"Group: {group.Name} ({group.Path})");
}

Create a new group

var newGroup = new GroupCreateRequest
{
    Name = "administrators"
};

var groupId = await client.Groups.CreateAsync(newGroup);

Add user to a group

await client.Users.JoinGroupAsync("user-id-here", "group-id-here");

Get group members

var members = await client.Groups.GetMembersAsync("group-id-here");
foreach (var member in members)
{
    Console.WriteLine($"Member: {member.Username}");
}

Create a subgroup

var subGroup = new GroupCreateRequest
{
    Name = "sub-admins"
};

var subGroupId = await client.Groups.CreateSubGroupAsync("parent-group-id", subGroup);

Migration from Auth0.ManagementApi

The API structure is intentionally similar to Auth0.ManagementApi. Here's a comparison:

Auth0 Code:

// Auth0
var auth0Client = new ManagementApiClient(token, new Uri(domain));
var users = await auth0Client.Users.GetAllAsync(new GetUsersRequest());
var user = await auth0Client.Users.GetAsync("user-id");

KeyCloak Equivalent:

// KeyCloak
var keycloakClient = new ManagementApiClient(baseUrl, realm, token);
var users = await keycloakClient.Users.GetAllAsync();
var user = await keycloakClient.Users.GetAsync("user-id");

Key Differences from Auth0

1. Realm-based: KeyCloak is multi-tenant with realms, so you specify the realm when initializing
2. Authentication: You need to obtain the access token separately (typically using client credentials flow)
3. User Attributes: In KeyCloak, custom attributes are stored in a dictionary: Dictionary<string, List<string>>
4. Client vs Application: What Auth0 calls "Applications" or "Clients", KeyCloak also calls "Clients"

Error Handling

The library throws exceptions on API errors. Always wrap calls in try-catch blocks:

try
{
    var user = await client.Users.GetAsync("user-id");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"API Error: {ex.Message}");
}

Custom HttpClient

If you need to configure the HttpClient (for proxies, custom timeouts, etc.):

var httpClient = new HttpClient
{
    Timeout = TimeSpan.FromSeconds(30)
};

var client = new ManagementApiClient(keycloakUrl, realm, accessToken, httpClient);

License

This project is provided as-is for migrating from Auth0 to KeyCloak.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.