HTTP Admin REST API

Keycloak.AuthServices has to options for integration with the Admin REST API.

NuGet	Description
Keycloak.AuthServices.Sdk	Provides a typed HTTP Client to work with Keycloak Admin HTTP REST API. A high quality SDK client written manually, but not all functionality is implemented.
Keycloak.AuthServices.Sdk.Kiota	A client generated based on OpenAPI Spec, full functionality covered

The Admin REST API in Keycloak provides a programmatic way to manage and administer Keycloak instances. It allows you to perform various administrative tasks such as creating and managing realms, users, roles, clients, and more. To interact with the Admin REST API, you can use HTTP requests to send commands and retrieve data. The API follows the REST architectural style and is designed to be simple and intuitive to use.

NOTE

See full list of API endpoints - Admin REST API

Keycloak provides a comprehensive set of endpoints that cover a wide range of administrative operations. These endpoints are organized into different resource types, such as realms, users, roles, and clients, making it easy to navigate and manipulate the Keycloak configuration.

❗ To get started with the Admin REST API, you need to authenticate and obtain an access token. Once you have the token, you can include it in the Authorization header of your HTTP requests to authenticate and authorize your API calls.

NOTE

See Admin REST API - Server Development documentation for more details.

Add to your code

Install Keycloak.AuthServices.Sdk:

dotnet add package Keycloak.AuthServices.Sdk

IMPORTANT

Admin API is protected so you need to acquire access token somehow. See Access Token Management

You can use IKeycloakClient from Web APIs, Worker, Console apps, etc. It is fully integrated with IHttpClientFactory and therefore you don't need to worry about HttpClient lifetime and the way you work with it.

To add it to DI, you can use convenience extensions method AddKeycloakAdminHttpClient:

/// <summary>
/// Adds <see cref="IKeycloakClient"/>, <see cref="IKeycloakRealmClient"/>, <see cref="IKeycloakUserClient"/>, <see cref="IKeycloakGroupClient"/> HTTP clients for Keycloak Admin API.
/// </summary>
/// <returns>The IHttpClientBuilder for further configuration.</returns>
public static IHttpClientBuilder AddKeycloakAdminHttpClient(
    this IServiceCollection services,
    IConfiguration configuration,
    Action<HttpClient>? configureClient = default,
    string keycloakClientSectionName = KeycloakAdminClientOptions.Section
)

It registers typed client with umbrella interface IKeycloakClient and adds KeycloakAdminClientOptions to DI so you can use it as IOptions<KeycloakAdminClientOptions> in your code.

NOTE

💡 AddKeycloakAdminHttpClient returns IHttpClientBuilder so you can proceed and configure underlying HttpClient.

For example, here is how to add Polly and some custom delegating handlers:

services
  .AddKeycloakAdminHttpClient(configuration)
  .AddStandardResilienceHandler()
  .AddHttpMessageHandler<TimingHandler>()
  .AddHttpMessageHandler<ValidateHeaderHandler>();

Console App

Here is how to use it from a Console App:

var services = new ServiceCollection();

var keycloakOptions = new KeycloakAdminClientOptions
{
    AuthServerUrl = "http://localhost:8080/",
    Realm = "master",
    Resource = "admin-api",
};
services.AddKeycloakAdminHttpClient(keycloakOptions);

var sp = services.BuildServiceProvider();
var client = sp.GetRequiredService<IKeycloakClient>();

var realm = await client.GetRealmAsync("Test");

WARNING

In the code above the key part is missing - Authentication and Authorization. Because of that, you will receive 401 (Unauthorized). In the next section I will show you how to obtain access token and successfully invoke Admin API endpoints.

Here is IKeycloakClient:

namespace Keycloak.AuthServices.Sdk.Admin;

/// <summary>
/// Keycloak Admin API Client
/// </summary>
/// <remarks>
/// Aggregates multiple clients
/// </remarks>
public interface IKeycloakClient
    : IKeycloakRealmClient,
        IKeycloakUserClient,
        IKeycloakGroupClient { }