Guia para Configuração Local do Keycloak utilizando Docker

Este documento oferece um passo a passo sobre como executar uma instância do Keycloak em modo de desenvolvimento local usando Docker. Vamos configurar uma instância com um administrador padrão para facilitar o desenvolvimento.

Pré-requisitos

  • Docker instalado e configurado no seu ambiente local.
  • Conexão à internet para baixar a imagem do Keycloak.

Instruções

1. Executando o Keycloak no Docker

Para iniciar o Keycloak em modo de desenvolvimento local, execute o seguinte comando no terminal:

docker run --name mykeycloak -p 8080:8080 \
    -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
    -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \
    quay.io/keycloak/keycloak:latest \
    start-dev

Explicação dos parâmetros:

  • --name mykeycloak: Define o nome do container como "mykeycloak".
  • -p 8080:8080: Mapeia a porta 8080 do seu host para a porta 8080 no container, permitindo acesso via http://localhost:8080.
  • -e KC_BOOTSTRAP_ADMIN_USERNAME=admin: Define o nome de usuário do administrador como "admin".
  • -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me: Define a senha do administrador como "change_me".
  • quay.io/keycloak/keycloak:latest: Especifica a imagem do Keycloak mais recente disponível.
  • start-dev: Executa o Keycloak no modo de desenvolvimento, simplificando a configuração para uso local.

Nota: O modo de desenvolvimento do Keycloak desabilita algumas verificações de segurança, como HTTPS, o que é ideal para ambientes de desenvolvimento mas não deve ser utilizado em produção.

2. Acessando o Keycloak

Após a execução do comando, o Keycloak estará disponível em http://localhost:8080. Acesse esta URL no seu navegador e faça login com as credenciais de administrador que você configurou:

  • Usuário: admin
  • Senha: change_me

3. Configurações Básicas no Keycloak

  1. Criação de um Realm:

    • No painel do Keycloak, clique em "Add Realm" para criar um novo realm. O realm é o ambiente onde você pode configurar todos os recursos relacionados aos seus aplicativos.

  2. Configuração de Clientes:

    • Dentro do seu realm, vá até a seção "Clients" e clique em "Create" para adicionar um cliente. Este cliente representará sua aplicação e permitirá que ela se autentique com o Keycloak.

  3. Configuração de Usuários:

    • Na seção "Users", você pode adicionar novos usuários ao realm. Estes serão os usuários que poderão se autenticar na sua aplicação utilizando o Keycloak.

4. Encerrando o Container

Para parar e remover o container do Keycloak após o uso, execute os seguintes comandos:

docker stop mykeycloak
docker rm mykeycloak

Dicas Adicionais

  • Persistência de Dados: No modo padrão, os dados são apagados quando o container é removido. Para persistir os dados entre reinicializações, você pode adicionar um volume ao container.

bash docker run --name mykeycloak -p 8080:8080 \ -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \ -e KC_BOOTSTRAP_ADMIN_PASSWORD=change_me \ -v keycloak_data:/opt/keycloak/data \ quay.io/keycloak/keycloak:latest \ start-dev

  • Configurações Adicionais: Para ambientes de desenvolvimento mais complexos, consulte a documentação oficial do Keycloak para conhecer outras variáveis de ambiente e modos de execução disponíveis.

Referências