rabbitmq-server/deps/rabbitmq_auth_backend_cache

RabbitMQ Access Control Cache Plugin

This plugin provides a caching layer for access control operations 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 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, or HTTP ones.

Cache expiration is currently time-based. It is not very useful with the built-in (internal) authn/authz backends 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 before it can be used.

Installation

This plugin ships with reasonably recent RabbitMQ versions (e.g. 3.7.0 or later). Enable it with

rabbitmq-plugins enable rabbitmq_auth_backend_cache

Binary Builds

Binary builds can be obtained from project releases on GitHub.

Building

You can build and install it like any other plugin (see the plugin development guide).

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:

auth_backends.1 = cache

In the classic config format:

[
  {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 for both authentication and authorization and wraps it with caching:

auth_backends.1 = cache

auth_cache.cached_backend = ldap

In the classic config format:

[
  {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 and its example Spring Boot application:

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:

[
 {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.

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:

[
  {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:

[
 {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 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 or classic config format:

[
 {rabbit, [
   %% ...
 ]},

 {rabbitmq_auth_backend_cache, [{cache_module_args, [10000]}]}
].

The above two snippets combined in the classic config format:

[
 {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.