[#2484] Updated default/unknown role doc

diff --git a/doc/sphinx/arm/hooks-rbac.rst b/doc/sphinx/arm/hooks-rbac.rst
index 4bf99c903a8602bf6d6d9165e078ba2f4cc91ce8..d1c0b9c8ea28fa9d0997d7a6b03d960ab8dfcfea 100644 (file)
--- a/doc/sphinx/arm/hooks-rbac.rst
+++ b/doc/sphinx/arm/hooks-rbac.rst
@@ -59,11 +59,6 @@ Role assignment is governed by the configured role-assignment method.
 Role Configuration
 ------------------
 
-If role assignment returns an empty role, the configuration of the
-``default`` role is used; by default the request is rejected.
-If role assignment returns a not-empty role without a configuration,
-the configuration of the ``unknown`` role is used.
-
 .. table:: Role configuration parameters
 
    +------------------+----------------------------------------------------+
@@ -86,6 +81,19 @@ the configuration of the ``unknown`` role is used.
    | response-filters | the filters to apply to responses                  |
    +------------------+----------------------------------------------------+
 
+.. note::
+
+   The role assignment can fail, for instance with ``cert-subject`` when
+   the client certificate was not required, or it has no subject common
+   name and instead a DNS alternative subject name. In this case the role
+   assignment returns the empty role and the ``default-role`` entry is used.
+
+   The role assignment can return an unexpected value e.g. with an
+   unregistered role name or a typing error. In this case the ``unknown-role``
+   entry is used.
+
+   Both ``default-role`` and ``unknown-role`` default to reject all commands.
+
 API Commands
 ------------