Introducción

Cuando el tema es autenticación y autorización en aplicaciones modernas, la primera reacción de muchos equipos es recurrir a soluciones cloud de pago — Azure Entra ID, AWS Cognito, Auth0 o Firebase Auth. Son servicios excelentes, pero traen costos que pueden sorprender a medida que crece la base de usuarios: planes por MAU (Monthly Active Users), límites de tokens, cobros por login social y MFA. En muchos escenarios, especialmente startups, proyectos personales, entornos on-premises y empresas que valoran la soberanía de los datos, existe una alternativa gratuita, open-source y de nivel enterprise que merece toda la atención: Keycloak.

Keycloak es un servidor de identidad y gestión de acceso mantenido por la Cloud Native Computing Foundation (CNCF) como proyecto en incubación, creado originalmente por Red Hat. Implementa los protocolos OAuth 2.0, OpenID Connect y SAML 2.0 — los mismos que usan Azure Entra ID, Google y otros proveedores de identidad — pero se ejecuta en tu infraestructura, sin costos de licencia, sin límites de usuarios y con control total sobre los datos. Si ya entiendes los fundamentos de autenticación y autorización con JWT, OAuth2 y OpenID Connect, estás listo para el siguiente paso: poner en marcha un identity provider completo con Docker o Podman e integrarlo con tu aplicación ASP.NET Core con C# 8.0+.

En este artículo ejecuto Keycloak en un contenedor, configuro un realm y un client, lo integro con una API REST en C#, personalizo la pantalla de login con logo y tema propios, y lo comparo con los principales proveedores de identidad de la nube. El enfoque es práctico, funcional y 100% gratuito.

💡 Consejo: Aunque los ejemplos de este artículo usan C# con ASP.NET Core, Keycloak es agnóstico de lenguaje y framework. Al implementar protocolos abiertos (OAuth 2.0, OpenID Connect, SAML 2.0), funciona con cualquier tecnología que soporte estos estándares — incluidos Java/Spring Boot, Python/Django/Flask/FastAPI, Node.js/Express/NestJS, Go, PHP/Laravel, Ruby on Rails, Rust y Angular/React/Vue en el front-end. El setup de Keycloak en contenedor y la configuración de realm/client son idénticos sin importar el lenguaje de tu aplicación.

📦 Código fuente: La implementación completa de este artículo está en el repositorio blog-zocateli-sample en GitHub. Clónalo, explóralo y adáptalo a tu contexto.

¿Por Qué Elegir Keycloak?

Costo Cero vs Proveedores Cloud

El principal argumento a favor de Keycloak es simple: no cuesta nada. Mientras los proveedores cloud cobran por usuario activo o por funcionalidad premium, Keycloak lo ofrece todo gratis:

FuncionalidadKeycloak (Gratuito)Azure Entra IDAWS CognitoAuth0
Costo base$0Gratis hasta 50.000 MAU (External ID)Gratis hasta 50.000 MAUGratis hasta 7.500 MAU
Usuarios ilimitados✅❌ (cobra tras el límite)❌ (cobra tras el límite)❌ (cobra tras el límite)
Login social✅ Ilimitado✅✅✅ (limitado en el plan free)
MFA (Multi-Factor)✅ Incluido✅✅ (costo adicional por SMS)✅ (limitado en el plan free)
SAML + OIDC✅ Ambos✅ Ambos✅ OIDC / ⚠️ SAML limitado✅ Ambos
Personalización de UI✅ Total (temas FreeMarker)⚠️ Limitada⚠️ Limitada✅ (planes de pago)
Self-hosted✅ Obligatorio❌ Solo SaaS❌ Solo SaaS⚠️ Plan Enterprise
Soberanía de los datos✅ Total❌ Datos en Microsoft❌ Datos en AWS❌ Datos en Auth0

💡 Consejo: Keycloak no reemplaza necesariamente a los proveedores cloud en todos los escenarios. Si tu empresa ya está en el ecosistema Azure y necesita integración nativa con Microsoft 365, Teams y Entra ID, Azure Entra sigue siendo la mejor opción. Keycloak brilla cuando necesitas control total, costo previsible (cero) e independencia del vendor.

Principales Funcionalidades

Keycloak incluye funcionalidades que los proveedores cloud cobran por separado:

  • Single Sign-On (SSO) — login único entre múltiples aplicaciones
  • Identity Brokering — federación con proveedores externos (Google, GitHub, Facebook, Azure AD, SAML)
  • User Federation — integración con LDAP y Active Directory
  • Fine-grained Authorization — políticas de autorización basadas en roles, groups, scopes y resources
  • Multi-Factor Authentication (MFA) — TOTP, WebAuthn/FIDO2, SMS, email
  • Account Management Console — portal self-service para que el usuario gestione su perfil, sesiones y 2FA
  • Admin Console — panel web completo para gestionar realms, clients, users y roles
  • Event Logging y Audit Trail — registro detallado de eventos de autenticación
  • API REST para Administración — automatización completa vía API
  • Extensibilidad vía SPI — Service Provider Interfaces para personalizaciones avanzadas

