Keycloak Self-Hosted Tutorial: Autenticação Centralizada

O que é Keycloak e por que adotá-lo?

No cenário atual de desenvolvimento de software, a segurança não é um acessório, mas uma necessidade fundamental. Para equipes de TI e desenvolvedores que buscam controle total sobre os dados dos usuários, o Keycloak self-hosted tutorial se torna uma ferramenta indispensável. O Keycloak é um Identity and Access Management (IAM) open source, projetado para proteger aplicações modernas e serviços tradicionais contra ameaças cibernéticas.

A principal vantagem de implementar uma solução de autenticação centralizada on-premise ou em nuvem privada é a eliminação da dependência de provedores externos. Ao usar o Keycloak como um Identity Provider (IdP) open source, você mantém a soberania dos dados, garantindo que informações sensíveis de login não saiam do seu ambiente controlado. Além disso, ele oferece suporte nativo aos protocolos modernos OIDC (OpenID Connect) e SAML 2.0, permitindo Single Sign-On (SSO) para diversas aplicações simultaneamente.

Neste guia prático, demonstraremos como provisionar um servidor Keycloak robusto utilizando VPS Linux e orquestrado via Docker Compose. Essa abordagem garante portabilidade, facilidade de manutenção e escalabilidade, seguindo as melhores práticas de infraestrutura moderna.

Pré-requisitos do Ambiente

Antes de iniciar a instalação, é essencial garantir que o ambiente esteja preparado corretamente. A configuração abaixo utiliza uma máquina virtual Linux (Ubuntu 22.04 LTS ou Debian 11 são recomendados) com acesso root ou privilégios de sudo.

Um VPS Linux com mínimo de 2 vCPUs e 4GB de RAM.
Sistema operacional Linux recente (Kernel 5.x ou superior).
Docker Engine instalado e configurado para rodar sem necessidade de sudo.
Docker Compose plugin ou versão standalone instalada.
Um domínio apontando para o IP do seu servidor (ex: sso.suaempresa.com) com registros DNS A configurados. Isso é crucial para a geração correta dos tokens JWT e certificados TLS.

Caso ainda não tenha o Docker instalado, utilize os comandos padrão da sua distribuição. Para sistemas baseados em Debian/Ubuntu:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

Lembre-se de reconectar à sessão SSH após adicionar seu usuário ao grupo docker.

Estrutura do Projeto Docker Compose

A gestão de identidade via Docker Compose Keycloak simplifica drasticamente o ciclo de vida da aplicação. Em vez de gerenciar pacotes .deb ou .rpm e dependências do Java manualmente, encapsulamos toda a infraestrutura em arquivos de configuração versionáveis.

Crie um diretório dedicado para o projeto:

mkdir -p ~/keycloak-self-hosted
cd ~/keycloak-self-hosted

Dentro deste diretório, criaremos dois arquivos principais: docker-compose.yml, que define os serviços, e .env, que armazena variáveis de ambiente sensíveis. Esta separação é uma prática crítica de segurança.

Configurando Variáveis de Ambiente Seguras

Crie o arquivo .env na raiz do projeto. Este arquivo conterá as credenciais de administrador e configurações de banco de dados. Nunca commitar este arquivo no seu repositório Git público.

# Configurações do Admin
KC_ADMIN_USERNAME=admin
KC_ADMIN_PASSWORD=SuaSenhaForte123!@#

# Configurações do Banco de Dados (PostgreSQL)
DB_VENDOR=POSTGRES
DB_ADDR=postgresql
DB_DATABASE=keycloak
DB_USER=keycloak
DB_PASSWORD=SuaSenhaBanco456!@#

# Configurações de Host e HTTPS
KC_HOSTNAME=sso.suaempresa.com
KC_HTTP_ENABLED=false
KC_PROXY_HEADERS=xforwarded

Explicação das variáveis:

