keycloak 2.3.0 → 2.3.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/Gemfile.lock +55 -0
- data/README.md +89 -72
- data/README.pt-BR.md +17 -7
- data/lib/keycloak/version.rb +1 -1
- metadata +3 -2
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6f5e81b426ef2ccd31a7278d771cbd5489d777412b5bb5480b0e467847b35bd7
|
|
4
|
+
data.tar.gz: 90e7de6277c9b58402219f4964bb29a12390234ef52073e941489a64ba57d09f
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: eb26009073f1ba875c014d2aacfb0ef952d9c2dbaa4533b33ad059a65c2f953c7610d792d80d200614edca306f0a38ec6f0b38b756cf558e9601bea0029f014c
|
|
7
|
+
data.tar.gz: 3524e51b85b93b154bedc781598216fbe6713c5a7a3b42931dc14b0ee7365053d3b2587f1f736d9e789cd42453f3a35a488fa4eeb365acd97d95fe7313c455c9
|
data/Gemfile.lock
ADDED
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
PATH
|
|
2
|
+
remote: .
|
|
3
|
+
specs:
|
|
4
|
+
keycloak (2.3.1)
|
|
5
|
+
json
|
|
6
|
+
jwt
|
|
7
|
+
rest-client
|
|
8
|
+
|
|
9
|
+
GEM
|
|
10
|
+
remote: https://rubygems.org/
|
|
11
|
+
specs:
|
|
12
|
+
diff-lcs (1.3)
|
|
13
|
+
domain_name (0.5.20170404)
|
|
14
|
+
unf (>= 0.0.5, < 1.0.0)
|
|
15
|
+
http-cookie (1.0.3)
|
|
16
|
+
domain_name (~> 0.5)
|
|
17
|
+
json (2.1.0)
|
|
18
|
+
jwt (2.1.0)
|
|
19
|
+
mime-types (3.1)
|
|
20
|
+
mime-types-data (~> 3.2015)
|
|
21
|
+
mime-types-data (3.2016.0521)
|
|
22
|
+
netrc (0.11.0)
|
|
23
|
+
rake (10.5.0)
|
|
24
|
+
rest-client (2.0.2)
|
|
25
|
+
http-cookie (>= 1.0.2, < 2.0)
|
|
26
|
+
mime-types (>= 1.16, < 4.0)
|
|
27
|
+
netrc (~> 0.8)
|
|
28
|
+
rspec (3.7.0)
|
|
29
|
+
rspec-core (~> 3.7.0)
|
|
30
|
+
rspec-expectations (~> 3.7.0)
|
|
31
|
+
rspec-mocks (~> 3.7.0)
|
|
32
|
+
rspec-core (3.7.1)
|
|
33
|
+
rspec-support (~> 3.7.0)
|
|
34
|
+
rspec-expectations (3.7.0)
|
|
35
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
36
|
+
rspec-support (~> 3.7.0)
|
|
37
|
+
rspec-mocks (3.7.0)
|
|
38
|
+
diff-lcs (>= 1.2.0, < 2.0)
|
|
39
|
+
rspec-support (~> 3.7.0)
|
|
40
|
+
rspec-support (3.7.1)
|
|
41
|
+
unf (0.1.4)
|
|
42
|
+
unf_ext
|
|
43
|
+
unf_ext (0.0.7.5)
|
|
44
|
+
|
|
45
|
+
PLATFORMS
|
|
46
|
+
ruby
|
|
47
|
+
|
|
48
|
+
DEPENDENCIES
|
|
49
|
+
bundler (~> 1.15)
|
|
50
|
+
keycloak!
|
|
51
|
+
rake (~> 10.0)
|
|
52
|
+
rspec (~> 3.0)
|
|
53
|
+
|
|
54
|
+
BUNDLED WITH
|
|
55
|
+
1.16.1
|
data/README.md
CHANGED
|
@@ -1,217 +1,236 @@
|
|
|
1
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
2
|
|
|
4
|
-
|
|
3
|
+
* [pt-BR translation](https://github.com/imagov/keycloak/blob/master/README.pt-BR.md)
|
|
5
4
|
|
|
6
|
-
|
|
5
|
+
Keycloak gem was developed to integrate applications and services into [Red Hat](https://www.redhat.com)'s [Keycloak](http://www.keycloak.org/) system for user control, authentication, authorization, and session management.
|
|
7
6
|
|
|
8
|
-
|
|
7
|
+
Its development was based on version 3.2 of Keycloak, whose documentation can be found [here](http://www.keycloak.org/archive/documentation-3.2.html).
|
|
9
8
|
|
|
10
|
-
|
|
9
|
+
Publication of gem: https://rubygems.org/gems/keycloak
|
|
10
|
+
|
|
11
|
+
## Installation
|
|
12
|
+
|
|
13
|
+
Add this line in your application's <b>gemfile</b>:
|
|
11
14
|
|
|
12
15
|
```ruby
|
|
13
16
|
gem 'keycloak'
|
|
14
17
|
```
|
|
15
18
|
|
|
16
|
-
|
|
19
|
+
Install the gem by running:
|
|
17
20
|
|
|
18
|
-
$ bundle
|
|
21
|
+
$ bundle install
|
|
19
22
|
|
|
20
|
-
|
|
23
|
+
Or install it yourself:
|
|
21
24
|
|
|
22
25
|
$ gem install keycloak
|
|
26
|
+
|
|
27
|
+
To add the configuration file:
|
|
23
28
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
$ rails generate initializer
|
|
29
|
+
$ rails generate initializer
|
|
27
30
|
|
|
28
|
-
|
|
31
|
+
|
|
32
|
+
## Use
|
|
29
33
|
|
|
30
|
-
|
|
34
|
+
Since you already have a Keycloak environment configured and the gem already installed, the next step is to define how the application will authenticate. Keycloak works with key authentication protocols, such as OpenID Connect, Oauth 2.0 and SAML 2.0, integrating system access through Single-Sign On, and can also provide access to <b>LDAP</b> or <b>Active Directory</b> users.
|
|
31
35
|
|
|
32
|
-
|
|
36
|
+
When you register a realm and also a Client in your Keycloak environment, you can download the Client installation file into the root folder of the application so that gem gets the information it needs to interact with Keycloak. To download this, simply access your Client's registry, click the <b>Installation</b> tab, select <b>Keycloak OIDC JSON</b> in the <b>Format option</b> field and click <b>Download</b>. If your application does not only work with a specific client (application server for APIs, for example), then you can tell what is the realm that gem will interact in the `keycloak.rb` configuration file.
|
|
33
37
|
|
|
34
|
-
|
|
38
|
+
Gem has a main module called <b>Keycloak</b>. Within this module there are three other modules: <b>Client</b>, <b>Admin</b> and <b>Internal</b>.
|
|
35
39
|
|
|
36
40
|
### Module Keycloak
|
|
37
41
|
|
|
38
|
-
|
|
42
|
+
The Keycloak module has some attributes and its definitions are fundamental for the perfect functioning of the gem in the application.
|
|
43
|
+
|
|
44
|
+
```ruby
|
|
45
|
+
Keycloak.realm
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
If your application does not only work with a specific client (application server for APIs, for example), then you can tell the realm name that gem will interact in that attribute. When installed, gem creates the `keycloak.rb` file in `config / initializers`. This attribute can be found and defined in this file.
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
```ruby
|
|
52
|
+
Keycloak.auth_server_url
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
For the same scenario as the above attribute, you can tell the url of the realm that the gem will interact in that attribute. When installed, gem creates the `keycloak.rb` file in `config / initializers`. This attribute can be found and defined in this file.
|
|
56
|
+
|
|
39
57
|
|
|
40
58
|
```ruby
|
|
41
59
|
Keycloak.proxy
|
|
42
60
|
```
|
|
43
61
|
|
|
44
|
-
|
|
62
|
+
If the environment where your application will be used requires the use of proxy for the consumption of the Keycloak APIs, then define it in this attribute. When it is installed, gem creates the `keycloak.rb` file in `config/initializers`. This attribute can be found and defined in this file.
|
|
63
|
+
|
|
45
64
|
|
|
46
65
|
```ruby
|
|
47
66
|
Keycloak.generate_request_exception
|
|
48
67
|
```
|
|
49
68
|
|
|
50
|
-
|
|
69
|
+
This attribute is to define whether the HTTP exceptions generated in the returns of the requests made to Keycloak will or will not burst in the application. If set to `false`, then the exception will not be blown and the HTTP response will be returned to the application to do its own processing. The default value of this attribute is `true`. When it is installed, gem creates the `keycloak.rb` file in `config/initializers`. This attribute can be found and defined in this file.
|
|
51
70
|
|
|
52
71
|
|
|
53
72
|
```ruby
|
|
54
73
|
Keycloak.keycloak_controller
|
|
55
74
|
```
|
|
56
75
|
|
|
57
|
-
|
|
76
|
+
It is recommended that your application has a controller that centralizes the session actions that Keycloak will manage, such as login action, logout, session update, password reset, among others. Define in this attribute what is the name of the controller that will play this role. If your controller name is `SessionController`, then the value of this attribute should be `session` only. When it is installed, gem creates the `keycloak.rb` file in `config/initializers`. This attribute can be found and defined in this file.
|
|
58
77
|
|
|
59
78
|
|
|
60
79
|
```ruby
|
|
61
80
|
Keycloak.proc_cookie_token
|
|
62
81
|
```
|
|
63
82
|
|
|
64
|
-
|
|
83
|
+
This attribute is an anonymous method (lambda). The same must be implemented in the application so that the gem has access to the authentication token which, in turn, must be stored in the cookie. When performing the keycloak authentication through gem, the system must store the token returned in the browser cookie, such as:
|
|
65
84
|
```ruby
|
|
66
85
|
cookies.permanent[:keycloak_token] = Keycloak::Client.get_token(params[:user_login], params[:user_password])
|
|
67
86
|
```
|
|
68
|
-
|
|
87
|
+
|
|
88
|
+
The application can retrieve the token in the cookie by implementing the `Keycloak.proc_cookie_token` method as follows:
|
|
69
89
|
```ruby
|
|
70
90
|
Keycloak.proc_cookie_token = -> do
|
|
71
91
|
cookies.permanent[:keycloak_token]
|
|
72
92
|
end
|
|
73
93
|
```
|
|
74
|
-
|
|
94
|
+
This way, every time gem needs to use the token information to consume a Keycloak service, it will invoke this lambda method.
|
|
75
95
|
|
|
76
96
|
|
|
77
97
|
```ruby
|
|
78
98
|
Keycloak.proc_external_attributes
|
|
79
99
|
```
|
|
80
100
|
|
|
81
|
-
|
|
82
|
-
|
|
101
|
+
Keycloak gives the possibility that new attributes are mapped to the user registry. However, when these attributes are application specific, it is recommended that you manage them yourself. To do this, the best solution is to create these attributes in the application - example: create a table in the database of the application itself containing the columns representing each of the attributes, also inserting in this table a unique key column, same as the User Id created in Keycloak, indicating that the one belonging to that Id has those attributes.
|
|
102
|
+
In order for gem to have access to these attributes, set the `Keycloak.proc_external_attributes` attribute to a lambda method by obtaining the attributes of the logged-in user. Example:
|
|
83
103
|
```ruby
|
|
84
104
|
Keycloak.proc_external_attributes = -> do
|
|
85
|
-
|
|
86
|
-
if
|
|
87
|
-
|
|
88
|
-
|
|
105
|
+
attribute = UsuariosAtributo.find_or_create_by(user_keycloak_id: Keycloak::Client.get_attribute('sub'))
|
|
106
|
+
if attribute.status.nil?
|
|
107
|
+
attribute.status = false
|
|
108
|
+
attribute.save
|
|
89
109
|
end
|
|
90
|
-
|
|
110
|
+
attribute
|
|
91
111
|
end
|
|
92
112
|
```
|
|
93
113
|
|
|
94
|
-
<b>Observação:</b> Os atributos `Keycloak.proc_cookie_token` e `Keycloak.proc_external_attributes` podem ser definidos no `initialize` do controller `ApplicationController`.
|
|
95
114
|
|
|
115
|
+
<b>Note:</b> The `Keycloak.proc_cookie_token` and `Keycloak.proc_external_attributes` attributes can be defined in the `initialize` of the controller `ApplicationController`.
|
|
96
116
|
|
|
97
|
-
### Keycloak::Client
|
|
98
117
|
|
|
99
|
-
|
|
118
|
+
### Keycloak::Client
|
|
100
119
|
|
|
101
|
-
|
|
120
|
+
The `Keycloak::Client` module has the methods that represent the <b>endpoint</b> services. These services are fundamental for creating and updating tokens, logging in and logout, and also for obtaining the synthetic information of a logged in user. What enables gem to make use of all these services is the previously mentioned client installation file.
|
|
102
121
|
|
|
122
|
+
We will detail each of these methods:
|
|
103
123
|
|
|
104
124
|
```ruby
|
|
105
125
|
Keycloak::Client.get_token(user, password)
|
|
106
126
|
```
|
|
107
127
|
|
|
108
|
-
|
|
128
|
+
If you choose to authenticate users using the screen of your own application, then use this method. Simply invoke it in the method of login in the `controller` defined with the session controller of your application, passing as parameter the <b>user</b> and the <b>password</b> informed by the user. If the authentication is valid, then a JSON containing the `access_token` and the `refresh_token` is returned.
|
|
109
129
|
|
|
110
130
|
|
|
111
131
|
```ruby
|
|
112
132
|
Keycloak::Client.url_login_redirect(redirect_uri, response_type = 'code')
|
|
113
133
|
```
|
|
114
134
|
|
|
115
|
-
|
|
135
|
+
To authenticate the users of your application using a template configured in Keycloak, redirect the request to the url returned in this method. Pass as a parameter the url that the user will have access in case of successful authentication (`redirect_uri`) and also the type of response (`response_type`), which if not informed, gem will assume the `code` value. If the authentication is successful, then a `code` will be returned that will enable you to request a token from <b>Keycloak</b>.
|
|
116
136
|
|
|
117
137
|
|
|
118
138
|
```ruby
|
|
119
139
|
Keycloak::Client.get_token_by_code(code, redirect_uri)
|
|
120
140
|
```
|
|
121
141
|
|
|
122
|
-
|
|
142
|
+
When using the `Keycloak::Client.url_login_redirect` method to get a `code`, pass it as a parameter in this method so that Keycloak returns a token, thus logging the user in the application. The second parameter (`redirect_uri`) must be passed so that when a token is made available, Keycloak redirects to the url informed.
|
|
123
143
|
|
|
124
144
|
|
|
125
145
|
```ruby
|
|
126
146
|
Keycloak::Client.get_token_by_refresh_token(refresh_token = '')
|
|
127
147
|
```
|
|
128
148
|
|
|
129
|
-
|
|
149
|
+
When the user is already logged in and your application internally tracks the token expiration time provided by Keycloak, then this method can be used to renew that token if it is still valid. To do this, simply pass the `refresh_token` as a parameter. If you do not inform `refresh_token`, gem will use the `refresh_token` stored in the cookie.
|
|
130
150
|
|
|
131
151
|
|
|
132
152
|
```ruby
|
|
133
153
|
Keycloak::Client.get_token_introspection(token = '')
|
|
134
154
|
```
|
|
135
155
|
|
|
136
|
-
|
|
156
|
+
This method returns the information from the `token` session passed as parameter. Among the information returned, the most important is the `active` field, since it informs whether the token session passed in the parameter is active or not. This will help your application control whether the logged-in user session has expired or not. If no token is passed as a parameter, gem will use the last `access_token` stored in the application's cookie.
|
|
137
157
|
|
|
138
158
|
|
|
139
159
|
```ruby
|
|
140
160
|
Keycloak::Client.get_token_by_client_credentials(client_id = '', secret = '')
|
|
141
161
|
```
|
|
142
162
|
|
|
143
|
-
|
|
163
|
+
There are some Keycloak services like <b>password reset</b>, <b>user registration</b> in the initial screen of the application or even authentication following the standard <b>OAuth 2.0</b>, that the authentication of a user becomes unnecessary. Therefore, we can obtain a token using the credentials of its own application (Client) registered in Keycloak. To obtain this token, pass the `client_id` - informed by the person who registered your application in Keycloak - and the `secret` of your application generated by Keycloak - to generate a `secret`, the Access Type of your Client must be configured as `confidential`. If you do not pass any of these parameters, gem will use the credentials contained in the installation file mentioned above.
|
|
144
164
|
|
|
145
165
|
|
|
146
166
|
```ruby
|
|
147
167
|
Keycloak::Client.logout(redirect_uri = '', refresh_token = '')
|
|
148
168
|
```
|
|
149
169
|
|
|
150
|
-
|
|
170
|
+
When used before the expiration of the logged on user's session, this method terminates the session. If the `redirect_uri` parameter is fed, then Keycloak will redirect your application to the url informed after logout. The second parameter is `refresh_token`, obtained at the time of authentication or session update. If the latter is not informed, then the gem will use the `refresh_token` of the cookie
|
|
151
171
|
|
|
152
172
|
|
|
153
173
|
```ruby
|
|
154
174
|
Keycloak::Client.get_userinfo(access_token = '')
|
|
155
175
|
```
|
|
156
176
|
|
|
157
|
-
|
|
177
|
+
This method returns synthetic information from the user represented by the `access_token` passed as a parameter, such as `sub` - which is the authenticated user id -, `preferred_username` - which is the authenticated user name - and `email` - which is the user's email address. If the `access_token` parameter is not informed, then the gem will get this information in the cookie.
|
|
158
178
|
|
|
159
179
|
|
|
160
180
|
```ruby
|
|
161
181
|
Keycloak::Client.url_user_account
|
|
162
182
|
```
|
|
163
183
|
|
|
164
|
-
|
|
184
|
+
Returns the <b>url</b> for access to the realm user registry of the installation file (`keycloak.json`). To access the screen, Keycloak will require user authentication. After connected, and if has permission, the user will have access to his own personal information and could even change them.
|
|
165
185
|
|
|
166
186
|
|
|
167
187
|
```ruby
|
|
168
188
|
Keycloak::Client.has_role?(user_role, access_token = '')
|
|
169
189
|
```
|
|
170
190
|
|
|
171
|
-
|
|
191
|
+
The `has_role?` method decodes the JWT `access_token` and verifies that the user who owns the token has the <b>role</b> informed in the `user_role` parameter. If `access_token` is not informed then gem will use the `access_token` of the cookie.
|
|
172
192
|
|
|
173
193
|
|
|
174
194
|
```ruby
|
|
175
195
|
Keycloak::Client.user_signed_in?(access_token = '')
|
|
176
196
|
```
|
|
177
197
|
|
|
178
|
-
|
|
198
|
+
This method checks whether the `access_token` passed in the parameter is still active. To check whether the user is active or not, the gem invokes the `get_token_introspection` method internally. If `access_token` is not informed then gem will use the `access_token` of the cookie.
|
|
179
199
|
|
|
180
200
|
|
|
181
201
|
```ruby
|
|
182
202
|
Keycloak::Client.get_attribute(attribute_name, access_token = '')
|
|
183
203
|
```
|
|
184
204
|
|
|
185
|
-
|
|
205
|
+
This method decodes the JWT `access_token` and returns the value of the name attribute passed in the `attribute_name` parameter. This attribute can be a <b>mapper</b> - registered in the <b>Mappers</b> section of the Realm <b>Client</b> registry. If `access_token` is not informed then gem will use the `access_token` of the cookie.
|
|
186
206
|
|
|
187
207
|
|
|
188
208
|
```ruby
|
|
189
209
|
Keycloak::Client.token
|
|
190
210
|
```
|
|
191
211
|
|
|
192
|
-
|
|
212
|
+
Returns the last authenticated token stored in the cookie. When the `Keycloak.proc_cookie_token` method is implemented in the application and a user authenticates the application, this method returns the token of that user.
|
|
193
213
|
|
|
194
214
|
|
|
195
215
|
```ruby
|
|
196
216
|
Keycloak::Client.external_attributes
|
|
197
217
|
```
|
|
198
218
|
|
|
199
|
-
|
|
219
|
+
When the `Keycloak.proc_external_attributes` method is implemented, the `external_attributes` method returns it. The purpose of this method is to return the application-specific attributes not mapped in Keycloak.
|
|
200
220
|
|
|
201
221
|
|
|
202
222
|
### Keycloak::Admin
|
|
203
223
|
|
|
204
|
-
|
|
205
|
-
|
|
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`:
|
|
224
|
+
The `Keycloak :: Admin` module provides methods that represent the [REST APIs do Keycloak](http://www.keycloak.org/docs-api/3.2/rest-api/index.html). In order to use these APIs, an active `access_token` is required, that is, authentication must occur before using the methods for a valid token to be used as a credential. If `access_token` is not informed then gem will use the `access_token` of the cookie. The authenticated user must have the `role` of the respective service invoked - roles of the `realm-management` client, which represents the management of the realm.
|
|
207
225
|
|
|
226
|
+
The list of methods is shown below. The `{realm}` route parameter of all APIs will be obtained from the `keycloak.json` installation file:
|
|
208
227
|
|
|
209
228
|
```ruby
|
|
210
229
|
# GET /admin/realms/{realm}/users
|
|
211
230
|
Keycloak::Admin.get_users(query_parameters = nil, access_token = nil)
|
|
212
231
|
```
|
|
213
232
|
|
|
214
|
-
`get_users`
|
|
233
|
+
`get_users` returns a list of users, filtered according to the parameters <b>hash</b> passed in` query_parameters`.
|
|
215
234
|
|
|
216
235
|
|
|
217
236
|
```ruby
|
|
@@ -219,15 +238,14 @@ Keycloak::Admin.get_users(query_parameters = nil, access_token = nil)
|
|
|
219
238
|
Keycloak::Admin.create_user(user_representation, access_token = nil)
|
|
220
239
|
```
|
|
221
240
|
|
|
222
|
-
`create_user`
|
|
241
|
+
`create_user` creates a new user in Keycloak. The `user_representation` parameter must be a hash according to Keycloak [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation). The return of this method will be `true` for success.
|
|
223
242
|
|
|
224
243
|
|
|
225
244
|
```ruby
|
|
226
245
|
# GET /admin/realms/{realm}/users/count
|
|
227
246
|
Keycloak::Admin.count_users(access_token = nil)
|
|
228
247
|
```
|
|
229
|
-
|
|
230
|
-
`count_users` retorna a quantidade de usuários do reino.
|
|
248
|
+
`count_users` returns the number of users in the realm.
|
|
231
249
|
|
|
232
250
|
|
|
233
251
|
```ruby
|
|
@@ -235,7 +253,7 @@ Keycloak::Admin.count_users(access_token = nil)
|
|
|
235
253
|
Keycloak::Admin.get_user(id, access_token = nil)
|
|
236
254
|
```
|
|
237
255
|
|
|
238
|
-
`get_user`
|
|
256
|
+
`get_user` returns the user representation identified by the `id` parameter - which is the <b>ID</b> created by Keycloak when creating a new user.
|
|
239
257
|
|
|
240
258
|
|
|
241
259
|
```ruby
|
|
@@ -243,7 +261,7 @@ Keycloak::Admin.get_user(id, access_token = nil)
|
|
|
243
261
|
Keycloak::Admin.update_user(id, user_representation, access_token = nil)
|
|
244
262
|
```
|
|
245
263
|
|
|
246
|
-
`update_user`
|
|
264
|
+
`update_user` updates the user registry identified by `id` - which is the <b>ID</b> created by Keycloak when creating a new user. In the `user_representation` parameter should be a hash with the fields that will be changed, respecting the [UserRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_userrepresentation) of Keycloak. The return of this method will be `true` for success.
|
|
247
265
|
|
|
248
266
|
|
|
249
267
|
```ruby
|
|
@@ -251,7 +269,7 @@ Keycloak::Admin.update_user(id, user_representation, access_token = nil)
|
|
|
251
269
|
Keycloak::Admin.delete_user(id, access_token = nil)
|
|
252
270
|
```
|
|
253
271
|
|
|
254
|
-
`delete_user`
|
|
272
|
+
`delete_user` excludes the user ID identified by the `id` - which is the <b>ID</b> created by Keycloak when creating a new user. The return of this method will be `true` for success.
|
|
255
273
|
|
|
256
274
|
|
|
257
275
|
```ruby
|
|
@@ -259,7 +277,7 @@ Keycloak::Admin.delete_user(id, access_token = nil)
|
|
|
259
277
|
Keycloak::Admin.revoke_consent_user(id, client_id = nil, access_token = nil)
|
|
260
278
|
```
|
|
261
279
|
|
|
262
|
-
`revoke_consent_user`
|
|
280
|
+
`revoke_consent_user` revokes the tokens of a user identified by `id` - which is the <b>ID</b> created by Keycloak when creating a new user - on the client identified by the `client_id` parameter.
|
|
263
281
|
|
|
264
282
|
|
|
265
283
|
```ruby
|
|
@@ -267,7 +285,7 @@ Keycloak::Admin.revoke_consent_user(id, client_id = nil, access_token = nil)
|
|
|
267
285
|
Keycloak::Admin.update_account_email(id, actions, redirect_uri = '', client_id = nil, access_token = nil)
|
|
268
286
|
```
|
|
269
287
|
|
|
270
|
-
`update_account_email`
|
|
288
|
+
`update_account_email` sends an account update email to the user represented by the `id` parameter. The email contains a link that the user can click to execute a set of actions represented by the `actions` parameter - which awaits an `array` of [actions defined by Keycloak](http://www.keycloak.org/docs/3.2/server_admin/topics/users/required-actions.html). An example value that can be passed to the `actions` parameter is `['UPDATE_PASSWORD']`, which indicates that the action that the user must take when clicking the link in the email is to change their password. In the `redirect_uri` parameter, if necessary, a url must be passed so that, at the end of sending the e-mail, the application is redirected. The `client_id` parameter should be informed if the Client responsible for the actions to be performed is not the same as the `keycloak.json` installation file.
|
|
271
289
|
|
|
272
290
|
|
|
273
291
|
```ruby
|
|
@@ -275,7 +293,7 @@ Keycloak::Admin.update_account_email(id, actions, redirect_uri = '', client_id =
|
|
|
275
293
|
Keycloak::Admin.get_role_mappings(id, access_token = nil)
|
|
276
294
|
```
|
|
277
295
|
|
|
278
|
-
`get_role_mappings`
|
|
296
|
+
`get_role_mappings` returns all <b>Role Mappings</b> in the realm assigned to the user identified by the `id` parameter, regardless of the Client.
|
|
279
297
|
|
|
280
298
|
|
|
281
299
|
```ruby
|
|
@@ -283,7 +301,7 @@ Keycloak::Admin.get_role_mappings(id, access_token = nil)
|
|
|
283
301
|
Keycloak::Admin.get_clients(query_parameters = nil, access_token = nil)
|
|
284
302
|
```
|
|
285
303
|
|
|
286
|
-
`get_clients`
|
|
304
|
+
`get_clients` returns a list of [ClientRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_clientrepresentation) pertaining to the realm. The `query_parameters` parameter expects a hash with `clientId` attributes - if you want the list to be filtered by `client_id` - and `viewableOnly` - to filter whether the Keycloak Administration Clients will be returned in the list.
|
|
287
305
|
|
|
288
306
|
|
|
289
307
|
```ruby
|
|
@@ -291,7 +309,7 @@ Keycloak::Admin.get_clients(query_parameters = nil, access_token = nil)
|
|
|
291
309
|
Keycloak::Admin.get_all_roles_client(id, access_token = nil)
|
|
292
310
|
```
|
|
293
311
|
|
|
294
|
-
`get_all_roles_client`
|
|
312
|
+
`get_all_roles_client` returns a [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) list with all client <b>roles</b> identified by the `id` parameter - this parameter must be passed in the ID of the Clint and not `client_id`.
|
|
295
313
|
|
|
296
314
|
|
|
297
315
|
```ruby
|
|
@@ -299,7 +317,7 @@ Keycloak::Admin.get_all_roles_client(id, access_token = nil)
|
|
|
299
317
|
Keycloak::Admin.get_roles_client_by_name(id, role_name, access_token = nil)
|
|
300
318
|
```
|
|
301
319
|
|
|
302
|
-
`get_roles_client_by_name`
|
|
320
|
+
`get_roles_client_by_name` returns the [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) of the role identified by the parameter `role_name` - which is the name of the role.
|
|
303
321
|
|
|
304
322
|
|
|
305
323
|
```ruby
|
|
@@ -307,7 +325,7 @@ Keycloak::Admin.get_roles_client_by_name(id, role_name, access_token = nil)
|
|
|
307
325
|
Keycloak::Admin.add_client_level_roles_to_user(id, client, role_representation, access_token = nil)
|
|
308
326
|
```
|
|
309
327
|
|
|
310
|
-
`add_client_level_roles_to_user`
|
|
328
|
+
`add_client_level_roles_to_user` inserts a <b>role</b> from the Client (represented by the `client` parameter) to the user represented by the `id` parameter. The `role_representation` parameter should receive an `array` of [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) that will be entered into the user. On success, the return will be `true`.
|
|
311
329
|
|
|
312
330
|
|
|
313
331
|
```ruby
|
|
@@ -315,7 +333,7 @@ Keycloak::Admin.add_client_level_roles_to_user(id, client, role_representation,
|
|
|
315
333
|
Keycloak::Admin.delete_client_level_roles_from_user(id, client, role_representation, access_token = nil)
|
|
316
334
|
```
|
|
317
335
|
|
|
318
|
-
`delete_client_level_roles_from_user`
|
|
336
|
+
`delete_client_level_roles_from_user` deletes a <b>Client-Role</b> (representado pelo parâmetro `client`) of the user represented by the `id` parameter. The `role_representation` parameter should receive an `array` of [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) that will be removed on the user. On success, the return will be `true`.
|
|
319
337
|
|
|
320
338
|
|
|
321
339
|
```ruby
|
|
@@ -323,14 +341,14 @@ Keycloak::Admin.delete_client_level_roles_from_user(id, client, role_representat
|
|
|
323
341
|
Keycloak::Admin.get_client_level_role_for_user_and_app(id, client, access_token = nil)
|
|
324
342
|
```
|
|
325
343
|
|
|
326
|
-
`get_client_level_role_for_user_and_app`
|
|
344
|
+
`get_client_level_role_for_user_and_app` return a list of [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) of client <b>Client-Roles</b>, represented by `client` parameter linked to the user represented by the `id` parameter.
|
|
327
345
|
|
|
328
346
|
|
|
329
347
|
```ruby
|
|
330
348
|
Keycloak::Admin.update_effective_user_roles(id, client_id, roles_names, access_token = nil)
|
|
331
349
|
```
|
|
332
350
|
|
|
333
|
-
`update_effective_user_roles`
|
|
351
|
+
`update_effective_user_roles` is not on the Keycloak <b>Admin APIs</b> list. This method binds to the user represented by the `id` parameter all the roles passed in an` array` in the `roles_names` parameter. The roles passed in the `roles_names` parameter must belong to the Client represented by the` client_id` parameter. If the user has the link with a role that is not in the `roles_names` parameter, this link will be removed because the purpose of this method is for the user to effectively assume the roles passed in this parameter. On success, the return will be `true`.
|
|
334
352
|
|
|
335
353
|
|
|
336
354
|
```ruby
|
|
@@ -338,7 +356,7 @@ PUT /admin/realms/{realm}/users/{id}/reset-password
|
|
|
338
356
|
Keycloak::Admin.reset_password(id, credential_representation, access_token = nil)
|
|
339
357
|
```
|
|
340
358
|
|
|
341
|
-
`reset_password`
|
|
359
|
+
`reset_password` change the user password represented by `id` parameter. The new password is represented by `credential_representation` parameter, which is a set of information formatted under the [CredentialRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_credentialrepresentation) section of the Keycloak API manual.
|
|
342
360
|
|
|
343
361
|
|
|
344
362
|
```ruby
|
|
@@ -346,12 +364,12 @@ GET /admin/realms/{realm}/groups/{id}/role-mappings/clients/{client}/composite
|
|
|
346
364
|
Keycloak::Admin.get_effective_client_level_role_composite_user(id, client, access_token = nil)
|
|
347
365
|
```
|
|
348
366
|
|
|
349
|
-
`get_effective_client_level_role_composite_user`
|
|
367
|
+
`get_effective_client_level_role_composite_user` return a list (array) of [RoleRepresentation](http://www.keycloak.org/docs-api/3.2/rest-api/index.html#_rolerepresentation) of a <b>Group</b> represented by `id` parameter attached to a <b>Client</b> represented by `client` parameter.
|
|
350
368
|
|
|
351
369
|
|
|
352
|
-
|
|
370
|
+
If there is any service in the manual [Keycloak Admin REST API](http://www.keycloak.org/docs-api/3.2/rest-api/index.html) that has not been implemented in this gem, there is a possibility of being invoked using the <b>Generics Methods</b> of the `Keycloak::Admin` model. The <b>Generics Methods</b> allow you to request any of the APIs, either `GET`,` POST`, `PUT` or` DELETE`, passing the request parameters as `hashes` in the parameters` query_parameters` and `body_parameter` of the <b>Generics Methods</b>.
|
|
353
371
|
<br>
|
|
354
|
-
|
|
372
|
+
The following are the <b>Generics Methods</b>:
|
|
355
373
|
<br>
|
|
356
374
|
|
|
357
375
|
```ruby
|
|
@@ -365,7 +383,6 @@ Exemplo:
|
|
|
365
383
|
```
|
|
366
384
|
|
|
367
385
|
|
|
368
|
-
|
|
369
386
|
```ruby
|
|
370
387
|
Keycloak::Admin.generic_post(service, query_parameters, body_parameter, access_token = nil)
|
|
371
388
|
```
|
data/README.pt-BR.md
CHANGED
|
@@ -21,10 +21,6 @@ Ou instale você mesmo:
|
|
|
21
21
|
|
|
22
22
|
$ gem install keycloak
|
|
23
23
|
|
|
24
|
-
To add the configuration file:
|
|
25
|
-
|
|
26
|
-
$ rails generate initializer
|
|
27
|
-
|
|
28
24
|
Para adicionar o arquivo de configuração:
|
|
29
25
|
|
|
30
26
|
$ rails generate initializer
|
|
@@ -45,14 +41,14 @@ O módulo Keycloak possui alguns atributos e suas definições são fundamentais
|
|
|
45
41
|
Keycloak.realm
|
|
46
42
|
```
|
|
47
43
|
|
|
48
|
-
Se a sua aplicação não trabalha apenas com um client específico (aplicação servidora de APIs, por exemplo), então você poderá informar o nome reino que a gem irá interagir nesse atributo. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
|
|
44
|
+
Se a sua aplicação não trabalha apenas com um client específico (aplicação servidora de APIs, por exemplo), então você poderá informar o nome do reino que a gem irá interagir nesse atributo. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
|
|
49
45
|
|
|
50
46
|
|
|
51
47
|
```ruby
|
|
52
48
|
Keycloak.auth_server_url
|
|
53
49
|
```
|
|
54
50
|
|
|
55
|
-
Para o mesmo cenário do atributo acima, você poderá informar a url reino que a gem irá interagir nesse atributo. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
|
|
51
|
+
Para o mesmo cenário do atributo acima, você poderá informar a url do reino que a gem irá interagir nesse atributo. Ao ser instalada, a gem cria o arquivo `keycloak.rb` em `config/initializers`. Este atributo pode ser encontrado e definido nesse arquivo.
|
|
56
52
|
|
|
57
53
|
|
|
58
54
|
```ruby
|
|
@@ -140,6 +136,20 @@ Keycloak::Client.get_token_by_code(code, redirect_uri)
|
|
|
140
136
|
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.
|
|
141
137
|
|
|
142
138
|
|
|
139
|
+
```ruby
|
|
140
|
+
Keycloak::Client.get_token_by_exchange(issuer, issuer_token)
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Para obter um token através de um token obtido anteriormente de um provedor confiável (padrão OpenID), como Facebook, Gooble, Twitter, ou até mesmo outro reino configurado no keycloak, basta invocar este método, passando no parâmetro `issuer` o alias do provedor configurado no reino, e, no parâmetro `issuer_token` o token obtido por esse provedor. Com isso, será retornado um token autenticado pelo teu reino.
|
|
144
|
+
|
|
145
|
+
|
|
146
|
+
```ruby
|
|
147
|
+
Keycloak::Client.get_userinfo_issuer(access_token = '')
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Esse método retorna as informações do usuário de um provevedor (`issuer` do método `get_token_by_exchange`) representado pelo `access_token` passado como parâmetro. Caso o parâmetro `access_token` não seja informado, então a gem obterá essa informação no cookie.
|
|
151
|
+
|
|
152
|
+
|
|
143
153
|
```ruby
|
|
144
154
|
Keycloak::Client.get_token_by_refresh_token(refresh_token = '')
|
|
145
155
|
```
|
|
@@ -367,7 +377,7 @@ Keycloak::Admin.get_effective_client_level_role_composite_user(id, client, acces
|
|
|
367
377
|
`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`.
|
|
368
378
|
|
|
369
379
|
|
|
370
|
-
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
|
|
380
|
+
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 model `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>.
|
|
371
381
|
<br>
|
|
372
382
|
Veja a seguir os <b>Generics Methods</b>:
|
|
373
383
|
<br>
|
data/lib/keycloak/version.rb
CHANGED
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.3.
|
|
4
|
+
version: 2.3.1
|
|
5
5
|
platform: ruby
|
|
6
6
|
authors:
|
|
7
7
|
- Guilherme Portugues
|
|
8
8
|
autorequire:
|
|
9
9
|
bindir: exe
|
|
10
10
|
cert_chain: []
|
|
11
|
-
date: 2018-
|
|
11
|
+
date: 2018-03-05 00:00:00.000000000 Z
|
|
12
12
|
dependencies:
|
|
13
13
|
- !ruby/object:Gem::Dependency
|
|
14
14
|
name: bundler
|
|
@@ -107,6 +107,7 @@ files:
|
|
|
107
107
|
- ".vscode/launch.json"
|
|
108
108
|
- CODE_OF_CONDUCT.md
|
|
109
109
|
- Gemfile
|
|
110
|
+
- Gemfile.lock
|
|
110
111
|
- LICENSE.txt
|
|
111
112
|
- README.md
|
|
112
113
|
- README.pt-BR.md
|