Requisitos Previos

Keycloak en Contenedor: Setup Completo

Docker Compose para Desarrollo

La forma más rápida y recomendada de ejecutar Keycloak localmente es en un contenedor. Uso docker-compose con PostgreSQL como base de datos (la misma que usarías en producción):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
# docker-compose.keycloak.yml
services:
  keycloak-postgres:
    image: postgres:16-alpine
    container_name: keycloak-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: keycloak-dev-123
      TZ: America/Sao_Paulo
    volumes:
      - keycloak-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    container_name: keycloak
    restart: unless-stopped
    environment:
      # Admin inicial
      KC_BOOTSTRAP_ADMIN_USERNAME: admin
      KC_BOOTSTRAP_ADMIN_PASSWORD: admin
      # Base de datos
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak-postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: keycloak-dev-123
      # Configuración
      KC_HOSTNAME: localhost
      KC_HTTP_ENABLED: "true"
      KC_HOSTNAME_STRICT: "false"
      KC_PROXY_HEADERS: xforwarded
      TZ: America/Sao_Paulo
    ports:
      - "8443:8443"
      - "8180:8080"
    command: start-dev
    depends_on:
      keycloak-postgres:
        condition: service_healthy

volumes:
  keycloak-pgdata:

⚠️ Atención: El comando start-dev habilita el modo de desarrollo con HTTP, caché local y hot-reload de temas. Nunca uses start-dev en producción — usa start con HTTPS configurado y las variables de producción adecuadas.

Inicia el stack:

1
docker compose -f docker-compose.keycloak.yml up -d

Tras unos segundos, accede al panel admin en http://localhost:8180 con las credenciales admin / admin.

Configuración Inicial: Realm y Client

Keycloak organiza todo en Realms — cada realm es un espacio aislado con sus propios usuarios, clients, roles y configuraciones. El realm master está reservado para la administración del servidor. Creo un realm para la aplicación:

1. Crear un Realm

  1. En el panel admin, haz clic en el desplegable master en la esquina superior izquierda
  2. Haz clic en Create Realm
  3. Completa: Realm name = meu-app
  4. Haz clic en Create

2. Crear un Client (para la API ASP.NET Core)

  1. En el realm meu-app, ve a Clients → Create client
  2. Completa:
    • Client type: OpenID Connect
    • Client ID: minha-api
  3. En la siguiente pantalla:
    • Client authentication: ON (confidential client)
    • Authorization: ON (si quieres usar authorization services)
  4. En Valid Redirect URIs: https://localhost:5001/* y http://localhost:5000/*
  5. En Web Origins: + (permite todos los origins de los redirect URIs)
  6. Haz clic en Save

3. Obtener el Client Secret

  1. Después de guardar, ve a la pestaña Credentials
  2. Copia el Client secret — lo necesitarás en la configuración de la API

4. Crear un Usuario de Prueba

  1. Ve a Users → Add user
  2. Completa:
    • Username: usuario.teste
    • Email: [email protected]
    • First Name: Usuário
    • Last Name: Teste
    • Email verified: ON
  3. Haz clic en Create
  4. Ve a la pestaña Credentials → Set password
  5. Define una contraseña y desmarca Temporary

5. Crear Roles

  1. Ve a Realm roles → Create role
  2. Crea los roles: admin, user, manager
  3. Asigna roles al usuario: Users → selecciona el usuario → pestaña Role mapping → Assign role

ℹ️ Información: Todo lo que hice manualmente arriba puede automatizarse vía Keycloak Admin REST API o importando un realm en JSON — ideal para pipelines de CI/CD.

Visión General del Flujo de Autenticación

Antes de entrar en el código, mira cómo encajan las piezas. El diagrama siguiente muestra el flujo completo: el Browser se autentica vía OpenID Connect en Keycloak, recibe un JWT y lo envía como Bearer Token a la API ASP.NET Core, que valida el token consultando las claves públicas (JWKS) de Keycloak:

Diagrama del flujo de autenticación entre Browser, Keycloak y API ASP.NET Core en contenedores Docker con PostgreSQL

Integración con C# y ASP.NET Core

Los siguientes ejemplos usan C# con ASP.NET Core, pero el mismo flujo se aplica a cualquier lenguaje/framework. Keycloak se comunica mediante protocolos estándar (OIDC/OAuth2), así que la integración se reduce a configurar la validación de JWT Bearer en tu stack — algo que todas las plataformas modernas soportan de forma nativa o mediante una biblioteca:

Lenguaje / FrameworkBiblioteca / Recurso de Integración
C# / ASP.NET CoreMicrosoft.AspNetCore.Authentication.JwtBearer (usado en este artículo)
Java / Spring BootSpring Security OAuth2 Resource Server — spring-boot-starter-oauth2-resource-server
Python / Djangodjango-allauth o mozilla-django-oidc
Python / FastAPIpython-jose + validación manual de JWT o fastapi-keycloak
Node.js / Expresskeycloak-connect (adaptador oficial) o jsonwebtoken + JWKS
Node.js / NestJSnest-keycloak-connect
Gogo-oidc (CoreOS)
PHP / Laravelsocialiteproviders/keycloak o robsontenorio/laravel-keycloak-guard
Ruby on Railsomniauth-keycloak
Angular / React / Vuekeycloak-js (adaptador oficial para SPAs)

ℹ️ Información: Keycloak también ofrece adaptadores oficiales para varias plataformas. Sin embargo, para nuevas integraciones se recomienda usar bibliotecas genéricas de OIDC/JWT de tu lenguaje — así no quedas acoplado a un adaptador específico de Keycloak.

Configuración de la API

Creo una API REST protegida por Keycloak usando ASP.NET Core 8 con autenticación OpenID Connect / JWT Bearer:

1
2
3
dotnet new webapi -n MinhaApi.Keycloak -f net8.0
cd MinhaApi.Keycloak
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer

Configura el appsettings.json con los datos de Keycloak:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "Keycloak": {
    "Authority": "http://localhost:8180/realms/meu-app",
    "Audience": "minha-api",
    "ClientId": "minha-api",
    "ClientSecret": "SEU_CLIENT_SECRET_AQUI",
    "RequireHttpsMetadata": false
  },
  "Logging": {
    "LogLevel": {
      "Default": "Information"
    }
  }
}

⚠️ Atención: En producción, RequireHttpsMetadata debe ser true y el ClientSecret debe venir de variables de entorno o de Azure Key Vault, nunca hardcoded en el appsettings.json.

Program.cs — Configuración Completa

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
using System.Security.Claims;
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;

var builder = WebApplication.CreateBuilder(args);

// Carga la configuración de Keycloak
var keycloakConfig = builder.Configuration.GetSection("Keycloak");

builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
    options.Authority = keycloakConfig["Authority"];
    options.Audience = keycloakConfig["Audience"];
    options.RequireHttpsMetadata = bool.Parse(
        keycloakConfig["RequireHttpsMetadata"] ?? "true"
    );

    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidIssuer = keycloakConfig["Authority"],
        ValidateAudience = true,
        ValidAudience = keycloakConfig["Audience"],
        ValidateLifetime = true,
        // Mapea los roles de Keycloak a claims de .NET
        RoleClaimType = ClaimTypes.Role,
        NameClaimType = "preferred_username"
    };

    // Extrae los realm roles del token JWT de Keycloak
    options.Events = new JwtBearerEvents
    {
        OnTokenValidated = context =>
        {
            MapKeycloakRolesToClaims(context);
            return Task.CompletedTask;
        }
    };
});

builder.Services.AddAuthorization(options =>
{
    // Políticas basadas en roles de Keycloak
    options.AddPolicy("AdminOnly", policy =>
        policy.RequireRole("admin"));

    options.AddPolicy("UserOrAdmin", policy =>
        policy.RequireRole("user", "admin"));

    options.AddPolicy("ManagerOnly", policy =>
        policy.RequireRole("manager"));
});

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseAuthentication();
app.UseAuthorization();
app.MapControllers();
app.Run();

// Extrae realm_access.roles del token JWT de Keycloak
// y los agrega como claims de Role en el ClaimsPrincipal
static void MapKeycloakRolesToClaims(TokenValidatedContext context)
{
    if (context.Principal?.Identity is not ClaimsIdentity identity)
        return;

    // Keycloak almacena los roles en realm_access.roles en el token JWT
    var realmAccess = context.Principal.FindFirst("realm_access");
    if (realmAccess is null)
        return;

    using var doc = System.Text.Json.JsonDocument.Parse(realmAccess.Value);

    if (!doc.RootElement.TryGetProperty("roles", out var roles))
        return;

    foreach (var role in roles.EnumerateArray())
    {
        var roleName = role.GetString();
        if (!string.IsNullOrEmpty(roleName))
        {
            identity.AddClaim(new Claim(ClaimTypes.Role, roleName));
        }
    }
}

💡 Consejo: Keycloak almacena los roles del realm dentro de un claim llamado realm_access en el JWT. El código anterior extrae esos roles y los mapea a ClaimTypes.Role de .NET, lo que permite usar [Authorize(Roles = "admin")] con normalidad. Sin ese mapeo, User.IsInRole("admin") no funciona.

Controller Protegido

