BTW.KeycloakJwtGenerator 1.0.0

📦 BTW.KeycloakJwtGenerator

Librería .NET para generar JWT centralizados usando Keycloak como Identity Provider. Permite que sistemas con autenticación propia (LDAP, Base de Datos, Active Directory, etc.) generen tokens JWT estandarizados con claims personalizados.

🎯 ¿Para Qué Sirve?

Tu Sistema (auth propia) → BTW.KeycloakJwtGenerator → Keycloak → JWT con tus claims

• ✅ Tu sistema mantiene su mecanismo de autenticación (BD, LDAP, AD)
• ✅ Keycloak genera JWT estandarizados
• ✅ Incluye los claims personalizados que necesites
• ✅ Todos tus sistemas validan el mismo JWT

📦 Instalación

dotnet add package BTW.KeycloakJwtGenerator

⚡ Requisitos

• .NET 6.0 o superior
• .NET 7.0 o superior
• .NET 8.0 o superior

La librería es compatible con las versiones .NET 6, .NET 7 y .NET 8.

🚀 Uso Rápido

1. Configurar en appsettings.json

{
  "KeycloakJwt": {
    "BaseUrl": "http://localhost:8080",
    "Realm": "mi-realm",
    "ClientId": "mi-sistema",
    "ClientSecret": "mi-secret",
    "SystemName": "Sistema A"
  }
}

2. Registrar en Program.cs

// Opción 1: Desde appsettings.json
builder.Services.AddKeycloakJwtGenerator(builder.Configuration);

// Opción 2: Configuración fluida
builder.Services
    .AddKeycloakJwt()
    .WithBaseUrl("http://localhost:8080")
    .WithRealm("mi-realm")
    .WithClient("mi-cliente", "mi-secret")
    .WithSystemName("Sistema A")
    .Build();

// Opción 3: Con Action
builder.Services.AddKeycloakJwtGenerator(options =>
{
    options.BaseUrl = "http://localhost:8080";
    options.Realm = "mi-realm";
    options.ClientId = "mi-cliente";
    options.ClientSecret = "mi-secret";
    options.SystemName = "Sistema A";
});

3. Usar en tu código

public class AuthController : ControllerBase
{
    private readonly IKeycloakJwtGenerator _jwtGenerator;

    public AuthController(IKeycloakJwtGenerator jwtGenerator)
    {
        _jwtGenerator = jwtGenerator;
    }

    [HttpPost("login")]
    public async Task<IActionResult> Login(LoginRequest request)
    {
        // 1. Tu autenticación local (BD, LDAP, etc.)
        var user = await _myAuthService.ValidateAsync(request.Username, request.Password);
        
        if (user == null)
            return Unauthorized();

        // 2. Definir claims personalizados
        var claims = new Dictionary<string, object>
        {
            ["departamento"] = user.Departamento,
            ["nivel_acceso"] = user.NivelAcceso,
            ["permisos"] = user.Permisos,        // Array
            ["sucursal"] = user.Sucursal,
            ["metadata"] = new {                  // Objeto anidado
                zona = user.Zona,
                codigo = user.Codigo
            }
        };

        // 3. Generar JWT con Keycloak
        var token = await _jwtGenerator.GenerateTokenAsync(request.Username, claims);

        return Ok(new
        {
            accessToken = token.AccessToken,
            refreshToken = token.RefreshToken,
            expiresIn = token.ExpiresIn
        });
    }
}

📋 API Completa

Generar Token (Simple)

var token = await _jwtGenerator.GenerateTokenAsync(
    "usuario",
    new Dictionary<string, object>
    {
        ["departamento"] = "ventas",
        ["permisos"] = new[] { "leer", "escribir" }
    });

Generar Token (Request Completo)

var token = await _jwtGenerator.GenerateTokenAsync(new GenerateTokenRequest
{
    Username = "usuario",
    Email = "usuario@empresa.com",
    FirstName = "Juan",
    LastName = "Pérez",
    Roles = new List<string> { "user", "admin" },
    Claims = new Dictionary<string, object>
    {
        ["departamento"] = "ventas"
    }
});

Refrescar Token

var newToken = await _jwtGenerator.RefreshTokenAsync(refreshToken);

Validar Token

bool isValid = await _jwtGenerator.ValidateTokenAsync(accessToken);

Revocar Token (Logout)

await _jwtGenerator.RevokeTokenAsync(refreshToken);

🔐 Validar JWT en Otros Sistemas

Para sistemas que solo necesitan validar tokens (no generarlos):

// Solo agrega validación de JWT
builder.Services.AddKeycloakJwtValidation(builder.Configuration);

// O ambos (generar y validar)
builder.Services.AddKeycloakJwtFull(builder.Configuration);

Luego usa [Authorize] normalmente:

[Authorize]
[HttpGet("protected")]
public IActionResult Protected()
{
    var departamento = User.FindFirst("departamento")?.Value;
    return Ok(new { departamento });
}

⚙️ Configuración Completa

{
  "KeycloakJwt": {
    "BaseUrl": "http://localhost:8080",
    "Realm": "mi-realm",
    "ClientId": "mi-sistema",
    "ClientSecret": "secret",
    "SystemName": "Sistema A",
    "TimeoutSeconds": 30,
    "EnableAdminTokenCache": true,
    "AdminTokenCacheMinutes": 4,
    "UseTokenExchange": true,
    "MaxRetries": 3
  }
}

🛠️ Configuración de Keycloak

1. Crear Client (Service Account)

Clients → Create client
├── Client ID: "mi-sistema"
├── Client authentication: ON
├── Service accounts roles: ✅
└── Save

2. Asignar Roles al Service Account

Client → Service account roles → Assign role
├── manage-users
├── view-users
└── impersonation (para Token Exchange)

3. Crear Protocol Mappers

Client → Client scopes → Dedicated scope → Mappers
├── Mapper type: "User Attribute"
├── User Attribute: "departamento"
├── Token Claim Name: "departamento"
├── Add to access token: ✅
└── Save

4. Habilitar Token Exchange (opcional)

Si estás ejecutando Keycloak con Docker, agrega esta configuración para habilitar Token Exchange:

# docker-compose.yml (configuración de Keycloak, no de tu aplicación)
services:
  keycloak:
    image: quay.io/keycloak/keycloak:latest
    environment:
      KC_FEATURES: token-exchange
      # ... otras configuraciones

Nota: Esta configuración es solo para Keycloak. Si Keycloak ya tiene Token Exchange habilitado o usas otra forma de instalación, puedes omitir este paso.

📄 Licencia

MIT License - ver LICENSE

Desarrollado con ❤️ por By The Wave (BTW)