Optionally return authz refusal reason to client

 ## What?

If the new config setting `authorization_failure_disclosure`
for an authz backend is set to `true`, (`false` by default), RabbitMQ
will return the reason why access was denied to the client.
For now, only the HTTP and OAuth 2.0 auth backends support this new
config setting.

 ## Why?

This helps debugging and troubleshooting directly in the client.
Some users might not have access to the RabbitMQ logs, for other
users it's cumbersome to correlate authz denial in the client with
logs on the broker.

For example, in dev environments, it may be useful for users to learn
why vhost/resource/topic access was denied for a given OAuth 2.0 token.

Another example is that some customers would like to pass the reason why
authorization was denied from their custom HTTP auth backend via
RabbitMQ back to the client.

 ## How?

Authz backends can now return `{false, Reason}` as an alternative to
just `false` if access is denied.

For security reasons, the additional denial reason by the authz backend
will be returned to the client only if the operator opted in by setting
`authorization_failure_disclosure` to `true`.

Note that `authorization_failure_disclosure` applies only to
already authenticated clients when they try to access resources (e.g. vhosts,
exchanges, queues, topics). For security reasons, no detailed denial reason is
returned to the client if **authentication** fails.

Also note that `authorization_failure_disclosure` is set separately per
auth backend instead of being set globally for all auth backends. This
more fine granular configurability helps for use cases where the broker
should reveal the authz denial reason for only a specific auth backend,
e.g. only for HTTP backend, but not for OAuth 2.0 backend.

Author: ansd

deps/rabbit/src/rabbit_access_control.erl

@@ -361,6 +361,10 @@ check_access(Fun, Module, ErrStr, ErrArgs, ErrName) ->
             ok;
         false ->
             rabbit_misc:protocol_error(ErrName, ErrStr, ErrArgs);
+        {false, Reason} ->
+            FullErrStr = ErrStr ++ " by backend ~ts: ~ts",
+            FullErrArgs = ErrArgs ++ [Module, Reason],
+            rabbit_misc:protocol_error(ErrName, FullErrStr, FullErrArgs);
         {error, E}  ->
             FullErrStr = ErrStr ++ ", backend ~ts returned an error: ~tp",
             FullErrArgs = ErrArgs ++ [Module, E],

deps/rabbit/src/rabbit_authz_backend.erl

@@ -32,25 +32,27 @@
 %% Possible responses:
 %% true
 %% false
+%% {false, Reason}
 %% {error, Error}
 %%     Something went wrong. Log and die.
 -callback check_vhost_access(AuthUser :: rabbit_types:auth_user(),
                              VHost :: rabbit_types:vhost(),
                              AuthzData :: rabbit_types:authz_data()) ->
-    boolean() | {'error', any()}.
+    boolean() | {false, Reason :: string()} | {'error', any()}.
 
 %% Given #auth_user, resource and permission, can a user access a resource?
 %%
 %% Possible responses:
 %% true
 %% false
+%% {false, Reason}
 %% {error, Error}
 %%     Something went wrong. Log and die.
 -callback check_resource_access(rabbit_types:auth_user(),
                                 rabbit_types:r(atom()),
                                 rabbit_types:permission_atom(),
                                 rabbit_types:authz_context()) ->
-    boolean() | {'error', any()}.
+    boolean() | {false, Reason :: string()} | {'error', any()}.
 
 %% Given #auth_user, topic as resource, permission, and context, can a user access the topic?
 %%
@@ -63,7 +65,7 @@
     rabbit_types:r(atom()),
     rabbit_types:permission_atom(),
     rabbit_types:topic_access_context()) ->
-    boolean() | {'error', any()}.
+    boolean() | {false, Reason :: string()} | {'error', any()}.
 
 %% Updates backend state that has expired.
 %%

deps/rabbitmq_auth_backend_cache/src/rabbit_auth_backend_cache.erl