Crea un controller que demuestre los distintos niveles de acceso:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;
using System.Security.Claims;

namespace MinhaApi.Keycloak.Controllers;

[ApiController]
[Route("api/[controller]")]
public class ProtegidoController : ControllerBase
{
    // Ruta pública — sin autenticación
    [HttpGet("publico")]
    [AllowAnonymous]
    public IActionResult RotaPublica()
    {
        return Ok(new { mensagem = "Esta ruta es pública y no requiere autenticación." });
    }

    // Ruta protegida — cualquier usuario autenticado
    [HttpGet("autenticado")]
    [Authorize]
    public IActionResult RotaAutenticada()
    {
        var username = User.FindFirst("preferred_username")?.Value;
        var email = User.FindFirst("email")?.Value;
        var roles = User.FindAll(ClaimTypes.Role).Select(c => c.Value);

        return Ok(new
        {
            mensagem = "¡Estás autenticado vía Keycloak!",
            usuario = username,
            email,
            roles
        });
    }

    // Ruta restringida a admins
    [HttpGet("admin")]
    [Authorize(Policy = "AdminOnly")]
    public IActionResult RotaAdmin()
    {
        return Ok(new
        {
            mensagem = "Acceso administrativo concedido.",
            usuario = User.FindFirst("preferred_username")?.Value
        });
    }

    // Ruta restringida a managers
    [HttpGet("manager")]
    [Authorize(Policy = "ManagerOnly")]
    public IActionResult RotaManager()
    {
        return Ok(new
        {
            mensagem = "Acceso de manager concedido.",
            usuario = User.FindFirst("preferred_username")?.Value
        });
    }

    // Devuelve todas las claims del token JWT
    [HttpGet("claims")]
    [Authorize]
    public IActionResult VerClaims()
    {
        var claims = User.Claims.Select(c => new
        {
            tipo = c.Type,
            valor = c.Value
        });

        return Ok(claims);
    }
}

Obteniendo un Token para Pruebas

Para probar la API, necesitas obtener un token de Keycloak. Usa el flujo Resource Owner Password (solo para pruebas/desarrollo):

1
2
3
4
5
6
7
8
curl -X POST "http://localhost:8180/realms/meu-app/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=minha-api" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "grant_type=password" \
  -d "username=usuario.teste" \
  -d "password=sua-senha" \
  -d "scope=openid"

La respuesta contendrá el access_token. Úsalo para llamar a la API:

1
2
curl -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  http://localhost:5000/api/protegido/autenticado

Salida esperada:

1
2
3
4
5
6
{
  "mensagem": "¡Estás autenticado vía Keycloak!",
  "usuario": "usuario.teste",
  "email": "[email protected]",
  "roles": ["user"]
}

Service para Comunicarse con la Admin API

Para escenarios en los que tu aplicación necesita gestionar usuarios, roles o sesiones de forma programática, Keycloak expone una Admin REST API completa. Así se crea un servicio para consumir esa API:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

namespace MinhaApi.Keycloak.Services;

public sealed class KeycloakAdminService
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _realm;
    private readonly string _clientId;
    private readonly string _clientSecret;

    public KeycloakAdminService(
        HttpClient httpClient,
        IConfiguration configuration)
    {
        _httpClient = httpClient;
        _baseUrl = configuration["Keycloak:Authority"]!
            .Replace($"/realms/{configuration["Keycloak:Realm"]}", "");
        _realm = configuration["Keycloak:Realm"] ?? "meu-app";
        _clientId = configuration["Keycloak:ClientId"]!;
        _clientSecret = configuration["Keycloak:ClientSecret"]!;
    }

    // Obtiene un token de servicio (client credentials) para acceder a la Admin API
    private async Task<string> GetAdminTokenAsync(
        CancellationToken cancellationToken = default)
    {
        var content = new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["grant_type"] = "client_credentials",
            ["client_id"] = _clientId,
            ["client_secret"] = _clientSecret
        });

        var response = await _httpClient.PostAsync(
            $"{_baseUrl}/realms/{_realm}/protocol/openid-connect/token",
            content,
            cancellationToken);

        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync(cancellationToken);
        using var doc = JsonDocument.Parse(json);
        return doc.RootElement.GetProperty("access_token").GetString()!;
    }

    // Lista todos los usuarios del realm
    public async Task<JsonElement> ListarUsuariosAsync(
        int first = 0,
        int max = 100,
        CancellationToken cancellationToken = default)
    {
        var token = await GetAdminTokenAsync(cancellationToken);

        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", token);

        var response = await _httpClient.GetAsync(
            $"{_baseUrl}/admin/realms/{_realm}/users?first={first}&max={max}",
            cancellationToken);

        response.EnsureSuccessStatusCode();

        var json = await response.Content.ReadAsStringAsync(cancellationToken);
        return JsonDocument.Parse(json).RootElement;
    }

    // Crea un nuevo usuario en Keycloak
    public async Task<bool> CriarUsuarioAsync(
        string username,
        string email,
        string firstName,
        string lastName,
        string senha,
        CancellationToken cancellationToken = default)
    {
        var token = await GetAdminTokenAsync(cancellationToken);

        _httpClient.DefaultRequestHeaders.Authorization =
            new AuthenticationHeaderValue("Bearer", token);

        var novoUsuario = new
        {
            username,
            email,
            firstName,
            lastName,
            enabled = true,
            emailVerified = true,
            credentials = new[]
            {
                new
                {
                    type = "password",
                    value = senha,
                    temporary = false
                }
            }
        };

        var content = new StringContent(
            JsonSerializer.Serialize(novoUsuario),
            Encoding.UTF8,
            "application/json");

        var response = await _httpClient.PostAsync(
            $"{_baseUrl}/admin/realms/{_realm}/users",
            content,
            cancellationToken);

        return response.IsSuccessStatusCode;
    }
}