KC_ADMIN_USERNAME e KC_ADMIN_PASSWORD: Credenciais para acessar o painel administrativo do Keycloak.
DB_VENDOR: Define o banco de dados como PostgreSQL, que é o mais recomendado para produção devido à sua estabilidade ACID.
KC_PROXY_HEADERS=xforwarded: Essencial quando o Keycloak está atrás de um reverso de proxy (como Nginx ou Traefik). Isso permite que o Keycloak entenda se a conexão original foi HTTPS ou HTTP e construa URLs corretas nos redirects.

O Arquivo Docker Compose

Agora, crie o arquivo docker-compose.yml. Esta configuração define dois serviços: o próprio Keycloak e o banco de dados PostgreSQL. Utilizamos volumes nominais para persistência de dados, garantindo que as configurações e usuários não sejam perdidos em caso de reinicialização dos containers.

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:24.0
    restart: always
    environment:
      - DB_VENDOR=${DB_VENDOR}
      - DB_ADDR=${DB_ADDR}
      - DB_DATABASE=${DB_DATABASE}
      - DB_USER=${DB_USER}
      - DB_PASSWORD=${DB_PASSWORD}
      - KC_DB_SCHEMA=public
      - KC_HOSTNAME=${KC_HOSTNAME}
      - KC_HTTP_ENABLED=${KC_HTTP_ENABLED}
      - KC_PROXY_HEADERS=${KC_PROXY_HEADERS}
      - KC_ADMIN_USERNAME=${KC_ADMIN_USERNAME}
      - KC_ADMIN_PASSWORD=${KC_ADMIN_PASSWORD}
      - KC_HEALTH_ENABLED=true
    command: start-prod
    ports:
      - "8443:8443"
    volumes:
      - keycloak-data:/opt/keycloak/data
    depends_on:
      - postgresql

  postgresql:
    image: postgres:16-alpine
    restart: always
    environment:
      - POSTGRES_DB=${DB_DATABASE}
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  keycloak-data:
  pgdata:

Pontos de atenção nesta configuração:

Imagem Oficial: Utilizamos a imagem oficial do Quay.io, que é mantida pela equipe do Keycloak.
Comando Start-Prod: A flag start-prod otimiza o servidor para uso em produção, desativando logs excessivos e habilitando recursos de performance.
Porta 8443: Em ambientes com HTTPS, a porta interna do Keycloak é 8443. Se você estiver testando localmente sem TLS, pode usar a porta 8080 e alterar KC_HTTP_ENABLED=true.

Iniciando a Infraestrutura

Com os arquivos criados, o próximo passo é baixar as imagens e iniciar os containers. Execute o comando abaixo no terminal:

docker compose up -d

O Docker Compose baixará a imagem do Keycloak e do PostgreSQL, criará as redes necessárias e iniciará os serviços. Você pode monitorar os logs para garantir que a inicialização ocorreu sem erros:

docker compose logs -f keycloak

Aguarde até ver a mensagem "Keycloak started successfully". Isso indica que o banco de dados foi inicializado e as tabelas foram criadas.

Configuração Inicial via Console Web

Após a instalação, o Keycloak está rodando, mas precisa ser configurado para seu contexto específico. Abra um navegador web e acesse https://sso.suaempresa.com:8443. Como estamos usando um certificado auto-assinado ou sem CA pública no tutorial inicial, você verá um aviso de segurança do navegador; prossiga com "Avançado" > "Prosseguir".

O primeiro passo é criar o Realm. Um Realm no Keycloak é um tenant isolado que contém usuários, clientes e configurações. Por padrão, existe um realm chamado master, mas ele é destinado apenas à administração do servidor. Para suas aplicações, crie um novo realm:

No canto superior esquerdo, clique em Create Realm.
Digite o nome do seu domínio ou projeto (ex: minha-empresa) e clique em Create.

Agora, dentro do novo realm, você deve configurar os clientes (Clients). Um Client representa uma aplicação que deseja se autenticar contra o Keycloak. Isso pode ser um aplicativo web, mobile ou API.

Criando um Cliente para SSO On-Premise

Vamos configurar um cliente genérico para demonstrar a integração. Acesse o menu lateral Clients e clique em Create Client.