@@ -36,37 +36,34 @@ user_login_authorization(Username, AuthProps) ->
         end).
 
 check_vhost_access(#auth_user{} = AuthUser, VHostPath, AuthzData) ->
-    with_cache(authz, {check_vhost_access, [AuthUser, VHostPath, AuthzData]},
-        fun(true)  -> success;
-           (false) -> refusal;
-           ({error, _} = Err) -> Err;
-           (_)                -> unknown
-        end).
+    with_cache(authz,
+               {check_vhost_access, [AuthUser, VHostPath, AuthzData]},
+               fun convert_backend_result/1).
 
 check_resource_access(#auth_user{} = AuthUser,
                       #resource{} = Resource, Permission, AuthzContext) ->
-    with_cache(authz, {check_resource_access, [AuthUser, Resource, Permission, AuthzContext]},
-        fun(true)  -> success;
-           (false) -> refusal;
-           ({error, _} = Err) -> Err;
-           (_)                -> unknown
-        end).
+    with_cache(authz,
+               {check_resource_access, [AuthUser, Resource, Permission, AuthzContext]},
+               fun convert_backend_result/1).
 
 check_topic_access(#auth_user{} = AuthUser,
                    #resource{} = Resource, Permission, Context) ->
-    with_cache(authz, {check_topic_access, [AuthUser, Resource, Permission, Context]},
-        fun(true)  -> success;
-            (false) -> refusal;
-            ({error, _} = Err) -> Err;
-            (_)                -> unknown
-        end).
+    with_cache(authz,
+               {check_topic_access, [AuthUser, Resource, Permission, Context]},
+               fun convert_backend_result/1).
 
 expiry_timestamp(_) -> never.
 
 %%
 %% Implementation
 %%
 
+convert_backend_result(true) -> success;
+convert_backend_result(false) -> refusal;
+convert_backend_result({false, _}) -> refusal;
+convert_backend_result({error, _} = Err) -> Err;
+convert_backend_result(_) -> unknown.
+
 clear_cache_cluster_wide() ->
     Nodes = rabbit_nodes:list_running(),
     ?LOG_WARNING("Clearing auth_backend_cache in all nodes : ~p", [Nodes]),

deps/rabbitmq_auth_backend_cache/src/rabbit_auth_cache.erl

@@ -18,7 +18,7 @@
 -callback clear() -> ok.
 
 expiration(TTL) ->
-    erlang:system_time(milli_seconds) + TTL.
+    erlang:system_time(millisecond) + TTL.
 
 expired(Exp) ->
-    erlang:system_time(milli_seconds) > Exp.
+    erlang:system_time(millisecond) > Exp.

deps/rabbitmq_auth_backend_http/Makefile

@@ -10,7 +10,8 @@ define PROJECT_ENV
 	    {user_path,     "http://localhost:8000/auth/user"},
 	    {vhost_path,    "http://localhost:8000/auth/vhost"},
 	    {resource_path, "http://localhost:8000/auth/resource"},
-	    {topic_path,    "http://localhost:8000/auth/topic"}
+	    {topic_path,    "http://localhost:8000/auth/topic"},
+	    {authorization_failure_disclosure, false}
 	  ]
 endef
 

deps/rabbitmq_auth_backend_http/priv/schema/rabbitmq_auth_backend_http.schema

@@ -23,6 +23,9 @@
 {mapping, "auth_http.connection_timeout", "rabbitmq_auth_backend_http.connection_timeout",
     [{datatype, integer}]}.
 
+{mapping, "auth_http.authorization_failure_disclosure", "rabbitmq_auth_backend_http.authorization_failure_disclosure", [
+    {datatype, {enum, [true, false]}}]}.
+
 %% TLS options
 
 {mapping, "auth_http.ssl_options", "rabbitmq_auth_backend_http.ssl_options", [

deps/rabbitmq_auth_backend_http/src/rabbit_auth_backend_http.erl

@@ -25,6 +25,8 @@
 
 -define(SUCCESSFUL_RESPONSE_CODES, [200, 201]).
 
+-define(APP, rabbitmq_auth_backend_http).
+
 %%--------------------------------------------------------------------
 
 description() ->
@@ -120,34 +122,34 @@ check_vhost_access(#auth_user{username = Username, tags = Tags}, VHost,
 
 do_check_vhost_access(Username, Tags, VHost, Ip, AuthzData) ->
     OptionsParameters = context_as_parameters(AuthzData),
-    bool_req(vhost_path, [{username, Username},
-                          {vhost,    VHost},
-                          {ip,       Ip},
-                          {tags,     join_tags(Tags)}] ++ OptionsParameters).
+    req(vhost_path, [{username, Username},
+                     {vhost,    VHost},
+                     {ip,       Ip},
+                     {tags,     join_tags(Tags)}] ++ OptionsParameters).
 
 check_resource_access(#auth_user{username = Username, tags = Tags},
                       #resource{virtual_host = VHost, kind = Type, name = Name},
                       Permission,
                       AuthzContext) ->
     OptionsParameters = context_as_parameters(AuthzContext),
-    bool_req(resource_path, [{username,   Username},
-                             {vhost,      VHost},
-                             {resource,   Type},
-                             {name,       Name},
-                             {permission, Permission},
-                             {tags, join_tags(Tags)}] ++ OptionsParameters).
+    req(resource_path, [{username,   Username},
+                        {vhost,      VHost},
+                        {resource,   Type},
+                        {name,       Name},
+                        {permission, Permission},
+                        {tags, join_tags(Tags)}] ++ OptionsParameters).
 
 check_topic_access(#auth_user{username = Username, tags = Tags},
                    #resource{virtual_host = VHost, kind = topic = Type, name = Name},
                    Permission,
                    Context) ->
     OptionsParameters = context_as_parameters(Context),
-    bool_req(topic_path, [{username,   Username},
-        {vhost,      VHost},
-        {resource,   Type},
-        {name,       Name},
-        {permission, Permission},
-        {tags, join_tags(Tags)}] ++ OptionsParameters).
+    req(topic_path, [{username,   Username},
+                     {vhost,      VHost},
+                     {resource,   Type},
+                     {name,       Name},
+                     {permission, Permission},
+                     {tags, join_tags(Tags)}] ++ OptionsParameters).
 
 expiry_timestamp(_) -> never.
 
@@ -163,7 +165,7 @@ context_as_parameters(Options) when is_map(Options) ->
 context_as_parameters(_) ->
     [].
 
-bool_req(PathName, Props) ->
+req(PathName, Props) ->
     Path = p(PathName),
     Query = q(Props),
     case http_req(Path, Query) of
@@ -172,7 +174,12 @@ bool_req(PathName, Props) ->
         "deny " ++ Reason ->
             ?LOG_INFO("HTTP authorisation denied for path ~ts with query ~ts: ~ts",
                       [Path, Query, Reason]),
-            false;
+            case application:get_env(?APP, authorization_failure_disclosure) of
+                {ok, true} ->
+                    {false, Reason};
+                _ ->
+                    false
+            end;
         Body ->
             case string:lowercase(Body) of
                 "deny" ->
@@ -201,7 +208,7 @@ do_http_req(Path0, Query) ->
     {host, Host} = lists:keyfind(host, 1, URI),
     {port, Port} = lists:keyfind(port, 1, URI),
     HostHdr = rabbit_misc:format("~ts:~b", [Host, Port]),
-    {ok, Method} = application:get_env(rabbitmq_auth_backend_http, http_method),
+    {ok, Method} = application:get_env(?APP, http_method),
     Request = case rabbit_data_coercion:to_atom(Method) of
         get  ->
             Path = Path0 ++ "?" ++ Query,
@@ -212,12 +219,12 @@ do_http_req(Path0, Query) ->
             {Path0, [{"Host", HostHdr}], "application/x-www-form-urlencoded", Query}
     end,
     RequestTimeout =
-        case application:get_env(rabbitmq_auth_backend_http, request_timeout) of
+        case application:get_env(?APP, request_timeout) of
             {ok, Val1} -> Val1;
             _ -> infinity
         end,
     ConnectionTimeout =
-        case application:get_env(rabbitmq_auth_backend_http, connection_timeout) of
+        case application:get_env(?APP, connection_timeout) of
             {ok, Val2} -> Val2;
             _ -> RequestTimeout
         end,
@@ -238,10 +245,10 @@ do_http_req(Path0, Query) ->
     end.
 
 ssl_options() ->
-    case application:get_env(rabbitmq_auth_backend_http, ssl_options) of
+    case application:get_env(?APP, ssl_options) of
         {ok, Opts0} when is_list(Opts0) ->
             Opts1 = [{ssl, rabbit_ssl_options:fix_client(Opts0)}],
-            case application:get_env(rabbitmq_auth_backend_http, ssl_hostname_verification) of
+            case application:get_env(?APP, ssl_hostname_verification) of
                 {ok, wildcard} ->
                     ?LOG_DEBUG("Enabling wildcard-aware hostname verification for HTTP client connections"),
                     %% Needed for HTTPS connections that connect to servers that use wildcard certificates.
@@ -254,7 +261,7 @@ ssl_options() ->
     end.
 
 p(PathName) ->
-    {ok, Path} = application:get_env(rabbitmq_auth_backend_http, PathName),
+    {ok, Path} = application:get_env(?APP, PathName),
     Path.
 
 q(Args) ->

deps/rabbitmq_auth_backend_http/test/auth_SUITE.erl renamed to deps/rabbitmq_auth_backend_http/test/auth_unit_SUITE.erl

@@ -4,7 +4,7 @@
 %%
 %% Copyright (c) 2007-2025 Broadcom. All Rights Reserved. The term “Broadcom” refers to Broadcom Inc. and/or its subsidiaries. All rights reserved.
 
--module(auth_SUITE).
+-module(auth_unit_SUITE).
 
 -include_lib("common_test/include/ct.hrl").
 -include_lib("eunit/include/eunit.hrl").

deps/rabbitmq_auth_backend_http/test/config_schema_SUITE_data/rabbitmq_auth_backend_http.snippets

@@ -3,13 +3,15 @@
    auth_http.http_method   = post
    auth_http.user_path     = http://some-server/auth/user
    auth_http.vhost_path    = http://some-server/auth/vhost
-   auth_http.resource_path = http://some-server/auth/resource",
+   auth_http.resource_path = http://some-server/auth/resource
+   auth_http.authorization_failure_disclosure = true",
   [{rabbit,[{auth_backends,[rabbit_auth_backend_http]}]},
    {rabbitmq_auth_backend_http,
     [{http_method, post},
      {user_path,"http://some-server/auth/user"},
      {vhost_path,"http://some-server/auth/vhost"},
-     {resource_path,"http://some-server/auth/resource"}]}],
+     {resource_path,"http://some-server/auth/resource"},
+     {authorization_failure_disclosure, true}]}],
   [rabbitmq_auth_backend_http]},
  {default_http_method,
   "auth_backends.1        = http

deps/rabbitmq_auth_backend_oauth2/priv/schema/rabbitmq_auth_backend_oauth2.schema

@@ -158,6 +158,11 @@
  "rabbitmq_auth_backend_oauth2.issuer",
  [{datatype, string}, {validators, ["uri", "https_uri"]}]}.
 
+{mapping,
+ "auth_oauth2.authorization_failure_disclosure",
+ "rabbitmq_auth_backend_oauth2.authorization_failure_disclosure",
+ [{datatype, {enum, [true, false]}}]}.
+
 {mapping,
  "auth_oauth2.token_endpoint",
  "rabbitmq_auth_backend_oauth2.token_endpoint",