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:8080Para 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-userFluxo 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:
- Crie um app OAuth 2.0 no Google Cloud Console.
- Informe Client ID e Client Secret do Google no Keycloak.
- 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+):
- Autenticação → Políticas → Política WebAuthn — configure o domínio como
Relying Party ID. - 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=ispncomjdbc-pingpara HA sem dependências adicionais.