Client Type: Selecione OpenID Connect.
Client ID: Defina um identificador único, por exemplo, meu-app-web.

Navegue até a aba Credentials. Você verá o Client Secret. Anote este valor, pois ele será necessário para configurar sua aplicação. Este segredo garante que apenas aplicações autorizadas possam solicitar tokens ao Keycloak.

Vá até a aba Capability config e certifique-se de que Standard flow está habilitado. Para aplicações modernas (SPAs, React, Vue), também habilite o PKCE.

Integração com Aplicações Existentes

Com o Keycloak rodando e configurado, a próxima etapa é integrar suas aplicações existentes para usar esta autenticação centralizada. O processo varia dependendo da stack tecnológica, mas o princípio é sempre o mesmo: redirecionar o usuário para o endpoint de login do Keycloak.

Para uma aplicação web tradicional (Node.js/Express, por exemplo), você utilizaria middleware como passport-keycloak-oauth2-oidc. A configuração básica envolve apontar para os endpoints Discovery do seu servidor:

const keycloakConfig = {
  authServerUrl: 'https://sso.suaempresa.com:8443/realms/minha-empresa',
  realm: 'minha-empresa',
  clientId: 'meu-app-web',
  clientSecret: 'COLE-O-SEGREDO-AQUI',
  callbackURL: 'https://meuapp.com/callback'
};

Para APIs RESTful, o fluxo típico é exigir que o cliente envie um token JWT válido no header Authorization: Bearer <token>. Sua API deve validar este token contra a chave pública (public key) fornecida pelo Keycloak, garantindo que ele não foi adulterado e ainda está válido.

Habilitando HTTPS com Nginx (Recomendado)

A configuração acima expõe a porta 8443 diretamente. Em produção, é altamente recomendável usar um reverso de proxy como o Nginx para gerenciar certificados TLS Let's Encrypt e rotear o tráfego.

No seu servidor Linux, instale o Nginx e configure um bloco de servidor:

server {
    listen 443 ssl;
    server_name sso.suaempresa.com;

    ssl_certificate /etc/letsencrypt/live/sso.suaempresa.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sso.suaempresa.com/privkey.pem;

    location / {
        proxy_pass http://localhost: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;
    }
}

Com essa configuração, o Keycloak receberá as requisições como se viessem de HTTPS diretamente, permitindo que os tokens gerados contenham URLs corretas e seguras.

Melhores Práticas de Segurança e Manutenção

A gestão de identidade exige rigor. Ao implementar um idp open source como o Keycloak, adote as seguintes práticas:

Backup Regular: Configure backups automáticos do volume pgdata e do diretório de dados do Keycloak. A perda de dados de usuários pode ser catastrófica.
Rotação de Senhas: Força políticas de complexidade de senha através das "Client Policies" ou "User Federation" no painel administrativo.
Monitoramento: Ative o health check exposto na porta 9000 (se configurado) e integre com ferramentas como Prometheus para monitorar a latência de autenticação.
Atualizações: Mantenha a imagem do Docker atualizada. O Keycloak lança correções de segurança frequentemente. Utilize tags específicas de versão (ex: 24.0) em vez de latest em ambientes de produção para evitar mudanças bruscas.

Conclusão

Este tutorial demonstrou como implementar uma solução robusta de gestão de identidade utilizando Keycloak self-hosted. Ao combinar a flexibilidade do Docker Compose com a segurança de um banco de dados dedicado e um proxy reverso, você estabelece uma base sólida para Single Sign-On on-premise.

A autonomia proporcionada por esta arquitetura permite que sua equipe controle o ciclo de vida da autenticação, integre múltiplos sistemas heterogêneos e cumpra requisitos rigorosos de conformidade de dados. Com a infraestrutura pronta, o próximo passo é integrar suas aplicações principais e começar a consolidar seus acessos em um único ponto seguro.

Tags: #keycloak self-hosted tutorial #instalar keycloak docker compose #sso on-premise linux #idp open source #gestão de identidade #autenticação centralizada #keycloak postgresql #sso ubuntu