Regístralo en el Program.cs:

1
builder.Services.AddHttpClient<KeycloakAdminService>();

ℹ️ Información: Para que el client minha-api pueda acceder a la Admin API, es necesario habilitar la Service Account del client en Keycloak y asignar el rol realm-management → realm-admin a la service account.

Implementando el Logout

El logout en una integración con Keycloak va más allá de simplemente descartar el token del lado del cliente. Para que la sesión quede completamente cerrada, hay que notificar a Keycloak para que también invalide la sesión en el servidor de identidad — esto se llama RP-Initiated Logout (especificación OpenID Connect).

Keycloak expone el endpoint de logout en:

1
{KEYCLOAK_URL}/realms/{REALM}/protocol/openid-connect/logout

Logout vía API (Back-Channel)

Para invalidar la sesión del usuario directamente desde tu API, usa el refresh_token o el id_token_hint:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

namespace MinhaApi.Keycloak.Controllers;

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly IConfiguration _configuration;
    private readonly IHttpClientFactory _httpClientFactory;

    public AuthController(
        IConfiguration configuration,
        IHttpClientFactory httpClientFactory)
    {
        _configuration = configuration;
        _httpClientFactory = httpClientFactory;
    }

    /// <summary>
    /// Realiza el logout en Keycloak invalidando la sesión vía back-channel.
    /// El client envía el refresh_token para que Keycloak cierre la sesión.
    /// </summary>
    [HttpPost("logout")]
    [Authorize]
    public async Task<IActionResult> Logout(
        [FromBody] LogoutRequest request,
        CancellationToken cancellationToken = default)
    {
        var authority = _configuration["Keycloak:Authority"];
        var clientId = _configuration["Keycloak:ClientId"];
        var clientSecret = _configuration["Keycloak:ClientSecret"];

        var httpClient = _httpClientFactory.CreateClient();

        // Llama al endpoint de logout de Keycloak
        var content = new FormUrlEncodedContent(new Dictionary<string, string>
        {
            ["client_id"] = clientId!,
            ["client_secret"] = clientSecret!,
            ["refresh_token"] = request.RefreshToken
        });

        var response = await httpClient.PostAsync(
            $"{authority}/protocol/openid-connect/logout",
            content,
            cancellationToken);

        if (!response.IsSuccessStatusCode)
        {
            var error = await response.Content.ReadAsStringAsync(cancellationToken);
            return BadRequest(new
            {
                mensagem = "Error al realizar el logout en Keycloak.",
                detalhes = error
            });
        }

        return Ok(new { mensagem = "Logout realizado con éxito." });
    }

    /// <summary>
    /// Genera la URL de logout de Keycloak para redirección (Front-Channel).
    /// Se usa cuando el client necesita redirigir al usuario a la pantalla de logout de Keycloak.
    /// </summary>
    [HttpGet("logout-url")]
    [Authorize]
    public IActionResult GetLogoutUrl(
        [FromQuery] string? redirectUri = null)
    {
        var authority = _configuration["Keycloak:Authority"];
        var clientId = _configuration["Keycloak:ClientId"];

        var logoutUrl = $"{authority}/protocol/openid-connect/logout" +
                        $"?client_id={clientId}";

        if (!string.IsNullOrEmpty(redirectUri))
        {
            logoutUrl += $"&post_logout_redirect_uri={Uri.EscapeDataString(redirectUri)}";
        }

        return Ok(new { logoutUrl });
    }
}

public record LogoutRequest(string RefreshToken);

Registra el IHttpClientFactory en el Program.cs (si aún no está registrado):

1
builder.Services.AddHttpClient();

Probando el Logout

1. Obtén un token (incluido el refresh_token):

