TL;DR — Resumo Rápido

Guia completo do Keycloak: instalação com Docker, configuração de realms, clientes OpenID Connect e SAML, federação LDAP, RBAC e alta disponibilidade.

O Keycloak é a principal solução open-source de Gestão de Identidades e Acessos (IAM) — fornece Single Sign-On (SSO), MFA, login social, federação LDAP/Active Directory e autorização detalhada usando OpenID Connect, OAuth 2.0 e SAML 2.0. Este guia abrange desde a instalação com Docker Compose até configuração de realms, RBAC, federação de identidades e clustering de alta disponibilidade.

Pré-requisitos

  • Docker 25+ e Docker Compose v2 (ou cluster Kubernetes para instalação com operator).
  • PostgreSQL 15+ para produção (H2 integrado é apenas para desenvolvimento).
  • Proxy reverso (Nginx ou Traefik) para terminação TLS em produção.
  • Familiaridade básica com conceitos de OAuth 2.0.

Arquitetura do Keycloak

O Keycloak organiza tudo em realms — domínios de segurança isolados:

Conceito Descrição
Realm Tenant isolado. Contém usuários, clientes, roles e grupos
Cliente Aplicação registrada para usar o Keycloak
Usuário Identidade dentro do realm (local ou federada)
Role Rótulo de permissão. Roles de realm ou roles de cliente
Grupo Coleção de usuários com roles herdados
Provedor de Identidade IdP externo (Google, GitHub, SAML, LDAP)
Fluxo de Autenticação Pipeline configurável: login, OTP, WebAuthn

O realm master é o super-admin — use-o apenas para gerenciar outros realms, nunca para usuários de aplicações.

Passo 1: Instalar Keycloak com Docker Compose

version: "3.9"
services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: keycloak
      POSTGRES_PASSWORD: changeme
    volumes:
      - postgres_data:/var/lib/postgresql/data

  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    command: start
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres/keycloak
      KC_DB_USERNAME: keycloak
      KC_DB_PASSWORD: changeme
      KC_HOSTNAME: auth.exemplo.com
      KC_PROXY: edge
      KEYCLOAK_ADMIN: admin
      KEYCLOAK_ADMIN_PASSWORD: adminpass
    ports:
      - "8080:8080"
    depends_on:
      - postgres

volumes:
  postgres_data:
docker compose up -d
# Acesse o Console de Administração em http://localhost:8080

Para Kubernetes, use o Keycloak Operator oficial.

Passo 2: Configuração do Realm

Configuração Valor recomendado
Nome de exibição Nome da sua marca
Tema de login keycloak ou personalizado
Exigir SSL external requests (produção)
Tempo ocioso da sessão SSO 30 minutos
Duração do token de acesso 5 minutos

Configure SMTP em Configurações do Realm → Email para e-mails de redefinição de senha.

Passo 3: Configuração de Clientes OpenID Connect

Clientes → Criar cliente:

  • Tipo de cliente: OpenID Connect
  • Client ID: myapp-client
  • Autenticação de cliente: Ativada (confidencial) para apps server-side; Desativada (público) para SPAs
  • URIs de redirecionamento válidas: https://myapp.exemplo.com/callback
  • Web origins: https://myapp.exemplo.com

Clientes Confidenciais vs Públicos

Característica Confidencial Público
Tem segredo Sim Não
Caso de uso Servidor (Node, .NET, Python) SPA, app móvel
Fluxo de código auth Com segredo Com PKCE

Passo 4: Controle de Acesso Baseado em Roles (RBAC)

# Criar role de realm com kcadm.sh
kcadm.sh config credentials \
  --server http://localhost:8080 \
  --realm master \
  --user admin --password adminpass

kcadm.sh create roles -r myapp -s name=app-admin
kcadm.sh create roles -r myapp -s name=app-user

Fluxo recomendado: Roles → Grupos → Usuários. Atribua roles a grupos e adicione usuários aos grupos.

Os roles compostos agrupam outros roles: crie superusuario e adicione app-admin e app-user como compostos.

Passo 5: Federação de Identidades

Login Social (Google, GitHub, Microsoft)

Provedores de Identidade → Adicionar provedor → Google:

  1. Crie um app OAuth 2.0 no Google Cloud Console.
  2. Informe Client ID e Client Secret do Google no Keycloak.
  3. URI de redirecionamento: https://auth.exemplo.com/realms/myapp/broker/google/endpoint.

Federação LDAP / Active Directory

Configuração Valor
Fornecedor Active Directory
URL de conexão ldap://ad.corp.exemplo.com
Bind DN CN=svc-keycloak,OU=ContasServico,DC=corp,DC=exemplo,DC=com
DN de usuários OU=Usuarios,DC=corp,DC=exemplo,DC=com
Modo de sincronização FORCE

Execute Sincronizar todos os usuários para importar usuários do AD.

Passo 6: Fluxos de Autenticação e MFA

TOTP e WebAuthn

Para TOTP: Autenticação → Fluxos → browser → Duplicar → Adicionar Formulário OTP como OBRIGATÓRIO.

Para WebAuthn/Passkeys (Keycloak 22+):

  1. Autenticação → Políticas → Política WebAuthn — configure o domínio como Relying Party ID.
  2. Adicione Autenticador WebAuthn ao fluxo do navegador.

Alta Disponibilidade

environment:
  KC_CACHE: ispn
  KC_CACHE_STACK: jdbc-ping
  KC_DB: postgres
  KC_DB_URL: jdbc:postgresql://pgpool/keycloak
  • Habilite sessões sticky no balanceador (cookie AUTH_SESSION_ID).
  • Endpoint de saúde: GET /health/ready.

Keycloak vs Alternativas

Característica Keycloak Authentik Authelia Auth0 Okta FusionAuth
Código aberto Sim Sim Sim Não Não Parcial
Auto-hospedado Sim Sim Sim Não Não Sim
SAML 2.0 Sim Sim Não Sim Sim Sim
Federação LDAP Sim Sim Não Sim Sim Sim
Autorização detalhada Sim (UMA) Não Não Sim (pago) Sim (pago) Parcial
Complexidade Alta Média Baixa Baixa Baixa Média

Solução de Problemas

Problema Solução
“Invalid redirect_uri” Verifique URIs de redirecionamento válidas — correspondência exata
“Client secret not valid” Regenere o segredo em Clientes → Credenciais
Loop de login Verifique se KC_HOSTNAME corresponde à URL real
E-mail não enviado Revise SMTP em Configurações do Realm → Email
Usuários LDAP não sincronizados Verifique credenciais de bind e execute sincronização manual

Resumo

  • Os realms isolam tenants — use sempre um realm dedicado para aplicações.
  • Os clientes confidenciais usam segredos; os públicos usam PKCE.
  • Os grupos com roles escalam o RBAC — evite atribuir roles diretamente a usuários.
  • A sincronização LDAP com modo FORCE mantém o AD como fonte autoritativa.
  • Use KC_CACHE=ispn com jdbc-ping para HA sem dependências adicionais.

Artigos Relacionados