.NET / C# Keycloak.RestApiClient

This is a .NET / C# REST API client

• for the Keycloak Admin REST API
• auto-generated by OpenAPI Generator
• using the OpenAPI definitions provided by Keycloak

Documentation for API Endpoints

• Official documentation: Keycloak Admin REST API
• Generated Swagger UI: Swagger Editor

Keycloak versions supported

Frameworks supported

• .NET Core >=1.0
• .NET Framework >=4.6
• Mono/Xamarin >=vNext

Installation

Install from NuGet package

Install-Package Schick.Keycloak.RestApiClient

Getting Started

Method names

Method names are humanized:

GET on path /{realm}/users becomes GetUsers(Async)

GET on path /{realm}/identity-provider/providers/{provider_id} becomes GetIdentityProviderProvidersByProviderId(Async)

Authentication

You can select authentication flow either by the username and password or by providing client ID and client secret.

Sample code

With authentication by username/password

using FS.Keycloak.RestApiClient.Api;
using FS.Keycloak.RestApiClient.Authentication.ClientFactory;
using FS.Keycloak.RestApiClient.Authentication.Flow;
using FS.Keycloak.RestApiClient.ClientFactory;

var credentials = new PasswordGrantFlow
{
    KeycloakUrl = "https://<keycloak-url>",
    Realm = "<realm>",
    UserName = "<username>",
    Password = "<password>"
};

using var httpClient = AuthenticationHttpClientFactory.Create(credentials);
using var usersApi = ApiClientFactory.Create<UsersApi>(httpClient);

var users = await usersApi.GetUsersAsync("<realm>");
Console.WriteLine($"Users: {users.Count}");

With authentication by client-id/client-secret

using FS.Keycloak.RestApiClient.Api;
using FS.Keycloak.RestApiClient.Authentication.ClientFactory;
using FS.Keycloak.RestApiClient.Authentication.Flow;
using FS.Keycloak.RestApiClient.ClientFactory;

var credentials = new ClientCredentialsFlow
{
    KeycloakUrl = "https://<keycloak-url>",
    Realm = "<realm>",
    ClientId = "<client-id>",
    ClientSecret = "<client-secret>"
};

using var httpClient = AuthenticationHttpClientFactory.Create(credentials);
using var usersApi = ApiClientFactory.Create<UsersApi>(httpClient);

var users = await usersApi.GetUsersAsync("<realm>");
Console.WriteLine($"Users: {users.Count}");

Advanced Usage

To use the API client with a HTTP proxy, setup a System.Net.WebProxy

Configuration c = new Configuration();
System.Net.WebProxy webProxy = new System.Net.WebProxy("http://myProxyUrl:80/");
webProxy.Credentials = System.Net.CredentialCache.DefaultCredentials;
c.Proxy = webProxy;

Connections

Each ApiClass (properly the ApiClient inside it) will create an instance of HttpClient. It will use that for the entire lifecycle and dispose it when called the Dispose method.

To better manager the connections it's a common practice to reuse the HttpClient and HttpClientHandler (see here for details). To use your own HttpClient instance just pass it to the ApiClass constructor.

HttpClientHandler yourHandler = new HttpClientHandler();
HttpClient yourHttpClient = new HttpClient(yourHandler);
var api = new YourApiClass(yourHttpClient, yourHandler);

If you want to use an HttpClient and don't have access to the handler, for example in a DI context in Asp.net Core when using IHttpClientFactory.

HttpClient yourHttpClient = new HttpClient();
var api = new YourApiClass(yourHttpClient);

You'll loose some configuration settings, the features affected are: Setting and Retrieving Cookies, Client Certificates, Proxy settings. You need to either manually handle those in your setup of the HttpClient or they won't be available.

Here an example of DI setup in a sample web project:

services.AddHttpClient<YourApiClass>(httpClient => new PetApi(httpClient));