Keycloak.AdminClient 1.0.0

Keycloak

A C# library for interacting with a Keycloak authentication server (Keycloak 17+). It provides admin API clients and ASP.NET Core JWT bearer authentication.

Requirements

• .NET Standard 2.0+ (admin API client)
• .NET 8.0+ (JWT bearer authentication extensions)
• Keycloak 17+ (modern URL paths without /auth prefix)

Installation

dotnet add package Keycloak.AdminClient

Or reference the Keycloak project directly from this repository.

Configuration

Recommended: nested Keycloak section

{
  "Keycloak": {
    "ServerUrl": "https://keycloak.example.com",
    "Realm": "myrealm",
    "ClientId": "my-service",
    "ClientSecret": "your-client-secret",
    "ServerSkew": 30,
    "ValidateClientId": true
  }
}

Legacy flat keys (still supported)

{
  "KeycloakServer": "https://keycloak.example.com",
  "Realm": "myrealm",
  "ClientId": "my-service",
  "ClientSecret": "your-client-secret"
}

Dependency injection

using Keycloak.Extensions;

// Program.cs / Startup.cs
builder.Services.AddKeycloak(builder.Configuration);
builder.Services.AddKeycloakAuthentication(); // Requires .NET 8+ app referencing net8.0 build

var app = builder.Build();
app.UseKeycloakAuthentication(); // UseAuthentication + UseAuthorization

AddKeycloak registers:

• KeycloakOptions
• IKeycloakClient
• IUserService
• IKeyService
• IRealmService

Usage examples

Create a user

public class MyController
{
    private readonly IUserService _users;

    public MyController(IUserService users) => _users = users;

    public async Task<string> Register(string username, string email)
    {
        return await _users.CreateUserAsync(new UserRepresentation
        {
            UserName = username,
            EmailAddress = email,
            Enabled = true,
        });
    }
}

Reset a password

await _users.ResetUserPasswordAsync(new CredentialRepresentation
{
    Value = "new-password",
    Temporary = true,
}, userId);

Send a required-action email

using Keycloak.Constants.Enums;

await _users.SendEmailAsync(userId, new[]
{
    RequiredActionsEnum.UpdatePassword,
    RequiredActionsEnum.VerifyEmail,
});

Query realm events

var events = await _realmService.GetRealmEventsAsync(new EventQuery
{
    Client = "my-app",
    FromDate = DateTime.UtcNow.AddDays(-7),
    Max = 100,
});

Manual client construction (without DI)

var client = new KeycloakClient(new KeycloakOptions
{
    ServerUrl = "https://keycloak.example.com",
    Realm = "myrealm",
    ClientId = "my-service",
    ClientSecret = "secret",
});

var userService = new UserService(client);

Error handling

API failures throw KeycloakApiException with StatusCode, ResponseBody, and RequestUri. Token acquisition failures throw KeycloakAuthenticationException. Configuration problems throw KeycloakConfigurationException.

try
{
    await _users.CreateUserAsync(user);
}
catch (KeycloakApiException ex) when (ex.StatusCode == HttpStatusCode.Conflict)
{
    // User already exists
}

Breaking changes (recent versions)

If upgrading from an older version of this library:

1. URL paths — Keycloak 17+ uses /realms/... and /admin/realms/... instead of /auth/realms/....
2. Static services removed — Use IUserService, IKeyService, IRealmService via DI instead of UserService.CreateUserAsync(client, ...).
3. Null on failure removed — Service methods throw KeycloakApiException instead of returning null.
4. HttpResponseMessage return types removed — Update/Delete/Email methods return Task and throw on failure.
5. IKeycloakClient.Client removed — HttpClient is no longer exposed on the interface.
6. Custom token middleware removed — Use AddKeycloakAuthentication() and UseKeycloakAuthentication() instead of UseKeycloakTokenValidation().
7. Custom JWT validation helpers removed — Incoming token validation is handled by ASP.NET Core JWT bearer; admin client expiry uses TokenValidator.IsAccessTokenValid().

Authentication

AddKeycloakAuthentication() configures standard ASP.NET Core JWT bearer authentication using your Keycloak realm authority, ServerSkew, and optional azp validation (ValidateClientId).

It populates HttpContext.User so downstream code can use [Authorize], policies, and User.Identity.

Requires AddKeycloak() to be registered first.

Publishing to NuGet (Trusted Publishing)

Package ID: Keycloak.AdminClient

Publishing uses NuGet Trusted Publishing via the Publish NuGet GitHub Actions workflow.

One-time nuget.org setup

1. Sign in to nuget.org as MattUssher (your profile username).
2. Open Account → Trusted Publishing → Add policy.
3. Use these values exactly:

Important:

• Workflow file is the YAML filename only — not the workflow display name Publish NuGet.
• Environment must match the GitHub Actions environment used by the publish job (prod).
• user in the workflow must be the NuGet username of the person who created the policy (MattUssher), not an organization name.
• If the repo is private, the policy starts in a 7-day trial. Re-activate it on nuget.org if that window expired before the first successful login.

One-time GitHub setup

1. Create an Actions environment named prod:
   • GitHub repo → Settings → Environments → New environment → name it prod
2. Add a repository secret:

Do not add a long-lived NUGET_API_KEY when using Trusted Publishing.

Publish

Run Actions → Publish NuGet → Run workflow, or publish a GitHub release.

Testing

dotnet test Keycloak.Test/Keycloak.Test.csproj

License

MIT — see LICENSE.