Keycloak.AdminSdk 0.1.0-preview.1

Keycloak.AdminSdk

SDK .NET 10 fortemente tipado para integração e administração do Keycloak pela Admin REST API.

0.1.0-preview.1: preview para validação pública. Consulte a matriz de compatibilidade antes de utilizar em produção.

Principais recursos

• Realms, Users, Clients, Client Scopes, Roles, Groups, Protocol Mappers, Identity Providers, Sessions e Events.
• API baseada em interfaces e integrada à DI nativa do .NET.
• Contextos imutáveis para múltiplos Realms.
• Client Credentials recomendado e Password Grant opcional.
• Cache e renovação concorrente de tokens.
• IHttpClientFactory, retry seguro, jitter, circuit breaker e timeouts.
• Provisionamento fluído com compensação de falhas.
• OpenTelemetry opcional: logs estruturados, traces e métricas.

Instalação

dotnet add package Keycloak.AdminSdk --version 0.1.0-preview.1

Configuração mínima

builder.Services.AddKeycloakAdmin(options =>
{
    options.ServerUrl = new Uri("https://identity.example.com");
    options.DefaultRealm = "customers";
    options.AuthenticationRealm = "master";
    options.Authentication.ClientCredentials.ClientId = "admin-service";
    options.Authentication.ClientCredentials.ClientSecret = secret;
});

Uso

var tenant = keycloak.ForRealm("tenant-a");

var user = await tenant.Users.CreateAsync(
    new CreateUserRequest("alice") { Email = "alice@example.com" });

var group = await tenant.Groups.CreateAsync(new CreateGroupRequest("operators"));
await tenant.Groups.AddUserAsync(group.Id, user.Id);

Documentação

• Visão geral
• Instalação passo a passo
• Configuração
• Módulos e exemplos
• OpenTelemetry e Grafana
• Segurança
• Compatibilidade e versionamento
• Cobertura de endpoints
• Política da API pública
• Estratégia e matriz de testes
• Troubleshooting

Extensão opcional de diagnóstico

Depois que o SDK principal estiver integrado e confiável, o pacote separado Keycloak.AdminSdk.Diagnostics.Mcp pode expor diagnósticos sanitizados e read-only para agentes autorizados. Ele é desabilitado por padrão e não participa do transporte de telemetria.

Arquitetura de observabilidade

OTLP é o transporte de logs, traces e métricas para Grafana ou outro backend. MCP é uma interface opcional para uma IA consultar diagnósticos sanitizados; não é utilizado como exporter.

Aplicação → OpenTelemetry/OTLP → Collector → Grafana
         └→ Diagnostic Sink → MCP read-only → IA

Nenhum exporter, servidor MCP ou provedor de IA é ativado automaticamente pelo pacote principal. Consulte o threat model antes de habilitar MCP.

Testes locais

docker-compose up -d
dotnet test Keycloak.AdminSdk.sln --configuration Release
dotnet test tests/Keycloak.AdminSdk.IntegrationTests `
  --settings tests/Keycloak.AdminSdk.IntegrationTests/local.runsettings

Licença

MIT.