O que é Keycloak e como começar a usar

Já parou pra pensar quantas vezes desenvolve funcionalidades iguais pra sistemas diferentes? No dia a dia, é preciso desenvolver muita coisa parecida. Por exemplo: provavelmente, a feature mais replicada em toda a história da computação é a de autenticação e autorização.

Pense em quantas vezes você já criou uma classe user, com atributos name, username, email, password… Certamente, foram algumas.  Foi pra tentar tornar esse processo menos chato para você que surgiu o Keycloak!

Nesse artigo, você entende melhor o que é Keycloak, como utilizá-lo e quais os pontos fortes e fracos da funcionalidade. Boa leitura!

O que é Keycloak?

Patrocinado pela Red Hat, o Keycloak é um software open source de um servidor JBoss feito para trabalhar em conjunto com sua aplicação em implementações mais comuns de autenticação e de autorização.

Caso as configurações padrão não te atendam, existem várias configurações e customizações que podem ser feitas para adequar o funcionamento ao seu sistema.

O que O Keycloak oferece?

São oferecidas, pelo Keycloak, funcionalidades como:

• Criação de usuário (podendo ser criados pelo administrador do sistema e habilitado ou não para o próprio usuário se cadastrar)
• Login, “esqueci minha senha” e login com plataformas externas como redes sociais
• Integração dos usuários com Active Directory
• Ativação de usuários por confirmação de e-mail
• Necessidade de aceitação de termos de uso antes de logar
• Customização das páginas que o usuário acessa (como a própria tela de login)
• Serviços para que outras aplicações busquem dados de usuários
• Criação de permissões que o sistema vai usar
• Criação de grupos de usuário
• i18n (internationalization)
• Entre outras várias configurações e customizações mais avançadas!

Como usar Keycloak?

O primeiro passo pra usar o Keycloak é baixar e rodar a versão mais recente na sua máquina. Você pode baixar direto no site oficial. Se você é um amante de conteinerização como eu, vai saber o que fazer com esse link do Docker.

Se você baixou pelo site, agora vai precisar iniciar o servidor. Para isso existe um script na pasta /bin chamado standalone.bat (para Windows) ou standalone.sh (para Linux e afins). Feito isso, o Keycloak vai gravar os dados em um banco de dados H2. Vale lembrar que, para ambientes de produção, o recomendado é subir via contêiner e especificar outro banco nas variáveis de ambiente, conforme mostrado anteriormente.