1
2
3
4
5
6
7
8
curl -X POST "http://localhost:8180/realms/meu-app/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id=minha-api" \
  -d "client_secret=SEU_CLIENT_SECRET" \
  -d "grant_type=password" \
  -d "username=usuario.teste" \
  -d "password=sua-senha" \
  -d "scope=openid offline_access"

💡 Consejo: El scope offline_access garantiza que Keycloak devuelva un refresh_token en la respuesta. Sin él, según la configuración del client, puede que el refresh token no se emita.

2. Realiza el logout vía API:

1
2
3
4
curl -X POST "http://localhost:5000/api/auth/logout" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "SEU_REFRESH_TOKEN"}'

3. U obtén la URL de logout para redirección (front-channel):

1
2
curl -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  "http://localhost:5000/api/auth/logout-url?redirectUri=http://localhost:3000"

Logout en el Front-End (SPA)

En aplicaciones front-end (Angular, React, Vue), el logout normalmente se hace mediante redirección al endpoint de Keycloak:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
// Ejemplo genérico para cualquier framework JavaScript
function logout() {
    const keycloakUrl = "http://localhost:8180";
    const realm = "meu-app";
    const clientId = "minha-api";
    const redirectUri = encodeURIComponent(window.location.origin);

    // Limpia los tokens locales
    localStorage.removeItem("access_token");
    localStorage.removeItem("refresh_token");

    // Redirige al logout de Keycloak
    window.location.href =
        `${keycloakUrl}/realms/${realm}/protocol/openid-connect/logout` +
        `?client_id=${clientId}` +
        `&post_logout_redirect_uri=${redirectUri}`;
}

Si usas el adaptador oficial keycloak-js, el logout es aún más simple:

1
2
3
4
5
6
7
8
9
// Con keycloak-js
const keycloak = new Keycloak({
    url: "http://localhost:8180",
    realm: "meu-app",
    clientId: "minha-api"
});

// Logout con redirección
keycloak.logout({ redirectUri: window.location.origin });

⚠️ Atención: Para que post_logout_redirect_uri funcione, la URL de redirección debe estar registrada en las Valid Post Logout Redirect URIs del client en Keycloak. En desarrollo, agrega http://localhost:*. En producción, usa solo las URLs exactas de tu dominio.

Personalización de la Pantalla de Login

Una de las grandes ventajas de Keycloak frente a los proveedores cloud es la libertad total para personalizar la pantalla de login. Puedes cambiar el logo, los colores, las fuentes y los textos, e incluso crear temas completamente desde cero usando plantillas FreeMarker.

Estructura de un Tema de Keycloak

Keycloak usa un sistema de temas basado en FreeMarker Templates. Cada tema puede sobrescribir parcialmente el tema por defecto (keycloak o keycloak.v2):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
themes/
└── meu-tema/
    └── login/
        ├── theme.properties          # Configuración del tema
        ├── resources/
        │   ├── css/
        │   │   └── login.css         # Estilos personalizados
        │   └── img/
        │       ├── logo.svg          # Logo personalizado
        │       └── favicon.ico       # Favicon
        └── messages/
            └── messages_pt_BR.properties  # Textos en PT-BR

Creando el Tema Personalizado

1. Archivo theme.properties

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
# Hereda del tema por defecto de Keycloak y sobrescribe solo lo necesario
parent=keycloak.v2
import=common/keycloak

# Estilos personalizados
styles=css/login.css

# Sobrescribe el logo
logo=img/logo.svg
logoUrl=https://minha-empresa.com.br

2. CSS Personalizado (resources/css/login.css)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
/* ===== Colores y Branding ===== */
:root {
    --pf-v5-global--primary-color--100: #1a73e8;    /* Azul primario */
    --pf-v5-global--primary-color--200: #1557b0;    /* Azul hover */
    --pf-v5-global--BackgroundColor--100: #f8f9fa;   /* Fondo de la página */
}

/* ===== Logo personalizado ===== */
.pf-v5-c-login__header .pf-v5-c-brand {
    max-height: 80px;
    width: auto;
}

/* ===== Card de login ===== */
.pf-v5-c-login__main {
    background-color: #ffffff;
    border-radius: 12px;
    box-shadow: 0 4px 24px rgba(0, 0, 0, 0.12);
    max-width: 440px;
}

/* ===== Botón de login ===== */
.pf-v5-c-button.pf-m-primary {
    background-color: var(--pf-v5-global--primary-color--100);
    border-radius: 8px;
    font-weight: 600;
    padding: 12px 24px;
    transition: background-color 0.2s ease;
}

.pf-v5-c-button.pf-m-primary:hover {
    background-color: var(--pf-v5-global--primary-color--200);
}

/* ===== Campos de input ===== */
.pf-v5-c-form-control {
    border-radius: 8px;
    border: 1px solid #dadce0;
    padding: 12px 16px;
}

