Skip to content

Commit c22e5d7

Browse files
RichardJJGRichardJJG
authored
Merge pull request #2185 from rabbitmq/issue-12324
Support keycloak custom format via configuration
2 parents 2d35134 + 5383aef commit c22e5d7

File tree

2 files changed

+292
-60
lines changed

2 files changed

+292
-60
lines changed

‎docs/oauth2-examples-keycloak.md‎

Lines changed: 134 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -19,83 +19,174 @@ See the License for the specific language governing permissions and
1919
limitations under the License.
2020
-->
2121

22-
# Use Keycloak as OAuth 2.0 server
22+
## Use Keycloak as OAuth 2.0 server
2323

24-
This guide explains how to set up OAuth 2.0 for RabbitMQ
25-
and Keycloak as Authorization Server using the following flows:
24+
This guide explains how to set up OAuth 2.0 for RabbitMQ and Keycloak as Authorization Server using
25+
the following flows:
2626

2727
* Access [management UI](./management/) via a browser
2828
* Access management HTTP API
2929
* Application authentication and authorization
3030

31+
## Keycloak JWT payloads
32+
33+
Keycloak can issue two types of JWT payloads.
34+
35+
One type of payload is found in a [Requesting Party Token](./oauth2#requesting-party-token).
36+
RabbitMQ supports this type of token and it extracts the scopes from it. You do not need to
37+
configure anything.
38+
39+
The second type of payload is the following:
40+
41+
```json
42+
{
43+
"realm_access": {
44+
"roles": [
45+
"offline_access",
46+
"uma_authorization",
47+
"rabbitmq.tag:management",
48+
]
49+
},
50+
"resource_access": {
51+
"account": {
52+
"roles": [
53+
"manage-account",
54+
"manage-account-links",
55+
"view-profile",
56+
"rabbitmq.write:*/*"
57+
]
58+
}
59+
},
60+
"roles": "rabbitmq.read:*/*",
61+
"scope": "profile email"
62+
}
63+
```
64+
65+
:::info
66+
The claim `roles` is not, strictly speaking, part of Keycloak official claims. Instead, it is a
67+
custom claim configured by the user from the Keycloak administration console.
68+
:::
69+
70+
RabbitMQ does not read the scopes from this token unless you configure it to do so. For example, to
71+
configure RabbitMQ to extract the scopes from `roles` under the `realm_access` claim, add the
72+
following configuration variable:
73+
74+
```json
75+
auth_oauth2.additional_scopes_key = realm_access.roles
76+
```
77+
78+
To configure RabbitMQ to also read from `resource_access` claim, edit the previous configuration as
79+
follows:
80+
81+
```json
82+
auth_oauth2.additional_scopes_key = realm_access.roles resource_access.account.roles
83+
```
84+
85+
And finally, if you also want to use the scopes in the claim `roles`, you edit the previous
86+
configuration:
87+
88+
```json
89+
auth_oauth2.additional_scopes_key = roles realm_access.roles resource_access.account.roles
90+
```
91+
92+
RabbitMQ reads the scopes from all those sources.
93+
3194
## Prerequisites to follow this guide
3295

3396
* Docker
3497
* make
35-
* A local clone of a [GitHub repository](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next) for branch `next` that contains all the configuration files and scripts used on this example
98+
* A local clone of a
99+
[GitHub repository](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next) for branch
100+
`next` that contains all the configuration files and scripts used on this example
36101
* Add the following entry to `/etc/hosts`:
37-
```
38-
localhost keycloak rabbitmq
39-
```
102+
103+
```console
104+
localhost keycloak rabbitmq
105+
```
40106

41107
## Deploy Keycloak
42108

43-
1. First, deploy **Keycloak**. It comes preconfigured with all the required scopes, users and clients.
109+
1. First, deploy Keycloak. It comes preconfigured with all the required scopes, users, and clients.
44110

45-
2. Run the following command to start **Keycloak** server:
111+
2. Start the Keycloak server by running:
46112

47-
```bash
48-
make start-keycloak
49-
```
113+
```bash
114+
make start-keycloak
115+
```
50116

51-
There is a dedicated **Keycloak realm** called `Test` configured as follows:
117+
There is a dedicated Keycloak realm called `Test` configured as follows:
52118

53-
* A [rsa](https://keycloak:8443/admin/master/console/#/test/realm-settings/keys) signing key. Use `admin`:`admin`
54-
when prompted for credentials to access the Keycloak Administration page
119+
* A [rsa](https://keycloak:8443/admin/master/console/#/test/realm-settings/keys) signing key. Use
120+
`admin`:`admin` when prompted for credentials to access the Keycloak Administration page
55121
* A [rsa provider](https://keycloak:8443/admin/master/console/#/test/realm-settings/keys/providers)
56-
* Three clients: `rabbitmq-client-code` for the rabbitmq management UI, `mgt_api_client` to access via the
57-
management api and `producer` to access via AMQP protocol.
58-
122+
* Three clients: `rabbitmq-client-code` for the RabbitMQ management UI, `mgt_api_client` to access
123+
via the management API and `producer` to access via the AMQP protocol.
59124

60125
## Start RabbitMQ
61126

62-
Run the command below to start RabbitMQ configured with the **Keycloak** server we started in the previous section: This is the [rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/keycloak/rabbitmq.conf) used for **Keycloak**.
127+
Run the command below to start RabbitMQ configured with the `Keycloak` server we started in the
128+
previous section: This is the
129+
[rabbitmq.conf](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/keycloak/rabbitmq.conf)
130+
used for Keycloak.
131+
63132
```bash
64133
export MODE=keycloak
65134
make start-rabbitmq
66135
```
67136

68137
:::info
69-
RabbitMQ is deployed with TLS enabled and Keycloak is configured with the corresponding `redirect_url` which uses https.
138+
RabbitMQ is deployed with TLS enabled and Keycloak is configured with the corresponding `redirect_url`
139+
which uses HTTPS.
140+
:::
141+
142+
:::important
143+
RabbitMQ is configured to read the scopes from the custom claim
144+
[extra_scope](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/blob/next/conf/keycloak/rabbitmq.conf#L11)
145+
and by default from the standard claim `scope`.
146+
However, if your scopes are deep in a map/list structure such as `authorization.permissions.scopes`,
147+
or under `realm_access.roles` or `resource_access.account.roles`, you can configure RabbitMQ to use
148+
those locations instead. For more information, see the section
149+
[Use a different token field for the scope](./oauth2#use-different-token-field).
70150
:::
71151

72-
## Access Management api
152+
## Access Management API
73153

74-
To access the management api run the following command. It uses the client [mgt_api_client](https://keycloak:8443/admin/master/console/#/test/clients/c5be3c24-0c88-4672-a77a-79002fcc9a9d/settings) which has the scope [rabbitmq.tag:administrator](https://keycloak:8443/admin/master/console/#/test/client-scopes/f6e6dd62-22bf-4421-910e-e6070908764c/settings).
154+
To access the management api run the following command. It uses the client
155+
[mgt_api_client](https://keycloak:8443/admin/master/console/#/test/clients/c5be3c24-0c88-4672-a77a-79002fcc9a9d/settings)
156+
that has the scope
157+
[rabbitmq.tag:administrator](https://keycloak:8443/admin/master/console/#/test/client-scopes/f6e6dd62-22bf-4421-910e-e6070908764c/settings).
75158

76159
```bash
77160
make curl-keycloak url=https://localhost:15671/api/overview client_id=mgt_api_client secret=LWOuYqJ8gjKg3D2U8CJZDuID3KiRZVDa realm=test
78161
```
79162

80163
## Application authentication and authorization with PerfTest
81164

82-
To test OAuth 2.0 authentication with AMQP protocol you are going to use RabbitMQ PerfTest tool which uses RabbitMQ Java Client.
165+
To test OAuth 2.0 authentication with the AMQP protocol you use the RabbitMQ PerfTest tool, which
166+
uses RabbitMQ Java Client.
83167

84-
First you obtain the token and pass it as a parameter to the make target `start-perftest-producer-with-token`.
168+
First you obtain the token and pass it as a parameter to the make target
169+
`start-perftest-producer-with-token`.
85170

86171
```bash
87172
make start-perftest-producer-with-token PRODUCER=producer TOKEN=$(bin/keycloak/token producer kbOFBXI9tANgKUq8vXHLhT6YhbivgXxn test)
88173
```
89174

90-
**NOTE**: Initializing an application with a token has one drawback: the application cannot use the connection beyond the lifespan of the token. See the next section where you demonstrate how to refresh the token.
175+
:::info
176+
Initializing an application with a token has one drawback: the application cannot use the connection
177+
beyond the lifespan of the token. See the next section where you demonstrate how to refresh the token.
178+
:::
91179

92180
## Application authentication and authorization with Pika
93181

94-
In the following information, OAuth 2.0 authentication is tested with the AMQP protocol and the Pika library. These tests specifically demonstrate how to refresh a token on a live AMQP connection.
182+
In the following information, OAuth 2.0 authentication is tested with the AMQP protocol and the Pika
183+
library. These tests specifically demonstrate how to refresh a token on a live AMQP connection.
95184

96-
The sample Python application [can be found on GitHub](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/pika-client).
185+
The sample Python application is
186+
[in GitHub](https://github.com/rabbitmq/rabbitmq-oauth2-tutorial/tree/next/pika-client).
97187

98188
To run this sample code proceed as follows:
189+
99190
```bash
100191
python3 --version
101192
pip install pika
@@ -111,40 +202,42 @@ source venv/bin/activate
111202
```
112203
:::
113204

114-
Note: Ensure you install pika 1.3
205+
:::important
206+
Ensure that you install pika 1.3.
207+
:::
115208

116209
## Access [management UI](./management/)
117210

118211
1. Go to https://localhost:15671.
119-
2. Click on the single button on the page which redirects to **Keycloak** to authenticate.
120-
3. Enter `rabbit_admin` and `rabbit_admin` and you should be redirected back to RabbitMQ Management fully logged in.
212+
2. Click on the single button on the page which redirects to Keycloak to authenticate.
213+
3. Enter `rabbit_admin` and `rabbit_admin` and you should be redirected back to RabbitMQ Management
214+
fully logged in.
121215

122-
123-
## Stop keycloak
216+
## Stop Keycloak
124217

125218
```bash
126219
make stop-keycloak
127220
```
128221

129222
## Notes about setting up Keycloak
130223

131-
### Configure Client
224+
### Configure client
132225

133226
For backend applications which uses **Client Credentials flow**, you can create a **Client** with:
134227

135-
* **Access Type** : `public`
228+
* **Access Type**: `public`
136229
* Turn off `Standard Flow`, `Implicit Flow`, and `Direct Access Grants`
137230
* With **Service Accounts Enabled** on. If it is not enabled you do not have the tab `Credentials`
138231
* In the `Credentials` tab, you have the `client id`
139232

233+
### Configure client scopes
140234

141-
### Configure Client scopes
142-
143-
*Default Client Scope* are scopes automatically granted to every token. Whereas *Optional Client Scope* are
144-
scopes which are only granted if they are explicitly requested during the authorization/token request flow.
145-
235+
*Default Client Scope* are scopes automatically granted to every token. Whereas
236+
*Optional Client Scope* are scopes which are only granted if they are explicitly requested during
237+
the authorization/token request flow.
146238

147239
### Include appropriate aud claim
148240

149-
You must configure a **Token Mapper** of type **Hardcoded claim** with the value of rabbitmq's *resource_server_id**.
150-
You can configure **Token Mapper** either to a **Client scope** or to a **Client**.
241+
You must configure a **Token Mapper** of type **Hardcoded claim** with the value of RabbitMQ's
242+
`resource_server_id`. You can configure **Token Mapper** either to a **Client scope** or to a
243+
**Client**.

0 commit comments

Comments
 (0)