Aguarde alguns instantes, enquanto a aplicação se inicializa, e abra seu localhost na porta 8080, no próprio navegador (http://localhost:8080). Agora, vamos acessar a parte do Administration Console. Se você inicializou pelo docker, o login e senha serão os que está definidos nas variáveis de ambiente KEYCLOAK_USER e KEYCLOAK_PASSWORD.

Se você inicializou pelos scripts de standalone, vai precisar definir usuário e senha do usuário administrador. Com o user criado, clique em Administration Console e logue com seu usuário.  Assim, uma tela parecida com esta aparecerá:

Primeiros conceitos para o Keycloak

Antes de ligarmos nossa aplicação no Keycloak, precisamos entender alguns conceitos para não fazermos bobagem.

Realms

Observe que, próximo ao canto superior esquerdo, está escrito “Master”. Ali é mostrado o realm atual em que você está. Para fins didáticos, você pode entender realm como um balde de usuários.

Normalmente usamos o realm Master para os administradores do sistema, já que seu usuário de administrador está criado nele. É extremamente recomendado que, para começar as configurações para sua aplicação, você crie, antes, um outro realm, para os usuários que vão acessar o sistema.

A ideia por trás disso é não permitir que os administradores usem o(s) sistema(s) que o Keycloak protege, e muito menos que usuários normais tenham acesso a configurações de administrador. Para criar esse novo realm, coloque o mouse sobre o Master e clique em “Add realm”.

Realm Settings

Agora que o realm  foi criado para os usuários do sistema que deve ser protegido, é possível visualizar uma tela com várias abas, em que é possível alterar várias configurações do realm.

As abas principais que você precisa conhecer são General (define pontos como o nome do realm que será mostrado na tela de login), Login (define campos que serão mostrados na tela de login e algumas regras) e Email (define as configurações do e-mail que será utilizado para fazer validações, como verificação de e-mail, quando habilitado).

Clients

Seguindo pela ordem dos menus, nos clients vamos cadastrar as aplicações que queremos proteger com o Keycloak. Lembre-se de não remover as aplicações que já estão cadastradas por padrão.

Roles

São as permissões que você terá dentro do sistema. Elas podem ser atribuídas a usuários ou a grupos de usuários. Dentro das aplicações, dá para usar os nomes cadastrados para liberar acesso (ou retirar o acesso) de um determinado recurso para o usuário logado.

Existem dois tipos de roles: as normais e as composite roles. As normais servem para te apoiar a fazer de fato o controle de acesso a recursos, enquanto as composite roles são feitas para agregar outras roles, facilitando a liberação delas em lote.

Também existe uma outra aba nessa tela, chamada “Default Roles”. Nessa aba são cadastradas as roles que os usuários terão por padrão, assim que forem criadas.

Identity Providers

Aqui, é possível configurar login usando outras plataformas, tais como redes sociais ou até mesmo outro Keycloak. É necessária alguma configuração nessas outras plataformas para que o login funcione bem.

User Federation

Serve para permitir o uso de bases de dados externas na hora de fazer login. Você pode configurar login com um Active Directory.

Groups

São os grupos de usuário. Você não precisa necessariamente criar grupos de usuário, mas eles podem ser úteis para separar os diferentes perfis que vão acessar suas aplicações.

Por exemplo, você pode criar um grupo para os gerentes e outro grupo para os operacionais, atribuindo as roles necessárias para ambos. Assim, quando criar um usuário, basta adicioná-lo ao grupo, e ele terá todos os acessos do grupo.

Users

Aqui ficam todos os usuários criados no seu realm. Enquanto administrador, você pode cadastrar novos usuários, editá-los e até removê-los. Existe uma funcionalidade excepcional nesta seção, chamada “Impersonate”.

Ao clicar nesse botão, você vai estar logado com aquele usuário. Isso vai te ajudar muito quando vir um chamado do suporte dizendo haver um problema com um usuário específico, e você precisa logar nele, mas não quer pedir a senha (apenas cuidado: você estará logado na conta de outra pessoa. Com grandes poderes vêm grandes responsabilidades).

Com essa introdução aos principais menus do painel de administração do Keycloak, é hora de começar a proteger a aplicação.

A primeira coisa que você deve fazer é se certificar que está no realm criado recentemente e só então crie um client para a aplicação que quer proteger. Durante esse processo, somente um campo Client ID é obrigatório, em que você escreverá algo que remete à sua aplicação (por exemplo, frontend-app).

Se está rodando sua aplicação ainda em localhost, recomendo informar a URL para a raiz da sua aplicação no campo Root URL (no caso, http://localhost:3000), pois, dessa forma, os campos Valid Redirect URIs e Web Origins serão preenchidos automaticamente.

Esses dois campos servem, respectivamente, para definir para quais páginas o Keycloak está autorizado a fazer redirecionamentos (usamos o wildcard para dar match em qualquer coisa), e definir quais endereços estão autorizados a obter recursos do Keycloak. No fim das contas, ambos são medidas de segurança para que somente páginas autorizadas consumam os serviços.

Agora que você criou o client, pode acessar a aba “Installation” e fazer download de um arquivo que usará para informar à aplicação os dados de conexão. Normalmente, usamos o formato “Keycloak OIDC JSON” (para Javascript e NodeJS, esse é o formato recomendado).

A partir desse ponto, o que precisaremos fazer dependerá da linguagem do sistema que queremos proteger, então recomendo a leitura da documentação do Keycloak. Essa documentação pode ir mudando conforme o Keycloak é atualizado, mas hoje existem mais de nove guides, que ensinam como fazer as coisas.

Para proteger sua aplicação, acesse o guide “Securing Applications and Services”. Logo no início existe a seção “Supported Platforms”, que mostra quais são as plataformas que já possuem adaptadores do Keycloak para serem usados. Clique em qual mais se encaixa na sua aplicação, e daí pra frente é só começar a seguir o que o guide ensina.

Uma dica de ouro: caso esteja protegendo uma aplicação Javascript (frontend), quando subir o Keycloak, ele mesmo já disponibiliza um adaptador Javascript, no path /auth/js/keycloak.js.

Suponha que seu Keycloak está rodando em localhost na porta 8080, o adaptador estará em http://localhost:8080/auth/js/keycloak.js. É interessante importar esse arquivo na sua aplicação, em vez de baixar o Keycloak-js como dependência, pois, dessa forma, não teremos problemas com versão. Se alterarmos a versão do Keycloak, a versão do adaptador é alterada junto dessa forma.

Prós e contras do Keycloak

Por fim, vale entender quais são as vantagens e as desvantagens em utilizar o Keycloak na hora do desenvolvimento.

Pontos fortes:

• Gratuito
• Conteinerizado
• Mantido pela comunidade, portanto, confiável
• Flexível
• Customizável
• Atualizado constantemente
• Compatível com diversas tecnologias
• Documentação extensa
• Poupa tempo de recriar a roda desenvolvendo autenticação e autorização

Pontos fracos:

• Documentação original toda em inglês
• Customização de temas usam FTL (Freemarker Template) para customizações mais pesadas
• Apesar do tempo poupado no desenvolvimento, você vai passar umas boas horas lendo documentação, especialmente quando precisar de customizações maiores