.pf-v5-c-form-control:focus {
    border-color: var(--pf-v5-global--primary-color--100);
    box-shadow: 0 0 0 2px rgba(26, 115, 232, 0.2);
}

/* ===== Footer personalizado ===== */
.pf-v5-c-login__footer {
    text-align: center;
    font-size: 0.85rem;
    color: #5f6368;
}

/* ===== Background con degradado ===== */
.pf-v5-c-login {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
    min-height: 100vh;
}

3. Mensajes en Portugués (messages/messages_pt_BR.properties)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# Sobrescribe los textos por defecto para PT-BR
loginTitle=Bem-vindo de volta
loginTitleHtml=Bem-vindo de volta
doLogIn=Entrar
doRegister=Criar conta
noAccount=Não tem uma conta?
usernameOrEmail=E-mail ou nome de usuário
password=Senha
rememberMe=Lembrar de mim
forgotPassword=Esqueceu a senha?
backToLogin=Voltar ao login

Montando el Tema en el Contenedor

Agrega el volumen del tema en el docker-compose.keycloak.yml:

1
2
3
4
5
6
7
8
  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    # ... demás configuraciones ...
    volumes:
      - ./themes/meu-tema:/opt/keycloak/themes/meu-tema:ro
    environment:
      # ... demás variables ...
      KC_SPI_THEME_DEFAULT: meu-tema

Como alternativa, activa el tema desde el panel admin:

  1. Ve a Realm Settings → pestaña Themes
  2. En Login theme, selecciona meu-tema
  3. Haz clic en Save

💡 Consejo: En el modo start-dev, Keycloak hace hot-reload de los temas automáticamente. Basta con guardar el archivo CSS o la plantilla FreeMarker y recargar la página de login para ver los cambios al instante — sin reiniciar el contenedor.

Resultado Visual

Después de aplicar el tema, la pantalla de login tendrá:

  • ✅ El logo de tu empresa en la parte superior
  • ✅ Colores personalizados en botones y campos
  • ✅ Textos en portugués de Brasil
  • ✅ Card de login con bordes redondeados y sombra suave
  • ✅ Background con degradado personalizado
  • ✅ Favicon personalizado

📝 Ejemplo: Empresas como Red Hat, Siemens y Deutsche Telekom usan Keycloak con temas totalmente personalizados que no se distinguen de soluciones SaaS propietarias. El usuario final nunca percibe que está usando un identity provider open-source.

Keycloak en Producción con Contenedores

Docker Compose para Producción

En producción, las diferencias respecto al setup de desarrollo son:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
# docker-compose.keycloak.prod.yml
services:
  keycloak-postgres:
    image: postgres:16-alpine
    container_name: keycloak-postgres
    restart: always
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
      TZ: America/Sao_Paulo
    volumes:
      - keycloak-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U keycloak -d keycloak"]
      interval: 10s
      timeout: 5s
      retries: 5

  keycloak:
    image: quay.io/keycloak/keycloak:26.0
    container_name: keycloak
    restart: always
    environment:
      # Admin — usar una contraseña segura generada con openssl rand
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KC_ADMIN_USER}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KC_ADMIN_PASSWORD}
      # Base de datos
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://keycloak-postgres:5432/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      # Producción — HTTPS obligatorio
      KC_HOSTNAME: auth.seudominio.com.br
      KC_PROXY_HEADERS: xforwarded
      KC_HTTP_ENABLED: "false"
      KC_HTTPS_CERTIFICATE_FILE: /opt/keycloak/certs/fullchain.pem
      KC_HTTPS_CERTIFICATE_KEY_FILE: /opt/keycloak/certs/privkey.pem
      # Performance
      KC_CACHE: ispn
      KC_HEALTH_ENABLED: "true"
      KC_METRICS_ENABLED: "true"
      TZ: America/Sao_Paulo
    ports:
      - "8443:8443"
    command: start --optimized
    volumes:
      - ./certs:/opt/keycloak/certs:ro
      - ./themes/meu-tema:/opt/keycloak/themes/meu-tema:ro
    depends_on:
      keycloak-postgres:
        condition: service_healthy

volumes:
  keycloak-pgdata:

⚠️ Atención: En producción, considera usar build en lugar de volúmenes para el tema. La imagen oficial soporta multi-stage build con kc.sh build para optimizar el arranque:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
FROM quay.io/keycloak/keycloak:26.0 AS builder

# Copia el tema personalizado
COPY themes/meu-tema /opt/keycloak/themes/meu-tema

# Build optimizado con la configuración de producción
ENV KC_DB=postgres
ENV KC_CACHE=ispn
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true

RUN /opt/keycloak/bin/kc.sh build

FROM quay.io/keycloak/keycloak:26.0

COPY --from=builder /opt/keycloak/ /opt/keycloak/

