ULC Lab · implementação reproduzível

Laboratório: Implantação do Keycloak com autenticação SAML integrada a um sistema web livre

Você terá um ambiente funcional com Keycloak rodando em uma VM Linux, atuando como Provedor de Identidade SAML para um sistema web (SimpleSAMLphp) em outra VM. O laboratório leva cerca de 120 minutos.

Ligado ao treinamento Gestão de Identidades com Keycloak do zero à governança

ULC-LAB-GOVE-0003 · Status de validaçãoNão validado pela Upnetix: roteiro derivado da documentação oficial, para você executar e validar

Duração estimada: 120 min
Passos: 12
Validações: 5
Versões da documentação consultada: Keycloak 22.0.5 · SimpleSAMLphp 2.1.2 · OpenJDK 17 · Apache HTTP Server 2.4.x · PHP 8.1

Objetivo

Demonstrar, na prática, como implantar o Keycloak como Provedor de Identidade (IdP) SAML e integrá-lo a um Serviço Web compatível (SP), simulando um cenário comum em ambientes públicos e governamentais. O exercício cobre instalação, configuração, federação, autenticação e validações de segurança, usando apenas software livre.

Topologia

Duas máquinas virtuais em rede privada: uma executando Keycloak (IdP) em 192.168.56.10, outra rodando SimpleSAMLphp (SP) em 192.168.56.20. O usuário acessa o serviço web, é redirecionado ao Keycloak para autenticação SAML e retorna autenticado ao SP.

         +---------------------+
         |  Usuário (browser) |
         +---------+----------+
                   |
                   v
+------------------+------------------+
|      SimpleSAMLphp (SP)             |
|      192.168.56.20                  |
+------------------+------------------+
                   |
                   v
+------------------+------------------+
|      Keycloak (IdP)                  |
|      192.168.56.10                   |
+--------------------------------------+

Equipamentos e software

Item	Requisito, licença ou versão
VM Keycloak	1 vCPU, 2GB RAM, 1 porta de rede, Ubuntu Server 22.04 LTS
VM SimpleSAMLphp	1 vCPU, 1GB RAM, 1 porta de rede, Ubuntu Server 22.04 LTS
Keycloak	Apache 2.0 · 22.0.5
SimpleSAMLphp	LGPL v2.1 · 2.1.2
OpenJDK	GPL v2 com Classpath Exception · 17
Apache HTTP Server	Apache 2.0 · 2.4.x
PHP	PHP License · 8.1

Roteiro

Preparar as VMs e a rede
Crie duas VMs Ubuntu Server 22.04 LTS, configure IPs estáticos 192.168.56.10 (Keycloak) e 192.168.56.20 (SimpleSAMLphp) na mesma rede privada.
```
sudo nano /etc/netplan/01-netcfg.yaml
```
O que você deve ver: Ambas as VMs respondem a ping entre si.

Instalar o Java e Keycloak

Keycloak exige Java. Instale o OpenJDK 17 e baixe o Keycloak.

sudo apt update && sudo apt install openjdk-17-jdk unzip wget -y
wget https://github.com/keycloak/keycloak/releases/download/22.0.5/keycloak-22.0.5.zip
unzip keycloak-22.0.5.zip
cd keycloak-22.0.5/bin

O que você deve ver: Diretório bin do Keycloak disponível.

Configurar e iniciar o Keycloak
Inicialize o Keycloak em modo standalone e crie o usuário admin.
```
./kc.sh start-dev --http-port=8080 &
./kc.sh create admin --user admin --password admin123
```
O que você deve ver: Keycloak acessível em http://192.168.56.10:8080
Acessar o painel de administração do Keycloak
Acesse o Keycloak via browser para garantir que está operacional.
O que você deve ver: Tela de login do Keycloak e painel após autenticação.
Criar um Realm dedicado
Realms isolam contextos de autenticação. Crie um novo Realm chamado 'govlab'.
O que você deve ver: Realm 'govlab' listado no painel.
Adicionar um usuário de teste
Em 'govlab', crie um usuário chamado 'usuario1' com senha definida.
O que você deve ver: Usuário 'usuario1' criado e habilitado.
Configurar o Provedor de Identidade SAML no Keycloak
No Realm 'govlab', crie um novo cliente SAML chamado 'simplesamlphp-sp' com o ACS (Assertion Consumer Service) apontando para http://192.168.56.20/simplesaml/module.php/saml/sp/saml2-acs.php/default-sp.
O que você deve ver: Cliente SAML 'simplesamlphp-sp' criado e ativo.
Exportar os metadados SAML do Keycloak
Baixe o arquivo de metadados SAML do cliente Keycloak para importar no SimpleSAMLphp.
```
Acesse: http://192.168.56.10:8080/realms/govlab/protocol/saml/descriptor
```
O que você deve ver: Arquivo XML de metadados baixado.

