O Keycloak é uma plataforma open source capaz de gerenciar os acessos dos usuários que utilizam as aplicações configuradas a ela. Esse procedimento é feito através do esquema de autenticação SSO e garante diversos benefícios, entre eles:

• Após logar na aplicação A, o usuário pode acessar a aplicação B sem efetuar um novo login enquanto o token ainda estiver ativo.
• Passa a responsabilidade do gerenciamento de acessos das suas aplicações para uma plataforma robusta e confiável.
• Possui integração com o Active Directory.
• Possui integração com diversas redes sociais para permitir o Login social.
• Facilidade para configurar autenticação em dois fatores.

Pré-requisitos

Antes de começar a seguir os passos do tutorial é preciso ter certeza de que se tem um ambiente minimamente preparado para reproduzir o exemplo. Abaixo estão os requisitos principais.

1. Esse tutorial utiliza a versão 13.0.1 do Keycloak e não aborda a instalação e configuração do servidor. Acesse a documentação oficial para realizar esse procedimento. É importante ressaltar que, por ser uma plataforma open source, o Keycloak passa por atualizações frequentes. Portanto, alguns recursos mencionados neste tutorial podem apresentar diferenças na versão atual, por isso consulte a documentação oficial para mais informações.
2. Usaremos um usuário local criado no próprio Keycloak como exemplo. Acesse a documentação oficial para saber como importar os usuários de um Active Directory ou configurar o acesso por Login social.

Passos no Keycloak

Para os próximos passos será necessário possuir um usuário Administrador do seu servidor do Keycloak para criar realms, clientes e usuários. Por isso, acesse a área Administration Console e faça o login com o usuário administrador.

Figura 1 - Página de bem-vindo do servidor do Keycloak

Realms

Um realm gerencia um conjunto de usuários, credenciais, regras (roles) e grupos (groups). Um usuário pertence e efetua login em um domínio (realm). Os realms são isolados uns dos outros e só podem gerenciar e autenticar os usuários que controlam. Caso não possua regras que o limite, um usuário credenciado em um realms poderá logar em todas as aplicações (clients) associadas.

Após logar na aplicação do Keycloak será possível visualizar a lista de realms já criada. Passe o cursor do mouse sobre a palavra Select realm e clique no botão Add realm (destaque 1 da figura 2).

Figura 2 - Acesso a lista de realms

Na tela seguinte, informe o nome para seu realm e clique em Create (Figura 2.1).

Figura 2.1 - Criando o realm

Após a criar o realm, você será direcionado para a aba Realm Settings do menu lateral e poderá ajustar diversos recursos do novo realm. Neste tutorial usaremos a configuração padrão, porém, para mais detalhes sobre as configurações do realm, acesse a documentação oficial.

Figura 2.2 - Área de configuração do realm selecionado

Clients

Os clientes são entidades que podem solicitar que o Keycloak autentique seus usuários. Na maioria das vezes os clientes são aplicações ou serviços que desejam usar o Keycloak para se proteger e fornecer uma solução de logon único. Os clientes também podem apenas obter informações de identidade ou token de acesso para que possam invocar, com segurança, outros serviços em redes protegidas pelo Keycloak. Assim, cada aplicação criada no Cronapp deve ser configurada como um client diferente no keycloak.

Acesse a aba Clients no menu lateral (destaque 1 da figura 3) para exibir a lista dos clientes existentes (alguns são padrões do Keycloak) e clique em Create (2). 

Figura 3 - Acesso a aba Clients

A próxima tela exibirá alguns campos para obter as informações mais básicas do novo client. Preencha como na figura 3.1 e clique em Save.

Figura 3.1 - Informações iniciais para a criação do Client

1. Client ID: informe um identificador para a aplicação a ser cadastrada.
2. Client Protocol: selecione a opção openid-connect.
3. Root URL: informe https://ide.cronapp.io

Em seguida o Keycloak exibirá a subaba Settings do client, fazermos mais algumas configurações. 

Figura 3.2 - Subaba Settings das configurações do Client

• Name: informe o nome da aplicação que representa o client.
• Login Theme: selecione o tema Keycloak. É possível personalizar o tema da tela de login, acesse a documentação oficial para mais detalhes.
• Access Type: selecione a opção confidential.
• Valid Redirect URIs: informe apenas "*" (asterisco), a aplicação Cronapp informará automaticamente ao Keycloak qual a página que o usuário deve ser direcionado após o login de sucesso.

Clique em Save.

Acesse a subaba Credentials (destaque 1 da figura 3.3) e copie o conteúdo do campo Secret, usaremos esse dado logo mais nas configurações da aplicação no Cronapp.

Figura 3.3 - Campos da subaba Credentials

Users

Usuários são entidades que podem fazer login em aplicações (clients) vinculadas ao Keycloak. Podem ter atributos (e-mail, nome de usuário, endereço, etc) associados e ser atribuídos como membros do grupo e possuir funções específicas. Um usuário possui vínculo com um realm, e não aos clients, dessa forma, após logar em uma aplicação, e não existir restrições, esse usuário poderá acessar todas as aplicações vinculadas ao realm. 

A base de usuários utilizada pelo Keycloak pode vir do cadastro local, como faremos nesse tutorial, ou obtida através de recursos como AD / LDAP (User Federation) ou Login Social (Identity Providers).

Novo usuário e duplo fator de autenticação (OTP)

Vamos cadastrar o usuário que iremos usar para logar em nossa aplicação Cronapp. Acesse a aba Users do menu lateral (destaque 1 da figura 4) e clique em Add user (2).

Figura 4 - Lista de usuários do realm

