keycloak 2.2.4 → 2.2.5

This diff has not been reviewed by any users.
Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: c12d7d40888c54116b3acf7b8c557f5cc3f8cf3e
4
- data.tar.gz: '087f959c26357e9b0b42dd1d75bd3f5c092ac8e6'
3
+ metadata.gz: d189f823216b37635131258bfa9b5cbcd6a82bad
4
+ data.tar.gz: c5384a3e5c3c106389268ae8e6e3d86ed90482af
5
5
  SHA512:
6
- metadata.gz: 56adbcfc6faf37f64fe34946ec479442d7a174af62cb9160e340b2439304bd3d2c3c9cf0908f8e869cd55e31553219aab065bb268e4eb72cf8d8856f084aac34
7
- data.tar.gz: c47d7d3e4b8dd908f75fb447cf6b6102ed90faca575c75cd5b81881426734180bb3d2d58dd3b8a07d3b2bbf21fc931bf49a4adabca0fd19a8335af23d346750b
6
+ metadata.gz: 9b9c6ab1860f5d38ba8c250ed1dd4bb96546e2c5b6e6d9a8fe88f933bbe7ae2e7b92cd10985b5de1ff6b613671e7fbac2c7d43ba3702566b802d9d33b532a6d4
7
+ data.tar.gz: 7023508ba14efe5f1f2d2925b4238826dedba881775d2aa8fd089f4af56b24b496e0461fdbc7d2446db65274dd72777072a562504ed6549db4d9909743499989
data/README.md CHANGED
@@ -3,6 +3,8 @@ A gem Keycloak foi desenvolvida para integrar aplicações e serviços ao sistem
3
3
 