Instalar Apache, PHP e SimpleSAMLphp

No SP, instale Apache, PHP e SimpleSAMLphp.

sudo apt update && sudo apt install apache2 php php-xml php-mbstring unzip wget -y
wget https://github.com/simplesamlphp/simplesamlphp/releases/download/v2.1.2/simplesamlphp-2.1.2.tar.gz
tar xzf simplesamlphp-2.1.2.tar.gz
sudo mv simplesamlphp-2.1.2 /var/www/html/simplesaml

O que você deve ver: Diretório /var/www/html/simplesaml criado.

Configurar SimpleSAMLphp como SP
Edite config.php e authsources.php para definir o SP. Importe os metadados do Keycloak como IdP.
```
sudo nano /var/www/html/simplesaml/config/authsources.php
sudo nano /var/www/html/simplesaml/metadata/saml20-idp-remote.php
```
O que você deve ver: SimpleSAMLphp reconhece o Keycloak como IdP.
Importar metadados do SP no Keycloak
Exporte os metadados do SimpleSAMLphp (SP) e importe no Keycloak.
```
Acesse: http://192.168.56.20/simplesaml/module.php/saml/sp/metadata.php/default-sp
```
O que você deve ver: Keycloak reconhece o SP e aceita requisições SAML.
Testar autenticação SAML ponta a ponta
Acesse o SP via browser, inicie login SAML, autentique-se no Keycloak e retorne autenticado ao SimpleSAMLphp.
```
Acesse: http://192.168.56.20/simplesaml/module.php/core/authenticate.php?as=default-sp
```
O que você deve ver: Usuário autenticado com sucesso e atributos SAML exibidos.

Como saber que funcionou

Teste	Comando	Critério
Acesso ao painel do Keycloak	`curl -I http://192.168.56.10:8080`	HTTP 200 OK
Usuário consegue autenticar via SAML		Após login, SimpleSAMLphp exibe atributos do usuário autenticado
Metadados SAML exportados/importados corretamente		Sem erros de parsing nos logs do SimpleSAMLphp ou Keycloak
Comunicação entre SP e IdP	`ping 192.168.56.10`	Respostas de ping
Logout SAML		Logout no SP encerra sessão no IdP

Troubleshooting

Sintoma	Causa provável	Correção
Erro 404 ao acessar SimpleSAMLphp	Diretório ou permissões incorretas	Verifique se /var/www/html/simplesaml existe e tem permissão de leitura
Falha de autenticação SAML	Metadados inconsistentes entre SP e IdP	Reimporte os metadados e reinicie ambos os serviços
Keycloak não inicia	Java não instalado ou versão incorreta	Confirme se o OpenJDK 17 está instalado
Atributos do usuário não aparecem no SP	Mapeamento de atributos SAML ausente no Keycloak	Configure mapeamentos em 'Protocol Mappers' do cliente SAML
Timeout ao acessar Keycloak	Firewall bloqueando porta 8080	Libere a porta 8080 no firewall da VM

Segurança e hardening

Altere as senhas padrão imediatamente após o laboratório
Habilite HTTPS nos dois serviços antes de produção
Restrinja o acesso às portas administrativas
Revise os mapeamentos de atributos para evitar vazamento de dados sensíveis
Desabilite o modo 'start-dev' do Keycloak em ambientes reais

Checklist final

Keycloak acessível via browser
Usuário criado no Realm 'govlab'
SimpleSAMLphp acessível via browser
Metadados SAML trocados entre SP e IdP
Autenticação SAML funcionando ponta a ponta

Verificação editorial

Publicado: 09/09/2026
Última revisão: 09/09/2026
Versão do conteúdo: 1.0
Referências: 0 oficiais
Revisão técnica: redação e revisão por IA, URLs conferidas na publicação
Status: Atual

Encontrou um erro? Escreva para comercial@upnetix.com.br com o endereço da página. A revisão semestral por IA nunca altera comandos ou configurações sem passar pela fila de revisão.