1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
|
# RabbitMQ Access Control Cache Plugin
This plugin provides a caching layer for [access control operations](https://rabbitmq.com/access-control.html)
performed by RabbitMQ nodes.
## Project Maturity
As of 3.7.0, this plugin is distributed with RabbitMQ.
## Overview
This plugin provides a way to cache [authentication and authorization backend](https://rabbitmq.com/access-control.html)
results for a configurable amount of time.
It's not an independent auth backend but a caching layer for existing backends
such as the built-in, [LDAP](https://github.com/rabbitmq/rabbitmq-auth-backend-ldap), or [HTTP](https://github.com/rabbitmq/rabbitmq-auth-backend-http)
ones.
Cache expiration is currently time-based. It is not very useful with the built-in
(internal) [authn/authz backends](https://rabbitmq.com/access-control.html) but can be very useful for LDAP, HTTP or other backends that
use network requests.
## RabbitMQ Version Requirements
As of 3.7.0, this plugin is distributed with RabbitMQ. Like any other plugin, it must
be [enabled](https://www.rabbitmq.com/plugins.html#ways-to-enable-plugins) before it can be used.
## Installation
This plugin ships with reasonably recent RabbitMQ versions
(e.g. `3.7.0` or later). Enable it with
``` shell
rabbitmq-plugins enable rabbitmq_auth_backend_cache
```
## Binary Builds
Binary builds can be obtained [from project releases](https://github.com/rabbitmq/rabbitmq-auth-backend-cache/releases/) on GitHub.
## Building
You can build and install it like any other plugin (see
[the plugin development guide](https://www.rabbitmq.com/plugin-development.html)).
## Authentication and Authorization Backend Configuration
To enable the plugin, set the value of the `auth_backends` configuration item
for the `rabbit` application to include `rabbit_auth_backend_cache`.
`auth_backends` is a list of authentication providers to try in order.
So a configuration fragment that enables this plugin *only* (this example is **intentionally incomplete**) would look like:
``` ini
auth_backends.1 = cache
```
In the [classic config format](https://www.rabbitmq.com/configure.html#config-file-formats):
``` erlang
[
{rabbit, [
{auth_backends, [rabbit_auth_backend_cache]}
]
}
].
```
This plugin wraps another auth backend (an "upstream" one) to reduce load on it.
To configure upstream auth backend, use the `auth_cache.cached_backend` configuration key
(`rabbitmq_auth_backend_cache.cached_backend` in the classic config format).
The following configuration uses the [LDAP backend]((https://rabbitmq.com/ldap.html)) for both authentication and authorization
and wraps it with caching:
auth_backends.1 = cache
auth_cache.cached_backend = ldap
In the classic config format:
``` erlang
[
{rabbit, [
%% ...
]},
{rabbitmq_auth_backend_cache, [
{cached_backend, rabbit_auth_backend_ldap}
]},
{rabbit_auth_backend_ldap, [
%% ...
]},
].
```
The following example combines this backend with the [HTTP backend](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_auth_backend_http) and its [example Spring Boot application](https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_auth_backend_http/examples):
auth_backends.1 = cache
auth_cache.cached_backend = http
auth_http.http_method = post
auth_http.user_path = http://localhost:8080/auth/user
auth_http.vhost_path = http://localhost:8080/auth/vhost
auth_http.resource_path = http://localhost:8080/auth/resource
auth_http.topic_path = http://localhost:8080/auth/topic
In the classic config format:
``` erlang
[
{rabbit, [
{auth_backends, [rabbit_auth_backend_cache]}
]
},
{rabbitmq_auth_backend_cache, [
{cached_backend, rabbit_auth_backend_http}
]
},
{rabbitmq_auth_backend_http, [{http_method, post},
{user_path, "http://127.0.0.1:8080/auth/user"},
{vhost_path, "http://127.0.0.1:8080/auth/vhost"},
{resource_path, "http://127.0.0.1:8080/auth/resource"},
{topic_path, "http://127.0.0.1:8080/auth/topic"}
]
}
].
```
It is still possible to [use different backends for authorization and authentication](https://www.rabbitmq.com/access-control.html).
The following example configures plugin to use LDAP backend for authentication
but internal backend for authorisation:
auth_backends.1 = cache
auth_cache.cached_backend.authn = ldap
auth_cache.cached_backend.authz = internal
In the classic config format:
``` erlang
[
{rabbit, [
%% ...
]},
{rabbitmq_auth_backend_cache, [{cached_backend, {rabbit_auth_backend_ldap,
rabbit_auth_backend_internal}}]}].
```
## Cache Configuration
You can configure TTL for cache items, by using `cache_ttl` configuration item, specified in **milliseconds**
auth_cache.cached_backend = ldap
auth_cache.cache_ttl = 5000
Or using the classic config for both parameters:
``` erlang
[
{rabbit, [
%% ...
]},
{rabbitmq_auth_backend_cache, [{cached_backend, rabbit_auth_backend_ldap},
{cache_ttl, 5000}]}].
```
You can also use a custom cache module to store cached requests. This module
should be an erlang module implementing `rabbit_auth_cache` behaviour and (optionally)
define `start_link` function to start cache process.
This repository provides several implementations:
* `rabbit_auth_cache_dict` stores cache entries in the internal process dictionary. **This module is for demonstration only and should not be used in production**.
* `rabbit_auth_cache_ets` stores cache entries in an [ETS](https://learnyousomeerlang.com/ets) table and uses timers for cache invalidation. **This is the default implementation**.
* `rabbit_auth_cache_ets_segmented` stores cache entries in multiple ETS tables and does not delete individual cache items but rather
uses a separate process for garbage collection.
* `rabbit_auth_cache_ets_segmented_stateless` same as previous, but with minimal use of `gen_server` state, using ets tables to store information about segments.
To specify module for caching you should use `cache_module` configuration item and
specify start args with `cache_module_args`.
Start args should be list of arguments passed to module `start_link` function
Cache module can be set via sysctl config format:
auth_cache.cache_module = rabbit_auth_backend_ets_segmented
Additional cache module arguments can only be defined via the [advanced config](https://www.rabbitmq.com/configure.html#advanced-config-file) or classic config format:
``` erlang
[
{rabbit, [
%% ...
]},
{rabbitmq_auth_backend_cache, [{cache_module_args, [10000]}]}
].
```
The above two snippets combined in the classic config format:
``` erlang
[
{rabbit, [
%% ...
]},
{rabbitmq_auth_backend_cache, [{cache_module, rabbit_auth_backend_ets_segmented},
{cache_module_args, [10000]}]}
].
```
The default values are `rabbit_auth_cache_ets` and `[]`, respectively.
## License and Copyright
(c) 2007-2024 Broadcom. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. All rights reserved.
Released under the Mozilla Public License 2.0, same as RabbitMQ.
|
