1"use strict";(self.webpackChunkrabbitmq_website=self.webpackChunkrabbitmq_website||[]).push([["18943"],{6318(e,n,a){a.r(n),a.d(n,{metadata:()=>i,default:()=>d,frontMatter:()=>s,contentTitle:()=>o,toc:()=>h,assets:()=>r});var i=JSON.parse('{"id":"auth-cache-backend","title":"RabbitMQ Access Control Cache Plugin","description":"\x3c!--","source":"@site/versioned_docs/version-4.3/auth-cache-backend.md","sourceDirName":".","slug":"/auth-cache-backend","permalink":"/docs/auth-cache-backend","draft":false,"unlisted":false,"editUrl":"https://github.com/rabbitmq/rabbitmq-website/tree/main/versioned_docs/version-4.3/auth-cache-backend.md","tags":[],"version":"4.3","frontMatter":{"title":"RabbitMQ Access Control Cache Plugin"},"sidebar":"docsSidebar","previous":{"title":"LDAP","permalink":"/docs/ldap"},"next":{"title":"Authentication Failure Notifications","permalink":"/docs/auth-notification"}}'),t=a(74848),c=a(28453);let s={title:"RabbitMQ Access Control Cache Plugin"},o="Authentication/Authorization Cache Backend",r={},h=[{value:"Overview",id:"overview",level:2},{value:"Table of Contents",id:"table-of-contents",level:2},{value:"Installation",id:"installation",level:2},{value:"Authorization and Authentication Backend Configuration",id:"configuration",level:2},{value:"Basic Cache configuration",id:"basic-configuration",level:2},{value:"Advanced Cache configuration",id:"advanced-configuration",level:2},{value:"How to Clear the Cache",id:"how-to-clear-the-cache",level:2}];function l(e){let n={a:"a",code:"code",h1:"h1",h2:"h2",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,c.R)(),...e.components};return(0,t.jsxs)(t.Fragment,{children:[(0,t.jsx)(n.header,{children:(0,t.jsx)(n.h1,{id:"authenticationauthorization-cache-backend",children:"Authentication/Authorization Cache Backend"})}),"\n",(0,t.jsx)(n.h2,{id:"overview",children:"Overview"}),"\n",(0,t.jsxs)(n.p,{children:["This plugin provides a way to cache authentication and authorization backend\nresults for a configurable amount of time. It's not an independent auth backend,\nbut a caching layer for existing backends, such as the built-in, ",(0,t.jsx)(n.a,{href:"./ldap",children:"LDAP"}),",\nor ",(0,t.jsx)(n.a,{href:"https://github.com/rabbitmq/rabbitmq-server/tree/main/deps/rabbitmq_auth_backend_http",children:"HTTP"})," ones.\nAlthough it is not very useful with the\nbuilt-in (internal) ",(0,t.jsx)(n.a,{href:"./access-control",children:"authentication and authorization backends"})," but can be other\nbackends that use network requests, such as LDAP or HTTP."]}),"\n",(0,t.jsx)(n.p,{children:"Cache expiration is currently time-based."}),"\n",(0,t.jsx)(n.h2,{id:"table-of-contents",children:"Table of Contents"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#installation",children:"Installation"})}),"\n",(0,t.jsxs)(n.li,{children:["Authorization and Authentication ",(0,t.jsx)(n.a,{href:"#configuration",children:"Backend Configuration"})]}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#basic-configuration",children:"Plugin configuration"})}),"\n",(0,t.jsx)(n.li,{children:(0,t.jsx)(n.a,{href:"#advanced-configuration",children:"Advanced plugin configuration"})}),"\n"]}),"\n",(0,t.jsx)(n.h2,{id:"installation",children:"Installation"}),"\n",(0,t.jsxs)(n.p,{children:["The ",(0,t.jsx)(n.code,{children:"rabbitmq_auth_backend_cache"})," plugin ships with RabbitMQ."]}),"\n",(0,t.jsxs)(n.p,{children:["Like all plugins, it ",(0,t.jsx)(n.a,{href:"./plugins",children:"must be enabled"})," before it can be used, for example,\nuse ",(0,t.jsx)(n.a,{href:"./cli",children:(0,t.jsx)(n.code,{children:"rabbitmqctl"})}),":"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"rabbitmq-plugins enable rabbitmq_auth_backend_cache\n"})}),"\n",(0,t.jsx)(n.h2,{id:"configuration",children:"Authorization and Authentication Backend Configuration"}),"\n",(0,t.jsxs)(n.p,{children:["To configure this plugin so that it caches all the authorization and authentication\ndecisions, first set this cache backend as the ",(0,t.jsx)(n.code,{children:"auth_backends"})," or one\nof them and then you configure which authentication backend is actually cached."]}),"\n",(0,t.jsxs)(n.p,{children:["For example, to cache requests to the ",(0,t.jsx)(n.code,{children:"http"})," backend:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"auth_backends.1 = cache\nauth_cache.cac
1hed_backend = http\n\nauth_http.http_method = post\n"})}),"\n",(0,t.jsx)(n.p,{children:"It is possible to use different backends for authorization and authentication."}),"\n",(0,t.jsx)(n.p,{children:"The following example configures the plugin to use LDAP backend for\nauthentication, but internal backend for authorization:"}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"auth_backends.1 = cache\n\nauth_cache.cached_backend.authn = ldap\nauth_cache.cached_backend.authz = internal\n"})}),"\n",(0,t.jsx)(n.h2,{id:"basic-configuration",children:"Basic Cache configuration"}),"\n",(0,t.jsxs)(n.p,{children:["You can configure TTL for cache items, by using ",(0,t.jsx)(n.code,{children:"cache_ttl"})," configuration variable,\nspecified in milliseconds. The default value is ",(0,t.jsx)(n.code,{children:"15000"})," milliseconds:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"auth_cache.cached_backend = ldap\nauth_cache.cache_ttl = 5000\n"})}),"\n",(0,t.jsxs)(n.p,{children:["By default, negative authentication and/or authorization decisions are not cached,\nonly positive ones are. However, this behaviour can be changed by setting ",(0,t.jsx)(n.code,{children:"cache_refusals"})," to ",(0,t.jsx)(n.code,{children:"true"}),"\nas shown below:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"auth_cache.cache_refusals = true\n"})}),"\n",(0,t.jsx)(n.h2,{id:"advanced-configuration",children:"Advanced Cache configuration"}),"\n",(0,t.jsxs)(n.p,{children:["You can also use a custom cache module to store cached requests. This module\nshould be an Erlang module implementing the ",(0,t.jsx)(n.code,{children:"rabbit_auth_cache"})," behavior and\n(optionally) define ",(0,t.jsx)(n.code,{children:"start_link"})," function to start the cache process."]}),"\n",(0,t.jsx)(n.p,{children:"This repository provides several implementations:"}),"\n",(0,t.jsxs)(n.ul,{children:["\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"rabbit_auth_cache_dict"})," stores cache entries in the internal process dictionary.\nThis module is for demonstration only and should not be used in production."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"rabbit_auth_cache_ets"})," stores cache entries in an ",(0,t.jsx)(n.a,{href:"https://learnyousomeerlang.com/ets",children:"ETS"}),"\ntable and uses timers for cache invalidation. ",(0,t.jsx)(n.strong,{children:"This is the default implementation"}),"."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"rabbit_auth_cache_ets_segmented"})," stores cache entries in multiple ETS tables\nand does not delete individual cache items but rather uses a separate process for garbage collection."]}),"\n",(0,t.jsxs)(n.li,{children:[(0,t.jsx)(n.code,{children:"rabbit_auth_cache_ets_segmented_stateless"})," same as previous, but with minimal\nuse of ",(0,t.jsx)(n.code,{children:"gen_server"})," state, using ets tables to store information about segments."]}),"\n"]}),"\n",(0,t.jsxs)(n.p,{children:["To specify the module for caching, use the ",(0,t.jsx)(n.code,{children:"cache_module"})," configuration key.\nThis example configuration configures the ",(0,t.jsx)(n.code,{children:"rabbit_auth_backend_ets_segmented"})," module."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-ini",children:"auth_cache.cache_module = rabbit_auth_backend_ets_segmented\n"})}),"\n",(0,t.jsxs)(n.p,{children:["When using a custom implementation of a ",(0,t.jsx)(n.code,{children:"cache_module"}),", you can specify ",(0,t.jsx)(n.code,{children:"start args"}),"\nwith ",(0,t.jsx)(n.code,{children:"cache_module_args"}),". ",(0,t.jsx)(n.code,{children:"Start args"})," should be list of arguments passed to\nmodule ",(0,t.jsx)(n.code,{children:"start_link"})," function."]}),"\n",(0,t.jsxs)(n.p,{children:["However, additional cache module arguments can only be defined via the\n",(0,t.jsx)(n.a,{href:"./configure#advanced-config-file",children:"advanced.config"}),"."]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-erlang",children:"[\n {rabbit, [\n %% ...\n ]},\n\n {rabbitmq_auth_backend_cache, [\n {cache_module, rabbit_auth_backend_ets_segmented},\n {cache_module_args, [10000]}\n ]}\n].\n"})}),"\n",(0,t.jsx)(n.h2,{id:"how-to-clear-the-cache",children:"How to Clear the Cache"}),"\n",(0,t.jsxs)(n.p,{children:["A ",(0,t.jsx)(n.a,{href:"./man/rabbitmqctl.8",children:(0,t.jsx)(n.code,{children:"rabbitmqctl"})})," command ",(0,t.jsx)(n.code,{children:"clear_auth_backend_cache"}),"\ncan be used to clear the cache across all cluster nodes:"]}),"\n",(0,t.jsx)(n.pre,{children:(0,t.jsx)(n.code,{className:"language-bash",children:"rabbitmqctl clear_auth_backend_cache\n"})})]})}function d(e={}){let{wrapper:n}={...(0,c.R)(),...e.components};return n?(0,t.jsx)(n,{...e,children:(0,t.jsx)(l,{...e})}):l(e)}},28453(e,n,a){a.d(n,{R:()=>s,x:()=>o});var i=a(96540);let t={},c=i.createContext(t);function s(e){let n=i.useContext(c);return i.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function o(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(t):e.components||t:s(e.components),i.createElement(c.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.