Tutorial de Keycloak
Paulo Jerônimo
Table of Contents
1. Resumo ................................................................................................................. 1
2. Pré-requisitos ........................................................................................................ 2
3. Baixando e iniciando o Keycloak para a execução de aplicações de
demonstração ............................................................................................................ 3
4. Testando alguns exemplos ................................................................................... 4
4.1. Os exemplos "pré-configurados" ................................................................. 4
4.1.1. Importando o realm dos exemplos ................................................... 4
4.1.2. Compilando e implantando os exemplos .......................................... 4
4.1.3. Testando, manualmente, os exemplos customer-portal e product-
portal ............................................................................................................ 4
4.1.4. Uma aplicação escrita puramente em Javascript: customer-portal-
js .................................................................................................................. 6
4.1.5. Gerenciando a conta do usuário logado ........................................... 7
4.2. O exemplo basic-auth ................................................................................. 8
4.2.1. Compilando, implantando e testando a aplicação ............................. 9
5. A console de administração do Keycloak ........................................................... 10
6. Baixando e compilando os fontes do Keycloak .................................................. 11
6.1. Utilizando uma versão específica ............................................................. 11
ii
Chapter 1. Resumo
Este tutorial apresenta um passo a passo prático para a instalação e testes do
1
Keycloak [Link].
Os procedimentos descritos aqui podem ser realizados num ambiente Linux, OS X ou
2
Windows mas, nesse último caso, você precisará instalar o Cygwin para não precisar
fazer nenhuma adaptação nos comandos apresentados. A instalalação do Cygwin
para a execução deste tutorial deve ser realizada conforme os passos descritos na
3
página [Link]
1
[Link]
2
[Link]
3
[Link]
1
Chapter 2. Pré-requisitos
Para executar os passos deste tutorial você precisará ter instalado em tua máquina:
1. O JDK (este tutorial foi testado com a versão 1.8.0_60);
2. O Maven (este tutorial foi testado com a versão 3.3.3);
A montagem de um ambiente Java EE pode ser realizada
rapidamente no Linux, no OS X ou no Windows (+ Cygwin), através
1
do projeto javaee-ambiente .
1
[Link]
2
Chapter 3. Baixando e iniciando o
Keycloak para a execução de aplicações
de demonstração
Uma forma fácil de testar e aprender os conceitos do Keycloak é baixando o
1 2
instalador de desenvolvimento (arquivo [Link] ). Esse
arquivo contém parte dos arquivos necessários para a execução dos exemplos deste
tutorial. Isso inclui um servidor Wildfly [Link] com o servidor Keycloak e seus
adaptadores já configurados.
3
Se você montou teu ambiente através do projeto javaee-ambiente
o download e a descompactação do instalador de desenvolvimento
do keycloak podem ser realizados pelo comando keycloak_demo
install . Dessa forma, ele ficará instalado no diretório configurado
para a variável FERRAMENTAS_DIR .
Descompacte esse arquivo. Você pode utilizar o comando abaixo:
tar xvfz [Link]
Ajuste o valor da variável JBOSS_HOME da seguinte forma:
export JBOSS_HOME=$PWD/[Link]/keycloak
Inicie o Keycloak com o seguinte comando:
$JBOSS_HOME/bin/[Link] &
1
[Link]
2
[Link]
3
[Link]
3
Chapter 4. Testando alguns exemplos
4.1. Os exemplos "pré-configurados"
Vá para o diretório $JBOSS_HOME/../examples/preconfigured-demo e leia o
arquivo [Link] . Os passos descritos a seguir são uma simplificação dos passos
apresentados nele.
cd $JBOSS_HOME/../examples/preconfigured-demo
view [Link]
4.1.1. Importando o realm dos exemplos
Abra a URL [Link]
Logue-se com o usuário admin e a senha admin . Será solicitada a troca da senha.
Clique em Select file e selecione o arquivo [Link] que está dentro
do diretório em que você está. Em seguida, clique no botão Upload .
4.1.2. Compilando e implantando os exemplos
Abra um shell que contenha o Maven no PATH . Compile e implante os exemplos
com os comandos a seguir. Observe o log do Wildfly enquanto o último comando é
executado para averiguar a implantação dos exemplos.
mvn clean install
mvn wildfly:deploy
4.1.3. Testando, manualmente, os exemplos customer-portal
e product-portal
Acesse a URL [Link] Clique em Customer Listing
e você será redirecionado para a página de autenticação no Keycloak. Informe o
usuário ( bburke@[Link] ) e a senha ( password ).
Observe o log do Wildfly.
Observe a tela que será apresentada. Note o valor de Servlet User Principal .
4
Testando alguns exemplos
Clique em products . Observe que não foi solicitada nova autenticacão apesar
do contexto ter sido alterado para product-portal (esta app também utiliza os
mecanismos de segurança do Java EE).
Clique em Product Listing . Note que o valor do User é o mesmo que o
apresentado na tela customers para o campo Servlet User Principal .
Retorne a tela anterior e clique em Admin Interface (URL: [Link]
product-portal/admin/[Link]). Note que será exibida a mensagem Forbidden .
Isso ocorre pelo fato do usuário logado ( bburke@[Link] ) não ter o perfil
admin (exigido para esse acesso). Podemos saber disso observando dois arquivos:
o primeiro deles é o [Link] que, conforme a saída do comando abaixo, exige que o
usuário logado tenha o perfil admin para acessar qualquer URL abaixo de /admin/ :
$ sed -n 9,17p product-app/src/main/webapp/WEB-INF/[Link]
<security-constraint>
<web-resource-collection>
<web-resource-name>Admins</web-resource-name>
<url-pattern>/admin/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
</security-constraint>
O segundo arquivo é o [Link] . As configurações para o usuário
bburke@[Link] são apresentadas na saída do comando a seguir:
$ sed -n 15,29p [Link]
{
"username" : "bburke@[Link]",
"enabled": true,
"email" : "bburke@[Link]",
"firstName": "Bill",
"lastName": "Burke",
"credentials" : [
{ "type" : "password",
"value" : "password" }
],
"realmRoles": [ "user" ],
"clientRoles": {
"account": [ "manage-account" ]
}
5
Testando alguns exemplos
},
Notamos que, nessa saída, o usuário em questão não possui a role admin (as roles
que ele possui estão definidas para o valor de realmRoles ).
Retorne a URL [Link]
Clique em [Link] . Navegue pelos links.
Em Account edite os campos Email , Fist name e Last name informando
teus próprios dados e clique em Save .
Em Password , altere a senha e clique em Save .
Em Sessions , clique em Log out all sessions .
Efetue o Log in informando teu email e senha. Após o logon, note que o
Username permanece bburke@[Link] .
Observe o log do Wildfly.
4.1.4. Uma aplicação escrita puramente em Javascript:
customer-portal-js
Em Applications clique em customer-portal-js . Em seguida, em
Customer Listing . Note a alteração do valor dos campos Email e Full Name ,
Fist e Last , conforme os dados que você editou no passo anterior.
A aplicação [Link] é uma aplicação totalmente escrita
em Javascript. Para ver sua estrutura, sem os arquivos gerados na contrução da
aplicação, execute:
$ (cd customer-app-js; mvn clean)
$ tree customer-app-js/
customer-app-js/
|-- [Link]
`-- src
`-- main
`-- webapp
|-- customers
| `-- [Link]
|-- [Link]
`-- [Link]
6
Testando alguns exemplos
4 directories, 4 files
Clique em logout .
4.1.5. Gerenciando a conta do usuário logado
Efetue o Log in informando admin e password .
Clique em products e, em seguida, em Admin Interface . Note que, agora,
o acesso a tela de administração não exibe a mensagem Forbiden liberando a
visualização como deveria ser. Isso ocorre pelo fato do usuário logado (admin) ter
o perfil admin (exigido para esse acesso). Detalhe: essa configuração é visível no
em [Link] . Observe a saída do comando abaixo. Ela imprime as linhas
relativas a configuração do usuário admin no arquivo [Link]:
$ sed -n 60,74p [Link]
{
"username" : "admin",
"enabled": true,
"email" : "admin@[Link]",
"firstName": "Admin",
"lastName": "Burke",
"credentials" : [
{ "type" : "password",
"value" : "password" }
],
"realmRoles": [ "user","admin" ],
"clientRoles": {
"realm-management": [ "realm-admin" ]
}
},
Vá para a URL [Link] Clique em Customer Admin
Interface . Note que, agora, também é obtido o acesso a esse link.
Volte para a tela anterior. Clique em Customer Listing e, em
seguida, em manage acct (URL: [Link]
referrer=customer-portal). Note que o usuário logado ( admin ) não tem permissão de
acesso. A explicação para disso está logo abaixo.
Volte para a tela anterior e clique em logout . Note que você estará na página
Customer Portal . Clique em Customer Listing .
7
Testando alguns exemplos
Efetue o Log in como bburque@[Link] (utilize a nova senha que você
criou).
Clique em manage acct . Note que é possível que esse usuário gerencie sua conta,
o que não ocorre para o usuário admin . A explicação está nas roles definidas para
esse usuário: ele possui a role manage-accout definida para o acesso ao cliente
account (associado a URL base /auth/realms/demo/account ). O mesmo não
ocorre para o usuário admin .
Em Applications , clique em angular-product .
Clique em Reload para exibir a lista de produtos.
Clique em Sign Out para voltar a tela de autenticação.
Observe que qualquer tentativa de acesso a URLs protegidas pelo Keycloak (como,
por exemplo, [Link] será redirecionada a tela de
autenticação provida pelo Keycloak.
Acesse a tela de administração de usuários do realm ([Link]
admin/master/console/#/realms/demo/users). Clique em View all users e, em
seguida, no usuário admin . Vá para a aba Role Mappings . Em Client Roles
selecione account . Em Available Roles selecione manager-account e
clique no botão Add selected . Fazendo isso o usuário admin poderá gerenciar
1
sua conta acessando manage acct . Verifique!
4.2. O exemplo basic-auth
O estrutura do exemplo basic-auth pode ser observada pela seguinte saída:
$ tree
.
|-- [Link]
|-- [Link]
|-- [Link]
`-- src
`-- main
|-- java
| `-- org
| `-- keycloak
| `-- example
1
[Link]
8
Testando alguns exemplos
| `-- basicauth
| |-- [Link]
| `-- [Link]
`-- webapp
`-- WEB-INF
|-- [Link]
`-- [Link]
9 directories, 7 files
4.2.1. Compilando, implantando e testando a aplicação
Acesse a interface administrativa do Keycloak e importe o arquivo
[Link] .
Compile e implante a aplicação:
mvn clean package wildfly:jboss
Teste a aplicação:
curl [Link]
value=hello
Observe, na interface administrativa do Keycloak, a existência de uma sessão.
9
Chapter 5. A console de administração
do Keycloak
A URL [Link] possibilita o acesso a interface de
administração do Keycloak.
Você se lembra que trocou a senha para o usuário admin no primeiro
acesso a essa interface?
10
Chapter 6. Baixando e compilando os
fontes do Keycloak
6.1. Utilizando uma versão específica
Para gerar a versão [Link]:
git clone [Link]
cd keycloak
git tag
git checkout [Link]
mvn install
Mais detalhes sobre como contribuir na solução de um bug, gerar um release, etc,
1
podem ser obtidos na página [Link] .
1
[Link]
11