4. Usando keycloak na dojot¶
A partir da versão v0.8.0, a dojot começou a utilizar o keycloak e removeu a utilização do antigo serviço auth. Keycloak é uma solução de gerenciamento de acesso e identidade de código aberto.
Neste tutorial, vamos explicar alguns pontos importantes de configuração e uso do keycloak com a dojot.
Nota
Público: usuários e administradores
Nível: básico a intermediário
Tempo de leitura: 20 m
Índice
Atenção
A dojot tenant is equivalent to a keycloak realm.
4.1. Requerido¶
Caso você esteja inicializando um deployment, instalando uma dojot, veja o tópico Configurando Senhas (Requerido) via variáveis de ambiente.
4.2. Recomendações¶
Sempre utilize HTTPs
Use senhas fortes, por default o mínimo exigido são senhas com 8 caracteres, um número, uma letra maiúscula, uma letra minúscula e um caracter especial
Configure o SMTP
4.3. Acessando o Painel Administrativo¶
Substitua <url> e <realm> para seu caso
4.3.1. Utilizando o realm master¶
Atenção
Só é possível acessar esta página utilizando localhost ou https.
Para usar um usuário que pertence ao Realm master e pode controlar todos os realms, acesse <url>/auth/` , por exemplo https://dojot.com.br/auth.
4.3.2. Utilizando um usuário com papel (role) de admin¶
Para usar um usuário que pertence a um realm pode controlar somente este realm, acesse <url>/auth/admin/<realm>/console , por exemplo, https://dojot.com.br/auth/admin/admin/console.
4.3.3. Verificando realm selecionado¶
Após acessar a interface administrativa do keycloak utilizando um dos caminhos acima certifique que você está com o realm que quer utilizar selecionado, na barra lateral esquerda é possível selecionar o realm de interesse, como destacado na imagem abaixo:
4.4. Acessando Configurações de uma Conta¶
Substitua <url> e <realm> para seu caso
Para acessar sua conta e fazer mudanças como habilitar autenticação de 2 fatores, mudar senha, mudar e-mail, acesse o link <url>/auth/realms/<realm>/account, por exemplo, https://dojot.com.br/auth/realms/admin/account
4.5. Criando um novo usuário¶
Acesse o painel administrativo como explicado no tópico Acessando o Painel Administrativo.
No menu da barra à esquerda selecione a opção Users e em seguida clique em Add User.
Now let’s create the user, first fill in Username. It is recommended to fill in
the Email field and in Required User Actions Add the Update Password and
Verify Email options, but for Verify Email to make sense it is necessary
to have the SMTP configured for the Realm of interest. If you do not want to
configure SMTP do not put Verify Email. Another point is that if an SMTP
has not been configured, it is necessary to create a temporary password
and provide the user, to do so, access the Credentials tab after creating in Save.
Além disso é importante definir o papel**(**role) deste usuário no seu Realm, sem isso ele não poderá ser utilizado. Após clicar em ` Save ` uma das abas será a Role Mapping, clique sobre ela para definir o papel do usuário. Na aba Role Mapping na caixa Available Roles haverá as opções ` admin ` e ` user ` (caso não forem criados outros Roles) . Um usuário com o role ` admin ` tem acesso a todas as APIs e também ao Painel Administrativo do seu realm enquanto que um usuário com o Role ` user ` tem acesso a API, mas não pode acessar o painel administrativo. Selecione o Role (Papel) que se encaixa a esse novo usuário e o adicione na Caixa Assigned Roles.
4.6. Configurando SMTP pela interface gráfica¶
Acesse o painel administrativo como explicado no tópico Acessando o Painel Administrativo.
No menu da barra à esquerda selecione a opção Realm Settings e em seguida selecione a aba Email e faça as configurações necessárias.
4.7. Configurando HTTPs como requerido pela interface gráfica¶
Nota
Você deve estar utilizando um deployment com HTTPs configurado.
Acesse o painel administrativo como explicado no tópico Acessando o Painel Administrativo.
No menu da barra à esquerda selecione a opção Realm Settings e em seguida selecione a aba Login, em Require SSL selecione a opção external requests e clique em Save
4.8. Criando um novo realm (tenant na dojot)¶
Acesse o painel administrativo como explicado no tópico Acessando o Painel Administrativo, porém necessariamente utilizando o realm master.
No menu lateral à esquerda, passe o mouse em cima do nome do Realm corrente e irá aparecer uma opção Add realm, clique sobre ela.
Nota
O realm criado aqui será baseado no arquivo passado como base para o keycloak, veja mais em Arquivo de configuração do keycloak base para criação de realms.
4.9. Obtendo Token de Acesso (Access Token JWT)¶
4.9.1. A partir de username e uma senha em um realm (Não recomendado)¶
Nós temos um cliente criado no keycloak configurado e desabilitado com o nome dev-test-cli que permite obter um JWT a partir de um login e senha em um realm.
Atenção
Por motivos de segurança ele é desativado por padrão, após o uso, é recomendável desativá-lo novamente.
4.9.1.1. Como habilitar e desabilitar o cliente dev-test-cli¶
Acesse o painel administrativo como explicado no tópico Acessando o Painel Administrativo.
Selecione no menu lateral esquerdo a opção**Clients** , irá carregar uma nova tela, nela haverá a lista de clientes. Procure pelo cliente dev-test-cli, clique sobre ele, abrirá uma nova tela com várias opções, uma delas será a opção**Enabled** que estará com o valor OFF mude para o valor ON`, vá até o final da página e clique em ``Save.
Lembre-se de desabilitar este cliente após utilização voltando o valor Enabled para valor OFF e salvando, por questões de segurança.
Atenção
Para utilizar o comando abaixo de obtenção do JWT você já deve ter acesso pela interface gráfica o keycloak uma vez e definido uma senha. Caso você não tenha feito isso ainda, siga o tópico anterior:ref:Accessing an Account Settings antes de continuar. Além disso é necessário ter curl e jq. In Debian-based Linux distributions you can run: sudo apt-get install curl jq
Após habilitar o cliente dev-test-cli será possível obter um token utilizando login e senha. Como no comando curl abaixo utilizando a API do keycloak, altere os valores de DOJOT_URL, REALM, USERNAME e PASSWORD de acordo com o seu caso :
DOJOT_URL=http://localhost:8000
REALM=admin
USERNAME=admin
PASSWORD=password
JWT=$(curl --location --request POST ${DOJOT_URL}/auth/realms/${REALM}/protocol/openid-connect/token \
--data-urlencode "username=${USERNAME}" \
--data-urlencode "password=${PASSWORD}" \
--data-urlencode "client_id=dev-test-cli" \
--data-urlencode "grant_type=password" 2>/dev/null | jq -r ".access_token")
Se tudo der certo o token estará disponível na variável JWT, para checar o valor da variável utilize o comando abaixo:
echo $JWT
Atenção
O tempo de vida deste token de acesso não é muito grande, este processo retorna um refresh token que é pode ser utilizado para obter um novo access token.
4.9.2. Para uma aplicação backend¶
Para utilizar o Token de Acesso em uma aplicação backend recomenda-se criar um novo Cliente para o realm the interesse ou os realms de interesse, lembre-se de configuração-los em Client Protocol com o valor openid-connect, Access Type com o valor Confidential e utilizar o Secret obtido na aba Credentials, existem várias maneiras de configurações possíveis. É importante seguir os padrões estabelecidos de segurança atualmente para o OAuth 2 e o OpenIDConnect. Há várias bibliotecas para keycloak em várias linguagens que podem auxiliar neste desenvolvimento.
4.9.3. Para uma aplicação frontend¶
Nós temos um microsserviço com o intuito de ajudar no desenvolvimento a assegurar mais segurança para utilização do keycloak com a dojot, veja mais sobre em Backstage. Há como utilizar o keycloak diretamente com `PKCE`_e OpenID Connect também. É importante seguir os padrões estabelecidos de segurança atualmente para o OAuth 2 e o OpenIDConnect.
4.9.4. Para uma aplicação mobile¶
Nós não temos casos de uso, mas é importante seguir os padrões estabelecidos de segurança atualmente para o OAuth 2 e o OpenIDConnect. Alguns pontos iniciais seriam para prestar a atenção seriam criar um Cliente novo com o Access Type public e utilizar PKCE..
4.10. Configurações de Deployment¶
4.10.1. Configurando Senhas (Requerido) via variáveis de ambiente¶
Os deployments (**Docker compose e Ansible - kubernetes **) da dojot não vem com senhas definidas para os usuário admin e master e é necessário configurar essas senhas para que os deployments inicializem corretamente, caso não configurados os serviços não irão inicializar e a dojot ficará indisponível. Mas atenção esses valores só são aplicados quando o keycloak inicializar pela primeira vez e os realm são criados, não afetará os realms já existentes.
Atenção
Ao configurar use senhas fortes, por default o mínimo exigido são senhas com 8 caracteres, um número, uma letra maiúscula, uma letra minúscula e um caracter especial.
4.10.1.1. Docker compose¶
É necessário definir um valor de senha no arquivo .env para as variáveis ``KEYCLOAK_MASTER_PASSWORD `` e ``KEYCLOAK_ADMIN_PASSWORD_TEMP ``. O valor ``KEYCLOAK_ADMIN_PASSWORD_TEMP `` será a senha do usuário admin de todos os realms quando criado. Veja mais em settings required.
4.10.1.2. Ansible (kubernetes)¶
Trabalho em progresso
4.10.2. Configurando SMTP via variáveis de ambiente¶
É possível configurar SMTP via variáveis de ambiente, mas atenção esses valores só são aplicados quando o realm é criado, não afetará os realms já existentes. Para configurar um realm que já existe veja Configurando SMTP pela interface gráfica.
4.10.2.1. Docker compose¶
Veja mais em configuring SMTP.
4.10.2.2. Ansible (kubernetes)¶
Trabalho em progresso
4.10.3. Configurando HTTPs como requerido via variáveis de ambiente¶
Esses valores só são aplicados quando o realm é criado, não afetará os realms já existentes e o realm master. Para realms já existentes veja Configurando HTTPs como requerido pela interface gráfica.
4.10.3.1. Docker compose¶
É necessário definir o valor EXTERNAL no arquivo .env para a variável KEYCLOAK_REALM_SSL_MODE . Veja mais em configuring HTTPs.
4.10.3.2. Ansible (kubernetes)¶
Trabalho em progresso
4.10.4. Arquivo de configuração do keycloak base para criação de realms¶
Arquivo de configuração usado como base para criação dos realms no keycloak. É o arquivo exportado de um realm pelo keycloak completo. Este arquivo é configurado usando a variável de ambiente DOJOT_CUSTOM_REALM_REP_FILE no serviço do keycloak. Ao criar um novo realm os identificadores (ids) e nome do realm neste arquivo são ignorados. Porém é importante salientar que nossos deployments tanto para docker-compose quanto para ansible (kubernetes) Já possuem um arquivo com as configurações necessárias para utilização da dojot.
4.10.4.1. Docker compose¶
No caso do docker-compose este arquivo encontra-se em keycloak/customRealmRepresentation.json
4.10.4.2. Ansible (kubernetes)¶
Trabalho em progresso
4.10.5. Bibliotecas antigas¶
Para manter compatibilidade com a dojot é necessário fornecer o login e senha do master ou de um usuário que consiga obter a lista de realms disponíveis nas bibliotecas antigas, sendo elas dojot-module-nodejs, iotagent-nodejs, dojot-module-python, dojot-module-java, iotagent-java, veja mais nas suas respectivas documentações. Porém é importante salientar que nossos deployments tanto para docker-compose quanto para ansible (kubernetes) já estão preparados para isso e é apenas necessário configurar as senhas como descrito no tópico Configurando Senhas (Requerido) via variáveis de ambiente.
4.10.6. Configurando novas rotas, serviços, recursos, no keycloak para utilizar autorização¶
Em keycloak settings example há um caso básico de exemplo de configuração, você pode utilizá-lo como base para novas configurações.
4.10.7. Configurando keycloak com Nginx¶
Em how to use keycloak with a nginx proxy há um exemplo com as configurações necessárias.