4
4
  O seu desenvolvimento foi baseado na versão 3.2 do Keycloak, cuja documentação pode ser encontrada [aqui](http://www.keycloak.org/archive/documentation-3.2.html).
5
5
 
6
+ Publicação da gem: https://rubygems.org/gems/keycloak
7
+
6
8
  ## Instalação
7
9
 
8
10
  Adicione esta linha no <b>Gemfile</b> de sua aplicação:
@@ -19,6 +21,10 @@ Ou instale você mesmo:
19
21
 
20
22
  $ gem install keycloak
21
23
 
24
+ Para adicionar seu arquivo de configuração:
25
+
26
+ $ rails generate initializer
27
+
22
28
  ## Utilização
23
29
 
24
30
  Considerando que você já possua um ambiente do Keycloak configurado e a gem já instalada, o próximo passo é definir como será a autenticação da aplicação. O Keycloak trabalha com os principais protocolos de autenticação, tais como o OpenID Connect, Oauth 2.0 e SAML 2.0, integrando acesso a sistemas via Single-Sign On, podendo inclusive disponibilizar acessos a usuários LDAP ou Active Directory.
@@ -48,14 +54,14 @@ Este atributo serve para definir se as exceções HTTP geradas nos retornos das
48
54
  Keycloak.keycloak_controller
49
55
  ```
50
56
 
51
- É recomendado que a sua aplicação possua um controller que centraliza as ações de sessão que o Keycloak irá gerenciar, tais como a ação de login, logout, atualização de sessão, reset de senha, entre outras. Defina neste atributo qual é o nome do controller que desempenhará esse papel. Se o nome do seu controler é `SessionController`, então o valor deste atributo deverá ser apenas `session`. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
57
+ É recomendado que a sua aplicação possua um controller que centraliza as ações de sessão que o Keycloak irá gerenciar, tais como a ação de login, logout, atualização de sessão, reset de senha, entre outras. Defina neste atributo qual é o nome do controller que desempenhará esse papel. Se o nome do seu controller é `SessionController`, então o valor deste atributo deverá ser apenas `session`. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
52
58
 
53
59
 
54
60
  ```ruby
55
61
  Keycloak.proc_cookie_token
56
62
  ```
57
63
 
58
- Este atributo trata-se de um método anônimo (lâmbida). O mesmo deve ser implementado na aplicação para que a gem tenha acesso ao token de autenticação que, por sua vez, deverá ser armazenado no cookie. Ao realizar a autenticação no keycloak através da gem, o sistema deverá armazenar o token retornado no cookie do browser, como por exemplo:
64
+ Este atributo trata-se de um método anônimo (lambda). O mesmo deve ser implementado na aplicação para que a gem tenha acesso ao token de autenticação que, por sua vez, deverá ser armazenado no cookie. Ao realizar a autenticação no keycloak através da gem, o sistema deverá armazenar o token retornado no cookie do browser, como por exemplo:
59
65
  ```ruby
60
66
  cookies.permanent[:keycloak_token] = Keycloak::Client.get_token(params[:user_login], params[:user_password])
61
67
  ```
@@ -65,7 +71,7 @@ Keycloak.proc_cookie_token = -> do
65
71
  cookies.permanent[:keycloak_token]
66
72
  end
67
73
  ```
68
- Desta forma, todas as vezes que a gem precisar utilizar as informações do token para consumir um serviço do Keycloak, ele irá invocar este método lâmbida.
74
+ Desta forma, todas as vezes que a gem precisar utilizar as informações do token para consumir um serviço do Keycloak, ele irá invocar este método lambda.
69
75
 
70
76
 
71
77
  ```ruby
@@ -73,7 +79,7 @@ Keycloak.proc_external_attributes
73
79
  ```
74
80
 
75
81
  O Keycloak dá a possibilidade de que novos atributos sejam mapeados no cadastro de usuários. Porém, quando esses atributos são específicos da aplicação, recomenda-se que a própria os gerencie. Para isso, a melhor solução é criar esses atributos na aplicação - exemplo: criar uma tabela no banco de dados da própria aplicação contendo as colunas representando cada um dos atributos, inserindo também nessa tabela uma coluna de identificação única (unique key), contendo na mesma o Id do usuário criado no Keycloak, indicando que esse pertencente àquele Id possui aqueles atributos.
76
- Para que a gem tenha acesso a esses atributos, definina o atributo`Keycloak.proc_external_attributes` com um método lâmbida obtendo do `model` os atributos do usuário logado. Exemplo:
82
+ Para que a gem tenha acesso a esses atributos, defina o atributo`Keycloak.proc_external_attributes` com um método lambda obtendo do `model` os atributos do usuário logado. Exemplo:
77
83
  ```ruby
78
84
  Keycloak.proc_external_attributes = -> do
79
85
  atributos = UsuariosAtributo.find_or_create_by(user_keycloak_id: Keycloak::Client.get_attribute('sub'))
@@ -85,7 +91,7 @@ Keycloak.proc_external_attributes = -> do
85
91
  end
86
92
  ```
87
93
 
88
- <b>Observação:</b> Os atributos `Keycloak.proc_cookie_token` e `Keycloak.proc_external_attributes` podem ser definidos no `initialize` do controler `ApplicationController`.
94
+ <b>Observação:</b> Os atributos `Keycloak.proc_cookie_token` e `Keycloak.proc_external_attributes` podem ser definidos no `initialize` do controller `ApplicationController`.
89
95
 
90
96
 
91
97
  ### Keycloak::Client
@@ -99,7 +105,7 @@ Vamos ao detalhamento de cada um desses métodos:
99
105
  Keycloak::Client.get_token(user, password)
100
106
  ```
101
107
 
102
- Caso você opte por efetuar a autenticação dos usuários utilizando a tela da sua própria aplicação, então utilize esse método. Basta invocá-lo no método de login no `controller`definido com o controlador de sessão de sua aplicação, passando como parâmetro o <b>usuário</b> e a <b>senha</b> informados pelo usuário. Caso a autenticação seja válida, então será retornado um JSON contendo entre as informações principais o `access_token` e o `refresh_token`.
108
+ Caso você opte por efetuar a autenticação dos usuários utilizando a tela da sua própria aplicação, então utilize esse método. Basta invocá-lo no método de login no `controller` definido com o controlador de sessão de sua aplicação, passando como parâmetro o <b>usuário</b> e a <b>senha</b> informados pelo usuário. Caso a autenticação seja válida, então será retornado um JSON contendo entre as informações principais o `access_token` e o `refresh_token`.
103
109
 
104
110
 
105
111
  ```ruby
@@ -134,21 +140,21 @@ Esse método retorna a as informações da sessão do `token` passado como parâ
134
140
  Keycloak::Client.get_token_by_client_credentials(client_id = '', secret = '')
135
141
  ```
136
142
 
137
- Há alguns serviços do Keycloak como <b>reset de senha</b>, <b>cadastro de usuário</b> na tela inicial da aplicação ou até mesmo autenticação seguindo o padrão <b>OAuth 2.0</b>, que a autenticação de um usuário torna-se desnecessária. Sendo assim, podemos obter um token utilizando as credenciais da sua própria aplicação (Client) cadastrada no Keycloak. Para obter esse token, deve-se passar como parâmetro desse método o `client_id` - informado pela pessoa que cadastrou sua aplicação no Keycloak - e a `secret` de sua aplicação gerado pelo Keycloak - para gerar uma `secret`, o <b>Access Type</b> do seu Client (Aplicação) deverá estar configurado como `confidential`. Caso você não passe nenhum desses parãmetros, a gem utilizará as credenciais contidas no arquivo de instalação citado anteriormente.
143
+ Há alguns serviços do Keycloak como <b>reset de senha</b>, <b>cadastro de usuário</b> na tela inicial da aplicação ou até mesmo autenticação seguindo o padrão <b>OAuth 2.0</b>, que a autenticação de um usuário torna-se desnecessária. Sendo assim, podemos obter um token utilizando as credenciais da sua própria aplicação (Client) cadastrada no Keycloak. Para obter esse token, deve-se passar como parâmetro desse método o `client_id` - informado pela pessoa que cadastrou sua aplicação no Keycloak - e a `secret` de sua aplicação gerado pelo Keycloak - para gerar uma `secret`, o <b>Access Type</b> do seu Client (Aplicação) deverá estar configurado como `confidential`. Caso você não passe nenhum desses parâmetros, a gem utilizará as credenciais contidas no arquivo de instalação citado anteriormente.
138
144
 
139
145
 
140
146
  ```ruby
141
147
  Keycloak::Client.logout(redirect_uri = '', refresh_token = '')
142
148
  ```
143
149
 
144
- Quando utilizado antes da expiração da sessão do usuário logado, esse método encerra a sessão. Se o prâmetro `redirect_uri` for alimentado, então o Keycloak redirecionará a sua aplicação para a url informada após a efetuação do logout. O segundo parâmetro é o `refresh_token` obtido no momento da autenticação ou da atualização da sessão. Caso este último não seja informado, então a gem utilizará o `refresh_token` do cookie.
150
+ Quando utilizado antes da expiração da sessão do usuário logado, esse método encerra a sessão. Se o parâmetro `redirect_uri` for alimentado, então o Keycloak redirecionará a sua aplicação para a url informada após a efetuação do logout. O segundo parâmetro é o `refresh_token` obtido no momento da autenticação ou da atualização da sessão. Caso este último não seja informado, então a gem utilizará o `refresh_token` do cookie.
145
151
 
146
152
 
147
153
  ```ruby
148
154
  Keycloak::Client.get_userinfo(access_token = '')
149
155
  ```
150
156
 
151
- Esse método retorna informações sintéticas do usuário representado pelo `access_token` passado como parâmetro, tais como `sub` - que é o Id do usuário autenticado -, `preferred_username` - que é o nome do usuário autenticado - e `email` - que é o e-mail do usuário. Cado o parâmetro `access_token` não seja informado, então a gem obterá essa informação no cookie.
157
+ Esse método retorna informações sintéticas do usuário representado pelo `access_token` passado como parâmetro, tais como `sub` - que é o Id do usuário autenticado -, `preferred_username` - que é o nome do usuário autenticado - e `email` - que é o e-mail do usuário. Caso o parâmetro `access_token` não seja informado, então a gem obterá essa informação no cookie.
152
158
 
153
159
 
154
160
  ```ruby
@@ -195,7 +201,7 @@ Quando implementado o método `Keycloak.proc_external_attributes`, o método `ex
195
201
 
196
202
  ### Keycloak::Admin
197
203
 
198
- O módulo `Keycloak::Admin`disponibiliza métodos que representam as [REST APIs do Keycloak](http://www.keycloak.org/docs-api/3.2/rest-api/index.html). Para a utilização dessas APIs, será necessário um `access_token` ativo, ou seja, a autenticação deverá ocorrer antes da utilização dos métodos para que um token válido seja utilizado como credencial. Caso o `access_token` não seja informado, então a gem utilizará o `access_token` do cookie. O usuário autenticado deverá ter o `role` do respectivo serviço invocado - roles do client `realm-management`, que representa o gerênciamento do reino.
204
+ O módulo `Keycloak::Admin`disponibiliza métodos que representam as [REST APIs do Keycloak](http://www.keycloak.org/docs-api/3.2/rest-api/index.html). Para a utilização dessas APIs, será necessário um `access_token` ativo, ou seja, a autenticação deverá ocorrer antes da utilização dos métodos para que um token válido seja utilizado como credencial. Caso o `access_token` não seja informado, então a gem utilizará o `access_token` do cookie. O usuário autenticado deverá ter o `role` do respectivo serviço invocado - roles do client `realm-management`, que representa o gerenciamento do reino.
199
205
 
200
206
  Segue abaixo a lista dos métodos. O parâmetro de rota `{realm}` de todas as APIs será obtido do arquivo de instalação `keycloak.json`:
201
207
 
@@ -261,7 +267,7 @@ Keycloak::Admin.revoke_consent_user(id, client_id = nil, access_token = nil)
261
267
  Keycloak::Admin.update_account_email(id, actions, redirect_uri = '', client_id = nil, access_token = nil)
262
268
  ```
263
269
 
264
- `update_account_email` envia um e-mail de atualização da conta para o usuário representado pelo parâmetro `id`. O email contém um link que o usuário poderá clicar para executar um conjunto de ações representados pelo parâmetro `actions` - que aguarda um `array` de [ações definidas pelo Keycloak](http://www.keycloak.org/docs/3.2/server_admin/topics/users/required-actions.html). Um exemplo de valor que pode ser passado para o parâmetro `actions` é `['UPDATE_PASSWORD']`, que indica que a ação que o usuário deverá tomar ao clicar o link do e-mail é de alterar a sua senha. No parâmetro `redirect_uri`, caso necessário, deverá ser passada uma <b>url</b> para que, ao término do envio do e-mail, a aplicação seja redirecionada. O parâmetro `client_id` deverá ser informado caso o Client responsável pela as ações que deverão ser executadas não seja o mesmo do arquivo de instalação `keycloak.json`.
270
+ `update_account_email` envia um e-mail de atualização da conta para o usuário representado pelo parâmetro `id`. O e-mail contém um link que o usuário poderá clicar para executar um conjunto de ações representados pelo parâmetro `actions` - que aguarda um `array` de [ações definidas pelo Keycloak](http://www.keycloak.org/docs/3.2/server_admin/topics/users/required-actions.html). Um exemplo de valor que pode ser passado para o parâmetro `actions` é `['UPDATE_PASSWORD']`, que indica que a ação que o usuário deverá tomar ao clicar o link do e-mail é de alterar a sua senha. No parâmetro `redirect_uri`, caso necessário, deverá ser passada uma <b>url</b> para que, ao término do envio do e-mail, a aplicação seja redirecionada. O parâmetro `client_id` deverá ser informado caso o Client responsável pela as ações que deverão ser executadas não seja o mesmo do arquivo de instalação `keycloak.json`.
265
271
 
266
272
 
267
273
  ```ruby
@@ -285,7 +291,7 @@ Keycloak::Admin.get_clients(query_parameters = nil, access_token = nil)
285
291
  Keycloak::Admin.get_all_roles_client(id, access_token = nil)
286
292
  ```
287
293
 
288
- `get_all_roles_client` retorna uma lista de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) com todos os <b>roles</b> do client identidicado pelo parâmetro `id` - deve ser passado nesse parâmetro o `ID` do Client e não o `client_id`.
294
+ `get_all_roles_client` retorna uma lista de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) com todos os <b>roles</b> do client identificado pelo parâmetro `id` - deve ser passado nesse parâmetro o `ID` do Client e não o `client_id`.
289
295
 
290
296
 
291
297
  ```ruby
@@ -325,3 +331,146 @@ Keycloak::Admin.update_effective_user_roles(id, client_id, roles_names, access_t
325
331
  ```
326
332
 
327
333
  `update_effective_user_roles` não está na lista de <b>Admin APIs</b> do Keycloak. Este método vincula ao usuário representado pelo parâmetro `id` todos os roles passados em um `array` no parâmetro `roles_names`. Os roles passados no parâmetro `roles_names` deverão pertencer ao Client representado pelo parâmetro `client_id`. Caso o usuário possua o vínculo com um role que não esteja no parâmetro `roles_names`, esse vínculo será removido, pois a finalidade desse método é que o usuário assuma efetivamente os roles passados nesse parâmetro. Em caso de sucesso, o retorno será `true`.
334
+
335
+
336
+ ```ruby
337
+ PUT /admin/realms/{realm}/users/{id}/reset-password
338
+ Keycloak::Admin.reset_password(id, credential_representation, access_token = nil)
339
+ ```
340
+
341
+ `reset_password` altera a senha do usuário representado pelo parâmetro `id`. A nova senha é representada pelo parâmetro `credential_representation`, que trata-se de um conjunto de informações formatadas segundo a seção [CredentialRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_credentialrepresentation) do manual de APIs do Keycloak.
342
+
343
+
344
+ ```ruby
345
+ GET /admin/realms/{realm}/groups/{id}/role-mappings/clients/{client}/composite
346
+ Keycloak::Admin.get_effective_client_level_role_composite_user(id, client, access_token = nil)
347
+ ```
348
+
349
+ `get_effective_client_level_role_composite_user` retorna uma lista (array) de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) de um <b>Grupo</b> representado pelo parâmetro `id` atrelados a um <b>Client</b> representado pelo parâmetro `client`.
350
+
351
+
352
+ Caso tenha algum serviço no manual [Keycloak Admin REST API](http://www.keycloak.org/docs-api/3.2/rest-api/index.html) que não tenha sido implementado na gem, há uma possibilidade do mesmo ser invocado utilizando os <b>Generics Methods</b> do modelu `Keycloak::Admin`. Os <b>Generics Methods</b> te possibilita fazer a requisição de qualquer uma das APIs, seja ela `GET`, `POST`, `PUT` ou `DELETE`, passando os parâmetros da requisição como `hashes` nos parâmetros `query_parameters` e `body_parameter` dos <b>Generics Methods</b>.
353
+ <br>
354
+ Veja a seguir os <b>Generics Methods</b>:
355
+ <br>
356
+
357
+ ```ruby
358
+ Keycloak::Admin.generic_get(service, query_parameters = nil, access_token = nil)
359
+ ```
360
+
361
+ `generic_get` permite que você faça requisições de serviços `GET` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Queries Parameters</b> da requisição.<br>
362
+ Exemplo:
363
+ ```ruby
364
+ Keycloak::Admin.generic_get("users/", {email: 'admin@test.com'}, "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...")
365
+ ```
366
+
367
+
368
+
369
+ ```ruby
370
+ Keycloak::Admin.generic_post(service, query_parameters, body_parameter, access_token = nil)
371
+ ```
372
+
373
+ `generic_post` permite que você faça requisições de serviços `POST` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Query Parameters</b> da requisição. No parâmetro `body_parameter` você poderá passar um `hash` contendo os <b>Body Parameters</b> da requisição.<br>
374
+ Exemplo:
375
+ ```ruby
376
+ Keycloak::Admin.generic_post("users/", nil, { username: "admin", email: "admin@test.com", enabled: true }, "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...")
377
+ ```
378
+
379
+
380
+ ```ruby
381
+ Keycloak::Admin.generic_put(service, query_parameters, body_parameter, access_token = nil)
382
+ ```
383
+
384
+ `generic_put` permite que você faça requisições de serviços `PUT` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Query Parameters</b> da requisição. No parâmetro `body_parameter` você poderá passar um `hash` contendo os <b>Body Parameters</b> da requisição.
385
+
386
+
387
+ ```ruby
388
+ Keycloak::Admin.generic_delete(service, query_parameters = nil, body_parameter = nil, access_token = nil)
389
+ ```
390
+
391
+ `generic_delete` permite que você faça requisições de serviços `DELETE` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Query Parameters</b> da requisição. No parâmetro `body_parameter` você poderá passar um `hash` contendo os <b>Body Parameters</b> da requisição.
392
+
393
+
394
+
395
+ ### Keycloak::Internal
396
+
397
+ O módulo `Keycloak::internal`disponibiliza métodos criados para facilitar a interação entre a aplicação e o <b>Keycloak</b>. Partindo das informações encontradas no arquivo de instalação `keycloak.json`, todos os métodos invocados serão autenticados automaticamente, utilizando as credências da aplicação (`grant_type = client_credentials`), dependendo assim dos <b>roles</b> atribuídos a mesma para que o retorno da requisição seja autorizado.
398
+
399
+
400
+ ```ruby
401
+ Keycloak::Internal.get_users(query_parameters = nil)
402
+ ```
403
+
404
+ `get_users` invoca o método `Keycloak::Admin.get_users` que, por sua vez, retorna uma lista de usuários, filtrada de acordo com o hash de parâmetros passado em `query_parameters`.
405
+
406
+
407
+ ```ruby
408
+ Keycloak::Internal.change_password(user_id, redirect_uri = '')
409
+ ```
410
+
411
+ `change_password` invocará a API `PUT /admin/realms/{realm}/users/{id}/execute-actions-email` do Keycloak requisitando a action `UPDATE_PASSWORD`. Isso fará com que o Keycloak dispare um e-mail para o usuário representado pelo parâmetro `user_id`. O parâmetro `redirect_uri` é opcional. Se não for preenchido, então não haverá nenhum link para clicar após a ação de reset de senha ter sido concluída.
412
+
413
+
414
+ ```ruby
415
+ Keycloak::Internal.get_user_info(user_login, whole_word = false)
416
+ ```
417
+
418
+ `get_user_info`, baseado no parâmetro `user_login`, que poderá recepcionar o `username` ou o `email` do usuário, retornará uma lista (array) de [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) no caso em que o parâmetro `whole_word` for `false`, ou retornará um [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) quando o parâmetro `whole_word` for `true`. O parâmetro `whole_word` indica se o método deverá considerar usuários que tenham no `username` ou `email` parte da expressão passada no parâmetro `user_login` - para os casos de `whole_word = false` -, ou que tenha exatamente a expressão passada nesse parâmetro - para os casos de `whole_word = true`.
419
+
420
+
421
+ ```ruby
422
+ Keycloak::Internal.forgot_password(user_login, redirect_uri = '')
423
+ ```
424
+
425
+ `forgot_password` invocará o método `Keycloak::Internal.change_password` após invocar o método `Keycloak::Internal.get_user_info` - passando no parâmetro `user_login` do método descrito o parâmetro `user_login`deste tópico e passando `true` no parâmetro `whole_word` -. A utilização deste método é indicado para os casos de aplicações permitam o reset da senha dos usuários sem que o mesmo esteja logado.
426
+
427
+
428
+ ```ruby
429
+ Keycloak::Internal.exists_name_or_email(value, user_id = '')
430
+ ```
431
+
432
+ `exists_name_or_email` verifica se no reino já existe algum usuário com `username` ou o `email` passado no parâmetro `value`. O parâmetro `user_id` serve para passar o `ID` de um usuário nos casos em que deseja-se alterar o `username` ou o `email` do mesmo, para que assim sejam considerados na verificação do `username` e do `email` usuários diferentes do usuário com o `ID` informado em `user_id`.
433
+
434
+
435
+ ```ruby
436
+ Keycloak::Internal.get_logged_user_info
437
+ ```
438
+
439
+ `get_logged_user_info` retorna o [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do usuário logado na aplicação.
440
+
441
+
442
+ ```ruby
443
+ # GET /admin/realms/{realm}/users
444
+ Keycloak::Internal.logged_federation_user?
445
+ ```
446
+
447
+ `logged_federation_user?` incova o método `Keycloak::Internal.get_logged_user_info` e verifica se o mesmo é um <b>Federation User</b> (um usuário do AD por exemplo).
448
+
449
+
450
+ ```ruby
451
+ # GET /admin/realms/{realm}/users
452
+ Keycloak::Internal.create_starter_user(username, password, email, client_roles_names, proc = nil)
453
+ ```
454
+
455
+ `create_starter_user` é indicado para aplicações que permitam a criação de novos usuários sem que um usuário esteja logado ou até mesmo para criar novos usuários a partir do `rake db:seed`. Nos parâmetros `username`, `password` e `email` devem ser passados o nome do usuário, a senha do usuário, e o e-mail do usuário, respectivamente. No parâmetro `client_roles_names`deve ser passado uma lista (array) com o nome dos `roles` do Client que serão atribuídos ao usuário. O parâmetro `proc` trata-se de um método <b>lambda</b> que disponibilizará como parâmetro a [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do usuário criado para que sejam definidas ações por parte da aplicação. Este método terá como retorno o mesmo retorno do método do parâmetro `proc` se o mesmo for definido, caso contrário retornará a [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do usuário criado.
456
+
457
+
458
+ ```ruby
459
+ Keycloak::Internal.get_client_roles
460
+ ```
461
+
462
+ `get_client_roles` retornará uma lista (array) de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) do Client indicado pelo arquivo de instalação `keycloak.json`.
463
+
464
+
465
+ ```ruby
466
+ Keycloak::Internal.get_client_user_roles(user_id)
467
+ ```
468
+
469
+ `get_client_user_roles` invocará o método `Keycloak::Admin.get_effective_client_level_role_composite_user` considerando o Client indicado pelo arquivo de instalação `keycloak.json` e o usuário representado pelo parâmetro `user_id`.
470
+
471
+
472
+ ```ruby
473
+ Keycloak::Internal.has_role?(user_id, user_role)
474
+ ```
475
+
476
+ `has_role?` informará se o usuário representado pelo parâmetro `user_id` possui o <b>role</b> com o nome representado pelo parâmetro `user_role`.
@@ -0,0 +1,480 @@
1
+ # Keycloak
2
+ A gem Keycloak foi desenvolvida para integrar aplicações e serviços ao sistema [Keycloak](http://www.keycloak.org/) da [Red Hat](https://www.redhat.com) para controle de usuários, autenticação, autorização e sessão.
3
+
4
+ O seu desenvolvimento foi baseado na versão 3.2 do Keycloak, cuja documentação pode ser encontrada [aqui](http://www.keycloak.org/archive/documentation-3.2.html).
5
+
6
+ Publicação da gem: https://rubygems.org/gems/keycloak
7
+
8
+ ## Instalação
9
+
10
+ Adicione esta linha no <b>Gemfile</b> de sua aplicação:
11
+
12
+ ```ruby
13
+ gem 'keycloak'
14
+ ```
15
+
16
+ Então execute:
17
+
18
+ $ bundle
19
+
20
+ Ou instale você mesmo:
21
+
22
+ $ gem install keycloak
23
+
24
+ To add the configuration file:
25
+
26
+ $ rails generate initializer
27
+
28
+ Para adicionar o arquivo de configuração:
29
+
30
+ $ rails generate initializer
31
+
32
+ ## Utilização
33
+
34
+ Considerando que você já possua um ambiente do Keycloak configurado e a gem já instalada, o próximo passo é definir como será a autenticação da aplicação. O Keycloak trabalha com os principais protocolos de autenticação, tais como o OpenID Connect, Oauth 2.0 e SAML 2.0, integrando acesso a sistemas via Single-Sign On, podendo inclusive disponibilizar acessos a usuários LDAP ou Active Directory.
35
+
36
+ Ao cadastrar um Reino e também um Client no seu ambiente Keycloak, será necessário fazer o download do arquivo de instalação do Client para dentro da pasta raiz da aplicação, para que a gem obtenha as informações necessárias para interagir com o Keycloak. Para fazer esse download, basta acessar o cadastro de seu Client, clicar na aba <b>Installation</b>, selecionar <b>Keycloak OIDC JSON</b> no campo <b>Format option</b> e clicar em <b>Download</b>.
37
+
38
+ A gem possui um módulo principal chamado <b>Keycloak</b>. Dentro desse módulo há três outros módulos: <b>Client</b>, <b>Admin</b> e <b>Internal</b>.
39
+
40
+ ### Module Keycloak
41
+
42
+ O módulo Keycloak possui alguns atributos e suas definições são fundamentais para o perfeito funcionamento da gem na aplicação.
43
+
44
+ ```ruby
45
+ Keycloak.proxy
46
+ ```
47
+
48
+ Caso o ambiente onde a sua aplicação será utilizada exija a utilização de proxy para o consumo das APIs do Keycloak, então defina-o neste atributo. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
49
+
50
+ ```ruby
51
+ Keycloak.generate_request_exception
52
+ ```
53
+
54
+ Este atributo serve para definir se as exceções HTTP geradas nos retornos das requisições feitas para o Keycloak serão ou não estouradas na aplicação. Caso definido como `false`, então a exceção não será estourada e a resposta HTTP será retornada para a aplicação fazer o seu próprio tratamento. O valor default deste atributo é `true`. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
55
+
56
+
57
+ ```ruby
58
+ Keycloak.keycloak_controller
59
+ ```
60
+
61
+ É recomendado que a sua aplicação possua um controller que centraliza as ações de sessão que o Keycloak irá gerenciar, tais como a ação de login, logout, atualização de sessão, reset de senha, entre outras. Defina neste atributo qual é o nome do controller que desempenhará esse papel. Se o nome do seu controller é `SessionController`, então o valor deste atributo deverá ser apenas `session`. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
62
+
63
+
64
+ ```ruby
65
+ Keycloak.proc_cookie_token
66
+ ```
67
+
68
+ Este atributo trata-se de um método anônimo (lambda). O mesmo deve ser implementado na aplicação para que a gem tenha acesso ao token de autenticação que, por sua vez, deverá ser armazenado no cookie. Ao realizar a autenticação no keycloak através da gem, o sistema deverá armazenar o token retornado no cookie do browser, como por exemplo:
69
+ ```ruby
70
+ cookies.permanent[:keycloak_token] = Keycloak::Client.get_token(params[:user_login], params[:user_password])
71
+ ```
72
+ A aplicação poderá recuperar o token no cookie implementando o método `Keycloak.proc_cookie_token` da seguinte forma:
73
+ ```ruby
74
+ Keycloak.proc_cookie_token = -> do
75
+ cookies.permanent[:keycloak_token]
76
+ end
77
+ ```
78
+ Desta forma, todas as vezes que a gem precisar utilizar as informações do token para consumir um serviço do Keycloak, ele irá invocar este método lambda.
79
+
80
+
81
+ ```ruby
82
+ Keycloak.proc_external_attributes
83
+ ```
84
+
85
+ O Keycloak dá a possibilidade de que novos atributos sejam mapeados no cadastro de usuários. Porém, quando esses atributos são específicos da aplicação, recomenda-se que a própria os gerencie. Para isso, a melhor solução é criar esses atributos na aplicação - exemplo: criar uma tabela no banco de dados da própria aplicação contendo as colunas representando cada um dos atributos, inserindo também nessa tabela uma coluna de identificação única (unique key), contendo na mesma o Id do usuário criado no Keycloak, indicando que esse pertencente àquele Id possui aqueles atributos.
86
+ Para que a gem tenha acesso a esses atributos, defina o atributo`Keycloak.proc_external_attributes` com um método lambda obtendo do `model` os atributos do usuário logado. Exemplo:
87
+ ```ruby
88
+ Keycloak.proc_external_attributes = -> do
89
+ atributos = UsuariosAtributo.find_or_create_by(user_keycloak_id: Keycloak::Client.get_attribute('sub'))
90
+ if atributos.status.nil?
91
+ atributos.status = false
92
+ atributos.save
93
+ end
94
+ atributos
95
+ end
96
+ ```
97
+
98
+ <b>Observação:</b> Os atributos `Keycloak.proc_cookie_token` e `Keycloak.proc_external_attributes` podem ser definidos no `initialize` do controller `ApplicationController`.
99
+
100
+
101
+ ### Keycloak::Client
102
+
103
+ O módulo `Keycloak::Client` possui os métodos que representam os serviços de <b>endpoints</b>. Esses serviços são fundamentais para a criação e atualização de tokens, efetuação de login e logout, e, também para a obtenção de informações sintéticas de um usuário logado. O que habilita a gem a fazer uso de todos esses serviços é o arquivo de instalação do client citado anteriormente.
104
+
105
+ Vamos ao detalhamento de cada um desses métodos:
106
+
107
+
108
+ ```ruby
109
+ Keycloak::Client.get_token(user, password)
110
+ ```
111
+
112
+ Caso você opte por efetuar a autenticação dos usuários utilizando a tela da sua própria aplicação, então utilize esse método. Basta invocá-lo no método de login no `controller` definido com o controlador de sessão de sua aplicação, passando como parâmetro o <b>usuário</b> e a <b>senha</b> informados pelo usuário. Caso a autenticação seja válida, então será retornado um JSON contendo entre as informações principais o `access_token` e o `refresh_token`.
113
+
114
+
115
+ ```ruby
116
+ Keycloak::Client.url_login_redirect(redirect_uri, response_type = 'code')
117
+ ```
118
+
119
+ Para efetuar a autenticação dos usuários de sua aplicação utilizando um template configurado no Keycloak, redirecione a requisição para a url retornada nesse método. Passe como parâmetro a url que o usuário terá acesso no caso de êxito na autenticação(`redirect_uri`) e também o tipo de resposta (`response_type`), que caso não informado, a gem assumirá o valor `code`. Caso a autenticação seja bem sucedida, então será retornado um `code` que te habilitará a requisitar um token ao Keycloak.
120
+
121
+
122
+ ```ruby
123
+ Keycloak::Client.get_token_by_code(code, redirect_uri)
124
+ ```
125
+
126
+ Ao utilizar o método `Keycloak::Client.url_login_redirect` para obter um `code`, passe-o como parâmetro neste método para que o Keycloak retorne um token, efetuando assim o login do usuário na aplicação. O segundo parâmetro (`redirect_uri`) deve ser passado para que, ao disponibilizar um token, o Keycloak redirecione para a url informada.
127
+
128
+
129
+ ```ruby
130
+ Keycloak::Client.get_token_by_refresh_token(refresh_token = '')
131
+ ```
132
+
133
+ Quando o usuário já estiver logado e a sua aplicação acompanhar internamente o tempo de expiração do token fornecido pelo Keycloak, então esse método poderá ser utilizado para a renovação desse token, caso o mesmo ainda seja válido. Para isso, basta passar como parãmetro o `refresh_token`. Caso não seja informado o `refresh_token`, a gem utilizará o `refresh_token` armazenado no cookie.
134
+
135
+
136
+ ```ruby
137
+ Keycloak::Client.get_token_introspection(token = '')
138
+ ```
139
+
140
+ Esse método retorna a as informações da sessão do `token` passado como parâmetro. Entre as informações retornadas, a mais importante é o campo `active`, pois ele informa se a sessão do token passado no parâmetro é ativo ou não. Isso auxiliará a sua aplicação a controlar se a sessão do usuário logado expirou ou não. Caso nenhum token seja passado como parâmetro, a gem utilizará o último `access_token` armazenado no cookie da aplicação.
141
+
142
+
143
+ ```ruby
144
+ Keycloak::Client.get_token_by_client_credentials(client_id = '', secret = '')
145
+ ```
146
+
147
+ Há alguns serviços do Keycloak como <b>reset de senha</b>, <b>cadastro de usuário</b> na tela inicial da aplicação ou até mesmo autenticação seguindo o padrão <b>OAuth 2.0</b>, que a autenticação de um usuário torna-se desnecessária. Sendo assim, podemos obter um token utilizando as credenciais da sua própria aplicação (Client) cadastrada no Keycloak. Para obter esse token, deve-se passar como parâmetro desse método o `client_id` - informado pela pessoa que cadastrou sua aplicação no Keycloak - e a `secret` de sua aplicação gerado pelo Keycloak - para gerar uma `secret`, o <b>Access Type</b> do seu Client (Aplicação) deverá estar configurado como `confidential`. Caso você não passe nenhum desses parâmetros, a gem utilizará as credenciais contidas no arquivo de instalação citado anteriormente.
148
+
149
+
150
+ ```ruby
151
+ Keycloak::Client.logout(redirect_uri = '', refresh_token = '')
152
+ ```
153
+
154
+ Quando utilizado antes da expiração da sessão do usuário logado, esse método encerra a sessão. Se o parâmetro `redirect_uri` for alimentado, então o Keycloak redirecionará a sua aplicação para a url informada após a efetuação do logout. O segundo parâmetro é o `refresh_token` obtido no momento da autenticação ou da atualização da sessão. Caso este último não seja informado, então a gem utilizará o `refresh_token` do cookie.
155
+
156
+
157
+ ```ruby
158
+ Keycloak::Client.get_userinfo(access_token = '')
159
+ ```
160
+
161
+ Esse método retorna informações sintéticas do usuário representado pelo `access_token` passado como parâmetro, tais como `sub` - que é o Id do usuário autenticado -, `preferred_username` - que é o nome do usuário autenticado - e `email` - que é o e-mail do usuário. Caso o parâmetro `access_token` não seja informado, então a gem obterá essa informação no cookie.
162
+
163
+
164
+ ```ruby
165
+ Keycloak::Client.url_user_account
166
+ ```
167
+
168
+ Retorna a <b>url</b> para acesso ao cadastro de usuários do Reino do arquivo de instalação (`keycloak.json`). Para ter acesso a tela, o Keycloak exigirá a autenticação do usuário. Após logado, e caso tenha permissão, o usuário terá acesso a suas informações cadastrais podendo inclusive alterá-las.
169
+
170
+
171
+ ```ruby
172
+ Keycloak::Client.has_role?(user_role, access_token = '')
173
+ ```
174
+
175
+ O método `has_role?` decodifica o JWT `access_token` e verifica se o usuário dono do token possui o <b>role</b> informado no parâmetro `user_role`. Caso o `access_token` não seja informado, então a gem utilizará o `access_token` do cookie.
176
+
177
+
178
+ ```ruby
179
+ Keycloak::Client.user_signed_in?(access_token = '')
180
+ ```
181
+
182
+ Esse método verifica se o `access_token` passado no parâmetro ainda está ativo. Para verificar se o usuário está ativo ou não, internamente a gem invoca o método `get_token_introspection`. Caso o `access_token` não seja informado, então a gem utilizará o `access_token` do cookie.
183
+
184
+
185
+ ```ruby
186
+ Keycloak::Client.get_attribute(attribute_name, access_token = '')
187
+ ```
188
+
189
+ Esse método decodifica o JWT `access_token` e retorna o valor do atributo de nome passado no parâmetro `attribute_name`. Esse atributo pode ser um <b>mapper</b> - cadastrado na seção <b>Mappers</b> do cadastro do <b>Client</b> do Reino. Caso o `access_token` não seja informado, então a gem utilizará o `access_token` do cookie.
190
+
191
+
192
+ ```ruby
193
+ Keycloak::Client.token
194
+ ```
195
+
196
+ Retorna o último token autenticado armazenado no cookie. Quando na aplicação é implementado o método `Keycloak.proc_cookie_token` e um usuário faz a autenticação da aplicação, esse método retornará o token desse usuário.
197
+
198
+
199
+ ```ruby
200
+ Keycloak::Client.external_attributes
201
+ ```
202
+
203
+ Quando implementado o método `Keycloak.proc_external_attributes`, o método `external_attributes` o retornará. A finalidade desse método é retornar os atributos específicos da aplicação não mapeados no Keycloak.
204
+
205
+
206
+ ### Keycloak::Admin
207
+
208
+ O módulo `Keycloak::Admin`disponibiliza métodos que representam as [REST APIs do Keycloak](http://www.keycloak.org/docs-api/3.2/rest-api/index.html). Para a utilização dessas APIs, será necessário um `access_token` ativo, ou seja, a autenticação deverá ocorrer antes da utilização dos métodos para que um token válido seja utilizado como credencial. Caso o `access_token` não seja informado, então a gem utilizará o `access_token` do cookie. O usuário autenticado deverá ter o `role` do respectivo serviço invocado - roles do client `realm-management`, que representa o gerenciamento do reino.
209
+
210
+ Segue abaixo a lista dos métodos. O parâmetro de rota `{realm}` de todas as APIs será obtido do arquivo de instalação `keycloak.json`:
211
+
212
+
213
+ ```ruby
214
+ # GET /admin/realms/{realm}/users
215
+ Keycloak::Admin.get_users(query_parameters = nil, access_token = nil)
216
+ ```
217
+
218
+ `get_users` retorna uma lista de usuários, filtrada de acordo com o hash de parâmetros passado em `query_parameters`.
219
+
220
+
221
+ ```ruby
222
+ # POST /admin/realms/{realm}/users
223
+ Keycloak::Admin.create_user(user_representation, access_token = nil)
224
+ ```
225
+
226
+ `create_user` cria um novo usuário no Keycloak. O parâmetro `user_representation` deve ser um hash conforme o [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do Keycloak. O retorno deste método será `true` para o caso de sucesso.
227
+
228
+
229
+ ```ruby
230
+ # GET /admin/realms/{realm}/users/count
231
+ Keycloak::Admin.count_users(access_token = nil)
232
+ ```
233
+
234
+ `count_users` retorna a quantidade de usuários do reino.
235
+
236
+
237
+ ```ruby
238
+ # GET /admin/realms/{realm}/users/{id}
239
+ Keycloak::Admin.get_user(id, access_token = nil)
240
+ ```
241
+
242
+ `get_user` retorna a representação do usuário identificado pelo parâmetro `id` - que é o <b>ID</b> criado pelo Keycloak ao criar um novo usuário.
243
+
244
+
245
+ ```ruby
246
+ # PUT /admin/realms/{realm}/users/{id}
247
+ Keycloak::Admin.update_user(id, user_representation, access_token = nil)
248
+ ```
249
+
250
+ `update_user` atualiza o cadastro do usuário identificado pelo `id` - que é o <b>ID</b> criado pelo Keycloak ao criar um novo usuário. No parâmetro `user_representation` deverá ser uma hash com os campos que serão alterados, respeitando o [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do Keycloak. O retorno deste método será `true` para o caso de sucesso.
251
+
252
+
253
+ ```ruby
254
+ # DELETE /admin/realms/{realm}/users/{id}
255
+ Keycloak::Admin.delete_user(id, access_token = nil)
256
+ ```
257
+
258
+ `delete_user` exclui o cadastro do usuário identificado pelo `id` - que é o <b>ID</b> criado pelo Keycloak ao criar um novo usuário. O retorno deste método será `true` para o caso de sucesso.
259
+
260
+
261
+ ```ruby
262
+ # DELETE /admin/realms/{realm}/users/{id}/consents/{client}
263
+ Keycloak::Admin.revoke_consent_user(id, client_id = nil, access_token = nil)
264
+ ```
265
+
266
+ `revoke_consent_user` revoga os tokens de um usuário identificado pelo `id` - que é o <b>ID</b> criado pelo Keycloak ao criar um novo usuário - no client identificado pelo parâmetro `client_id`.
267
+
268
+
269
+ ```ruby
270
+ # PUT /admin/realms/{realm}/users/{id}/execute-actions-email
271
+ Keycloak::Admin.update_account_email(id, actions, redirect_uri = '', client_id = nil, access_token = nil)
272
+ ```
273
+
274
+ `update_account_email` envia um e-mail de atualização da conta para o usuário representado pelo parâmetro `id`. O e-mail contém um link que o usuário poderá clicar para executar um conjunto de ações representados pelo parâmetro `actions` - que aguarda um `array` de [ações definidas pelo Keycloak](http://www.keycloak.org/docs/3.2/server_admin/topics/users/required-actions.html). Um exemplo de valor que pode ser passado para o parâmetro `actions` é `['UPDATE_PASSWORD']`, que indica que a ação que o usuário deverá tomar ao clicar o link do e-mail é de alterar a sua senha. No parâmetro `redirect_uri`, caso necessário, deverá ser passada uma <b>url</b> para que, ao término do envio do e-mail, a aplicação seja redirecionada. O parâmetro `client_id` deverá ser informado caso o Client responsável pela as ações que deverão ser executadas não seja o mesmo do arquivo de instalação `keycloak.json`.
275
+
276
+
277
+ ```ruby
278
+ # GET /admin/realms/{realm}/users/{id}/role-mappings
279
+ Keycloak::Admin.get_role_mappings(id, access_token = nil)
280
+ ```
281
+
282
+ `get_role_mappings` retorna todas as <b>Role Mappings</b> do reino atribuídas ao usuário identificado pelo parâmetro `id`, independentemente do Client.
283
+
284
+
285
+ ```ruby
286
+ # GET /admin/realms/{realm}/clients
287
+ Keycloak::Admin.get_clients(query_parameters = nil, access_token = nil)
288
+ ```
289
+
290
+ `get_clients` retorna uma lista de [ClientRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_clientrepresentation) Clients pertencentes ao reino. O parâmetro `query_parameters` espera um hash com os atributos `clientId` - caso deseje que a lista seja filtrada pelo `client_id` - e `viewableOnly` - para filtrar se os Clients de administração do Keycloak serão ou não retornados na lista.
291
+
292
+
293
+ ```ruby
294
+ # GET /admin/realms/{realm}/clients/{id}/roles
295
+ Keycloak::Admin.get_all_roles_client(id, access_token = nil)
296
+ ```
297
+
298
+ `get_all_roles_client` retorna uma lista de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) com todos os <b>roles</b> do client identificado pelo parâmetro `id` - deve ser passado nesse parâmetro o `ID` do Client e não o `client_id`.
299
+
300
+
301
+ ```ruby
302
+ # GET /admin/realms/{realm}/clients/{id}/roles/{role-name}
303
+ Keycloak::Admin.get_roles_client_by_name(id, role_name, access_token = nil)
304
+ ```
305
+
306
+ `get_roles_client_by_name` retorna a [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) do role identificado pelo parâmetro `role_name` - que é o nome do role.
307
+
308
+
309
+ ```ruby
310
+ # POST /admin/realms/{realm}/users/{id}/role-mappings/clients/{client}
311
+ Keycloak::Admin.add_client_level_roles_to_user(id, client, role_representation, access_token = nil)
312
+ ```
313
+
314
+ `add_client_level_roles_to_user` insere um <b>role</b> do Client (representado pelo parâmetro `client`) ao usuário representado pelo parâmetro `id`. O parâmetro `role_representation` deverá receber um `array` de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) que serão inseridos no usuário. Em caso de sucesso, o retorno será `true`.
315
+
316
+
317
+ ```ruby
318
+ # DELETE /admin/realms/{realm}/users/{id}/role-mappings/clients/{client}
319
+ Keycloak::Admin.delete_client_level_roles_from_user(id, client, role_representation, access_token = nil)
320
+ ```
321
+
322
+ `delete_client_level_roles_from_user` exclui um <b>Client-Role</b> (representado pelo parâmetro `client`) do usuário representado pelo parâmetro `id`. O parâmetro `role_representation` deverá receber um `array` de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) que serão retirados do usuário. Em caso de sucesso, o retorno será `true`.
323
+
324
+
325
+ ```ruby
326
+ # GET /admin/realms/{realm}/users/{id}/role-mappings/clients/{client}
327
+ Keycloak::Admin.get_client_level_role_for_user_and_app(id, client, access_token = nil)
328
+ ```
329
+
330
+ `get_client_level_role_for_user_and_app` retorna uma lista de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) dos <b>Client-Roles</b> do Client representado pelo parâmetro `client` vinculados ao usuário representado pelo parâmetro `id`.
331
+
332
+
333
+ ```ruby
334
+ Keycloak::Admin.update_effective_user_roles(id, client_id, roles_names, access_token = nil)
335
+ ```
336
+
337
+ `update_effective_user_roles` não está na lista de <b>Admin APIs</b> do Keycloak. Este método vincula ao usuário representado pelo parâmetro `id` todos os roles passados em um `array` no parâmetro `roles_names`. Os roles passados no parâmetro `roles_names` deverão pertencer ao Client representado pelo parâmetro `client_id`. Caso o usuário possua o vínculo com um role que não esteja no parâmetro `roles_names`, esse vínculo será removido, pois a finalidade desse método é que o usuário assuma efetivamente os roles passados nesse parâmetro. Em caso de sucesso, o retorno será `true`.
338
+
339
+
340
+ ```ruby
341
+ PUT /admin/realms/{realm}/users/{id}/reset-password
342
+ Keycloak::Admin.reset_password(id, credential_representation, access_token = nil)
343
+ ```
344
+
345
+ `reset_password` altera a senha do usuário representado pelo parâmetro `id`. A nova senha é representada pelo parâmetro `credential_representation`, que trata-se de um conjunto de informações formatadas segundo a seção [CredentialRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_credentialrepresentation) do manual de APIs do Keycloak.
346
+
347
+
348
+ ```ruby
349
+ GET /admin/realms/{realm}/groups/{id}/role-mappings/clients/{client}/composite
350
+ Keycloak::Admin.get_effective_client_level_role_composite_user(id, client, access_token = nil)
351
+ ```
352
+
353
+ `get_effective_client_level_role_composite_user` retorna uma lista (array) de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) de um <b>Grupo</b> representado pelo parâmetro `id` atrelados a um <b>Client</b> representado pelo parâmetro `client`.
354
+
355
+
356
+ Caso tenha algum serviço no manual [Keycloak Admin REST API](http://www.keycloak.org/docs-api/3.2/rest-api/index.html) que não tenha sido implementado na gem, há uma possibilidade do mesmo ser invocado utilizando os <b>Generics Methods</b> do modelu `Keycloak::Admin`. Os <b>Generics Methods</b> te possibilita fazer a requisição de qualquer uma das APIs, seja ela `GET`, `POST`, `PUT` ou `DELETE`, passando os parâmetros da requisição como `hashes` nos parâmetros `query_parameters` e `body_parameter` dos <b>Generics Methods</b>.
357
+ <br>
358
+ Veja a seguir os <b>Generics Methods</b>:
359
+ <br>
360
+
361
+ ```ruby
362
+ Keycloak::Admin.generic_get(service, query_parameters = nil, access_token = nil)
363
+ ```
364
+
365
+ `generic_get` permite que você faça requisições de serviços `GET` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Queries Parameters</b> da requisição.<br>
366
+ Exemplo:
367
+ ```ruby
368
+ Keycloak::Admin.generic_get("users/", {email: 'admin@test.com'}, "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...")
369
+ ```
370
+
371
+
372
+
373
+ ```ruby
374
+ Keycloak::Admin.generic_post(service, query_parameters, body_parameter, access_token = nil)
375
+ ```
376
+
377
+ `generic_post` permite que você faça requisições de serviços `POST` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Query Parameters</b> da requisição. No parâmetro `body_parameter` você poderá passar um `hash` contendo os <b>Body Parameters</b> da requisição.<br>
378
+ Exemplo:
379
+ ```ruby
380
+ Keycloak::Admin.generic_post("users/", nil, { username: "admin", email: "admin@test.com", enabled: true }, "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldU...")
381
+ ```
382
+
383
+
384
+ ```ruby
385
+ Keycloak::Admin.generic_put(service, query_parameters, body_parameter, access_token = nil)
386
+ ```
387
+
388
+ `generic_put` permite que você faça requisições de serviços `PUT` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Query Parameters</b> da requisição. No parâmetro `body_parameter` você poderá passar um `hash` contendo os <b>Body Parameters</b> da requisição.
389
+
390
+
391
+ ```ruby
392
+ Keycloak::Admin.generic_delete(service, query_parameters = nil, body_parameter = nil, access_token = nil)
393
+ ```
394
+
395
+ `generic_delete` permite que você faça requisições de serviços `DELETE` do <b>Keycloak</b>. A parte da URI que identifica o serviço deve ser passada no parâmetro `service`, já com os parâmetros de rota (como o `{client}`, por exemplo) devidamente substituídos. No parâmetro `query_parameters` você poderá passar um `hash` contendo os <b>Query Parameters</b> da requisição. No parâmetro `body_parameter` você poderá passar um `hash` contendo os <b>Body Parameters</b> da requisição.
396
+
397
+
398
+
399
+ ### Keycloak::Internal
400
+
401
+ O módulo `Keycloak::internal`disponibiliza métodos criados para facilitar a interação entre a aplicação e o <b>Keycloak</b>. Partindo das informações encontradas no arquivo de instalação `keycloak.json`, todos os métodos invocados serão autenticados automaticamente, utilizando as credências da aplicação (`grant_type = client_credentials`), dependendo assim dos <b>roles</b> atribuídos a mesma para que o retorno da requisição seja autorizado.
402
+
403
+
404
+ ```ruby
405
+ Keycloak::Internal.get_users(query_parameters = nil)
406
+ ```
407
+
408
+ `get_users` invoca o método `Keycloak::Admin.get_users` que, por sua vez, retorna uma lista de usuários, filtrada de acordo com o hash de parâmetros passado em `query_parameters`.
409
+
410
+
411
+ ```ruby
412
+ Keycloak::Internal.change_password(user_id, redirect_uri = '')
413
+ ```
414
+
415
+ `change_password` invocará a API `PUT /admin/realms/{realm}/users/{id}/execute-actions-email` do Keycloak requisitando a action `UPDATE_PASSWORD`. Isso fará com que o Keycloak dispare um e-mail para o usuário representado pelo parâmetro `user_id`. O parâmetro `redirect_uri` é opcional. Se não for preenchido, então não haverá nenhum link para clicar após a ação de reset de senha ter sido concluída.
416
+
417
+
418
+ ```ruby
419
+ Keycloak::Internal.get_user_info(user_login, whole_word = false)
420
+ ```
421
+
422
+ `get_user_info`, baseado no parâmetro `user_login`, que poderá recepcionar o `username` ou o `email` do usuário, retornará uma lista (array) de [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) no caso em que o parâmetro `whole_word` for `false`, ou retornará um [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) quando o parâmetro `whole_word` for `true`. O parâmetro `whole_word` indica se o método deverá considerar usuários que tenham no `username` ou `email` parte da expressão passada no parâmetro `user_login` - para os casos de `whole_word = false` -, ou que tenha exatamente a expressão passada nesse parâmetro - para os casos de `whole_word = true`.
423
+
424
+
425
+ ```ruby
426
+ Keycloak::Internal.forgot_password(user_login, redirect_uri = '')
427
+ ```
428
+
429
+ `forgot_password` invocará o método `Keycloak::Internal.change_password` após invocar o método `Keycloak::Internal.get_user_info` - passando no parâmetro `user_login` do método descrito o parâmetro `user_login`deste tópico e passando `true` no parâmetro `whole_word` -. A utilização deste método é indicado para os casos de aplicações permitam o reset da senha dos usuários sem que o mesmo esteja logado.
430
+
431
+
432
+ ```ruby
433
+ Keycloak::Internal.exists_name_or_email(value, user_id = '')
434
+ ```
435
+
436
+ `exists_name_or_email` verifica se no reino já existe algum usuário com `username` ou o `email` passado no parâmetro `value`. O parâmetro `user_id` serve para passar o `ID` de um usuário nos casos em que deseja-se alterar o `username` ou o `email` do mesmo, para que assim sejam considerados na verificação do `username` e do `email` usuários diferentes do usuário com o `ID` informado em `user_id`.
437
+
438
+
439
+ ```ruby
440
+ Keycloak::Internal.get_logged_user_info
441
+ ```
442
+
443
+ `get_logged_user_info` retorna o [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do usuário logado na aplicação.
444
+
445
+
446
+ ```ruby
447
+ # GET /admin/realms/{realm}/users
448
+ Keycloak::Internal.logged_federation_user?
449
+ ```
450
+
451
+ `logged_federation_user?` incova o método `Keycloak::Internal.get_logged_user_info` e verifica se o mesmo é um <b>Federation User</b> (um usuário do AD por exemplo).
452
+
453
+
454
+ ```ruby
455
+ # GET /admin/realms/{realm}/users
456
+ Keycloak::Internal.create_starter_user(username, password, email, client_roles_names, proc = nil)
457
+ ```
458
+
459
+ `create_starter_user` é indicado para aplicações que permitam a criação de novos usuários sem que um usuário esteja logado ou até mesmo para criar novos usuários a partir do `rake db:seed`. Nos parâmetros `username`, `password` e `email` devem ser passados o nome do usuário, a senha do usuário, e o e-mail do usuário, respectivamente. No parâmetro `client_roles_names`deve ser passado uma lista (array) com o nome dos `roles` do Client que serão atribuídos ao usuário. O parâmetro `proc` trata-se de um método <b>lambda</b> que disponibilizará como parâmetro a [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do usuário criado para que sejam definidas ações por parte da aplicação. Este método terá como retorno o mesmo retorno do método do parâmetro `proc` se o mesmo for definido, caso contrário retornará a [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) do usuário criado.
460
+
461
+
462
+ ```ruby
463
+ Keycloak::Internal.get_client_roles
464
+ ```
465
+
466
+ `get_client_roles` retornará uma lista (array) de [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) do Client indicado pelo arquivo de instalação `keycloak.json`.
467
+
468
+
469
+ ```ruby
470
+ Keycloak::Internal.get_client_user_roles(user_id)
471
+ ```
472
+
473
+ `get_client_user_roles` invocará o método `Keycloak::Admin.get_effective_client_level_role_composite_user` considerando o Client indicado pelo arquivo de instalação `keycloak.json` e o usuário representado pelo parâmetro `user_id`.
474
+
475
+
476
+ ```ruby
477
+ Keycloak::Internal.has_role?(user_id, user_role)
478
+ ```
479
+
480
+ `has_role?` informará se o usuário representado pelo parâmetro `user_id` possui o <b>role</b> com o nome representado pelo parâmetro `user_role`.
@@ -1,5 +1,5 @@
1
1
  class InitializerGenerator < Rails::Generators::Base
2
- source_root(File.expand_path(File.dirname(__FILE__))
2
+ source_root(File.expand_path(File.dirname(__FILE__)))
3
3
 
4
4
  def copy_initializer
5
5
  copy_file 'keycloak.rb', 'config/initializers/keycloak.rb'
@@ -1,3 +1,3 @@
1
1
  module Keycloak
2
- VERSION = "2.2.4"
2
+ VERSION = "2.2.5"
3
3
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: keycloak
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.2.4
4
+ version: 2.2.5
5
5
  platform: ruby
6
6
  authors:
7
7
  - Guilherme Portugues
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2017-09-19 00:00:00.000000000 Z
11
+ date: 2017-09-21 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: bundler
@@ -108,6 +108,7 @@ files:
108
108
  - Gemfile
109
109
  - LICENSE.txt
110
110
  - README.md
111
+ - README.pt-BR.md
111
112
  - Rakefile
112
113
  - bin/console
113
114
  - bin/setup