Na próxima tela são exibidos os campos de cadastro do usuário, apenas o Username é obrigatório, porém destacamos alguns.

Figura 4.1 - Cadastro do usuário

• User Enabled: marque ON.
• Email Verified: quando ativada, essa opção fará com que o atributo de verificação de e-mail seja configurado como true. Pularemos essa etapa neste tutorial, por isso, marque ON.
• Required User Adctions: esse campo permite selecionar algumas ações que serão solicitadas ao usuário. Precisaremos marcar apenas as opções abaixo:
  • Update Password: essa opção exigirá que o usuário crie uma nova senha no primeiro login;
  • Configure OTP: ao selecionar essa opção, o Keycloak exibirá um QRCode ou um código hash para que o usuário utilize um aplicativo de autenticação.

Finalizada as configurações iniciais do usuário, clique em Save. 

Precisamos agora informar uma senha para o usuário recém-criado. Por isso, acesse a subaba Credentials (destaque 1 da figura 4.2) e preencha os campos como na imagem abaixo.

Figura 4.2 - Configuração da senha do usuário

• Password: informe uma senha para esse usuário. 
• Password Confirmation: confirme a senha desse usuário.
• Temporary: essa opção força o usuário a trocar de senha após o primeiro login, para simplificar os passos desse tutorial, dessa essa opção desmarcada (OFF).

Clique em Set Password e depois em Reset password no pop-up de confirmação de alteração da senha.

Após essa etapa, finalizamos as configurações mais básicas para utilizar o keycloak, os próximos passos serão feitos no Cronapp.

Passos no Cronapp

Nos próximos passos iremos criar uma nova aplicação já com a opção de autenticação via SSO. Esse procedimento evitará que tenhamos que configurar a tela de login da aplicação.

Novo projeto

Após logar no Cronapp, inicie um novo projeto seguindo os passos da figura abaixo.

Figura 5 - Criando um projeto no Cronapp

1. Clique em Novo para abrir a janela Novo Projeto.
2. Selecione a opção Mobile e Web no campo LOW-CODE.
3. Informe um nome para a sua aplicação.
4. Selecione a opção Baseado em Modelo existente.

Clique em Finalizar.

Na próxima tela (sem figura) selecione o modelo Mobile Low-Code Project e Avance novamente para tela de configurações do projeto e autenticação (Figura 5.1).

No campo Tipo de Autenticação, selecione a opção SSO (destaque 1 da figura 5.1) e Avance.

Figura 5.1 - Selecionando a autenticação via SSO

Na última tela, selecione um dos Temas e Finalize. Para este tutorial usaremos o tema Material.

Configurações da autenticação SSO

Para o próximo passo, acesse as configurações do projeto em Menu do sistema > Projeto > Configurações e, na janela que abrir, selecione a aba Configurações do Projeto (destaque 1 da figura 6) e por fim, na subaba Autenticação e Segurança (destaque 2).

Figura 6 - Configuração de autenticação do SSO

Nas Configurações da Autenticação (destaque 3), preencha os campos abaixo.

• ID do Cliente: informe o client id que configuração na criação do Client.
• Segredo do Cliente: informe o client secret que obtivemos após a criação do client.
• URI do Token de Acesso: informe a URI do token de acesso adaptado conforme quadro acima.
• URI de Autorização do Usuário: informe a URI de autorização do usuário adaptado conforme quadro acima.
• URI de Informações do Usuário: informe a URI de informações do usuário adaptado conforme quadro acima.

Salve a janela de configuração.

Teste

Finalizado as configurações, vamos executar o projeto Cronapp que acabamos de criar e logar com o usuário criado no Keycloak.

Execute o projeto Cronapp (destaque 1 da figura 7) e, após finalizar o processo, clique em Navegador [web] na janela que abrir. Como o nosso projeto foi criado com o tipo de autenticação SSO, a tela de login só possui o botão Entrar (Figura 7).

Figura 7 - Execução e autenticação na aplicação Cronapp

Clique no botão Entrar na tela de login da aplicação (Figura 7) para ser direcionado a uma página que utiliza a autenticação do Keycloak (Figura 7.1). Perceba que o endereço da página é o mesmo que informamos no campo URI de Autorização do Usuário (destaque 1 da figura 7.1). 

Informe as credenciais que informamos no passo de criação do usuário e clique em Sign In (Figura 7.1):

• Username: js
• Password: mypassword

Figura 7.1 - Logando com o usuário criado no Keycloak

Como se trata do primeiro acesso e solicitamos a ação Update Password no campo Required User Actions (Figura 4.1), o Keycloak pedirá que o usuário altere a senha inicial. Informe uma nova senha nos campos New Password e Confirm Password e clique em Submit (Figura 7.2).

Figura 7.2 - Atualização da senha do usuário no primeiro login

Como se trata do primeiro acesso e solicitamos a ação Configure OTP no campo Required User Actions (Figura 4.1), o Keycloak pedirá que o usuário utilize um aplicativo de autenticação para fazer a leitura do QRCode e informar o código gerado. Utilize qualquer aplicativo de autenticação e informe o código gerado pelo aplicativo e também o nome do dispositivo utilizado nessa ação (Figura 7.3).

Clique em Submit após preencher os 2 campos.

Figura 7.3 - Efetuando a autenticação em 2 fatores

Após logar na página de autenticação do Keycloak, a mesma será fechada e o usuário retornará para a aplicação do Cronapp já logado (Figura 7.4).

Figura 7.4 - Usuário logado na aplicação do Cronapp

Sempre que o usuário for efetuar um novo login, será necessário informar seu usuário e senha e o novo código gerado pelo aplicativo de autenticação.