ENTRYPOINT ["/opt/keycloak/bin/kc.sh"]

Consejos de Producción — Seguridad y Rendimiento

Proxy reverso con Nginx:

Si Keycloak está detrás de un Nginx (como en la arquitectura descrita en el patrón BFF), configura el location para proxy reverso:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
server {
    listen 443 ssl http2;
    server_name auth.seudominio.com.br;

    ssl_certificate     /etc/nginx/ssl/fullchain.pem;
    ssl_certificate_key /etc/nginx/ssl/privkey.pem;

    location / {
        proxy_pass https://keycloak:8443;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
}

Consejos y Buenas Prácticas

  • Separa el realm de producción del de administración — nunca uses el realm master para tus usuarios. Crea realms específicos por aplicación o dominio de negocio.

  • Exporta y versiona la configuración del realm — usa el endpoint de exportación de Keycloak (/admin/realms/{realm}/export) para guardar la configuración como JSON y versionarla en Git. Así puedes recrear todo el entorno a partir del código (Infrastructure as Code).

  • Habilita rate limiting en el proxy reverso — Keycloak gestiona la autenticación, blanco frecuente de ataques de fuerza bruta. Configura limit_req en Nginx para restringir las solicitudes al endpoint de login.

  • Configura correctamente la caché de Infinispan — en producción con múltiples instancias (cluster), Keycloak usa Infinispan como caché distribuida de sesiones. Consulta la documentación oficial de caching para escenarios de alta disponibilidad.

  • Monitorea con health checks y métricas — habilita KC_HEALTH_ENABLED y KC_METRICS_ENABLED para exponer los endpoints /health y /metrics (compatibles con Prometheus).

  • Usa start --optimized en producción — el comando start con el flag --optimized precompila la configuración y reduce drásticamente el tiempo de arranque (de ~30s a ~5s).

  • Actualiza con regularidad — Keycloak recibe actualizaciones de seguridad frecuentes. Sigue el blog oficial y prueba las nuevas versiones en staging antes de actualizar producción.

  • Haz backup de la base de datos con regularidad — el PostgreSQL de Keycloak contiene todos los datos de identidad. Un pg_dump programado es obligatorio en cualquier entorno de producción.

Comparativa: Cuándo Usar Keycloak vs Cloud

EscenarioRecomendación
Startup con presupuesto limitado✅ Keycloak — costo cero, todas las features
Empresa ya en el ecosistema Microsoft 365⚡ Azure Entra ID — integración nativa
Aplicación 100% AWS con Serverless⚡ AWS Cognito — integración con Lambda/API Gateway
Requisito de soberanía de datos (LGPD, GDPR)✅ Keycloak — los datos quedan en tu infra
Equipo sin experiencia en infra/contenedores⚡ Auth0 o Firebase Auth — SaaS gestionado
Escenario on-premises o air-gapped✅ Keycloak — única opción viable
Necesidad de personalización total de la UX✅ Keycloak — temas FreeMarker ilimitados
Alta escala (millones de MAU)🤔 Depende — Keycloak escala, pero exige experiencia en cluster

ℹ️ Información: Nada impide un uso híbrido. Muchas empresas usan Keycloak como identity broker federando con Azure AD/Google Workspace. Así, los empleados inician sesión con el SSO corporativo (Azure AD), pero los datos de sesión y autorización quedan centralizados en Keycloak.

Conclusión

Keycloak es una de las herramientas más subestimadas del ecosistema open-source. Entrega, gratis, funcionalidades por las que los proveedores cloud cobran cientos o miles de dólares al mes: SSO, MFA, identity brokering, user federation, personalización completa de la UI y una potente API REST para automatización. Ejecutarlo en contenedor con Docker o Podman es trivial, y la integración vía OpenID Connect es directa — en este artículo lo demostré con ASP.NET Core y C#, pero el mismo flujo funciona con Java, Python, Node.js, Go, PHP, Ruby y cualquier otra tecnología que soporte JWT y OIDC. Keycloak es un servidor de identidad agnóstico de lenguaje: la capa de autenticación corre en el contenedor y tu aplicación solo valida tokens estándar.

Si trabajas en un escenario donde el costo importa, donde la soberanía de los datos es un requisito, o simplemente quieres control total sobre la autenticación y la autorización de tu aplicación — sin importar el lenguaje o el framework —, Keycloak merece un lugar destacado en tu stack. Empieza en pequeño, en un entorno de desarrollo con Docker Compose, valida el flujo con tu aplicación, personaliza la pantalla de login con la identidad visual de tu marca y, cuando tengas confianza, llévalo a producción con HTTPS, proxy reverso y backups.

La autenticación es la puerta de entrada de tu sistema — y con Keycloak, esa puerta es gratuita, segura y completamente tuya.

Lee También

Referencias