From: Rich Bowen <rbowen@apache.org>
Date: Fri, 1 May 2026 20:14:05 +0000 (+0000)
Subject: Bug 65145: Add Authorization Result States section; cross-reference from Require... 
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=5a83e98043f95d6df0e7100bba7607b2c3a2bd89;p=thirdparty%2Fapache%2Fhttpd.git

Bug 65145: Add Authorization Result States section; cross-reference from Require directives, auth howto, and authz provider modules

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1933687 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/howto/auth.xml b/docs/manual/howto/auth.xml
index 21f58eb64f..a87a511155 100644
--- a/docs/manual/howto/auth.xml
+++ b/docs/manual/howto/auth.xml
@@ -475,7 +475,10 @@ Require valid-user
         access is granted.  See
         <a href="../mod/mod_authz_core.html#logic">Authorization Containers</a>
         for an example of how they may be used to express complex
-        authorization logic.</p>
+        authorization logic.  Each authorization provider returns one
+        of three possible results; see
+        <a href="../mod/mod_authz_core.html#authzresults">Authorization Result States</a>
+        for details on how containers interpret these results.</p>
 
         <p>By default all
         <directive module="mod_authz_core">Require</directive>
diff --git a/docs/manual/mod/mod_authz_core.xml b/docs/manual/mod/mod_authz_core.xml
index 6b3a194638..3b53ef112e 100644
--- a/docs/manual/mod/mod_authz_core.xml
+++ b/docs/manual/mod/mod_authz_core.xml
@@ -85,6 +85,56 @@
     </highlight>
 </section>
 
+<section id="authzresults"><title>Authorization Result States</title>
+
+    <p>Each authorization provider returns one of three possible results
+    when evaluating a <directive module="mod_authz_core">Require</directive>
+    directive:</p>
+
+    <dl>
+      <dt><strong>Granted</strong></dt>
+      <dd>The provider has verified that the request meets
+      its requirements.</dd>
+
+      <dt><strong>Denied</strong></dt>
+      <dd>The provider has determined that the request does not
+      meet its requirements.</dd>
+
+      <dt><strong>Neutral</strong></dt>
+      <dd>The provider has no opinion about the request. This
+      can occur when a provider is not relevant to the request
+      (e.g., a group-membership check when the request does not
+      involve group-based authorization).</dd>
+    </dl>
+
+    <p>The authorization container directives interpret these three
+    results as follows:</p>
+
+    <table border="1" style="zebra">
+    <columnspec><column width=".25"/><column width=".25"/><column width=".25"/><column width=".25"/></columnspec>
+    <tr><th>Container</th><th>Granted if...</th><th>Denied if...</th><th>Neutral treated as...</th></tr>
+    <tr><td><directive module="mod_authz_core" type="section">RequireAny</directive></td>
+        <td>at least one provider grants</td>
+        <td>all providers deny</td>
+        <td>deny (does not satisfy the requirement)</td></tr>
+    <tr><td><directive module="mod_authz_core" type="section">RequireAll</directive></td>
+        <td>no provider denies (and at least one grants)</td>
+        <td>any provider denies</td>
+        <td>grant (does not block the requirement)</td></tr>
+    <tr><td><directive module="mod_authz_core" type="section">RequireNone</directive></td>
+        <td>no provider grants</td>
+        <td>any provider grants</td>
+        <td>grant (does not block)</td></tr>
+    </table>
+
+    <p>When a <directive>Require</directive> directive is negated with
+    <code>not</code> (e.g., <code>Require not group temps</code>), a
+    granted result is inverted to denied and vice versa, but a neutral
+    result remains neutral. A negated directive can therefore never
+    independently authorize a request.</p>
+
+</section>
+
 <section id="requiredirectives"><title>The Require Directives</title>
 
   <p><module>mod_authz_core</module> provides some generic authorization
@@ -402,6 +452,7 @@ Require group admin
 
 <seealso><a href="../howto/access.html">Access Control howto</a></seealso>
 <seealso><a href="#logic">Authorization Containers</a></seealso>
+<seealso><a href="#authzresults">Authorization Result States</a></seealso>
 <seealso><module>mod_authn_core</module></seealso>
 <seealso><module>mod_authz_host</module></seealso>
 </directivesynopsis>
@@ -433,6 +484,7 @@ succeed.</description>
 </usage>
 
 <seealso><a href="#logic">Authorization Containers</a></seealso>
+<seealso><a href="#authzresults">Authorization Result States</a></seealso>
 <seealso><a href="../howto/auth.html">Authentication, Authorization,
     and Access Control</a></seealso>
 
@@ -471,6 +523,7 @@ must succeed for the enclosing directive to succeed.</description>
 </usage>
 
 <seealso><a href="#logic">Authorization Containers</a></seealso>
+<seealso><a href="#authzresults">Authorization Result States</a></seealso>
 <seealso><a href="../howto/auth.html">Authentication, Authorization,
     and Access Control</a></seealso>
 
@@ -512,6 +565,7 @@ must succeed for the enclosing directive to not fail.</description>
 </usage>
 
 <seealso><a href="#logic">Authorization Containers</a></seealso>
+<seealso><a href="#authzresults">Authorization Result States</a></seealso>
 <seealso><a href="../howto/auth.html">Authentication, Authorization,
     and Access Control</a></seealso>
 
diff --git a/docs/manual/mod/mod_authz_groupfile.xml b/docs/manual/mod/mod_authz_groupfile.xml
index 014d136fa9..42a3285f6e 100644
--- a/docs/manual/mod/mod_authz_groupfile.xml
+++ b/docs/manual/mod/mod_authz_groupfile.xml
@@ -36,6 +36,7 @@
 </summary>
 
 <seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso><a href="mod_authz_core.html#authzresults">Authorization Result States</a></seealso>
 
 <section id="requiredirectives"><title>The Require Directives</title>
 
diff --git a/docs/manual/mod/mod_authz_host.xml b/docs/manual/mod/mod_authz_host.xml
index f68a3c9be1..29634a49a5 100644
--- a/docs/manual/mod/mod_authz_host.xml
+++ b/docs/manual/mod/mod_authz_host.xml
@@ -52,6 +52,7 @@ address)</description>
 <seealso><a href="../howto/auth.html">Authentication, Authorization,
     and Access Control</a></seealso>
 <seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso><a href="mod_authz_core.html#authzresults">Authorization Result States</a></seealso>
 
 <section id="requiredirectives"><title>The Require Directives</title>
 
diff --git a/docs/manual/mod/mod_authz_user.xml b/docs/manual/mod/mod_authz_user.xml
index 7461f15d25..615c3756f9 100644
--- a/docs/manual/mod/mod_authz_user.xml
+++ b/docs/manual/mod/mod_authz_user.xml
@@ -37,6 +37,7 @@
     grant access to all successfully authenticated users.</p>
 </summary>
 <seealso><directive module="mod_authz_core">Require</directive></seealso>
+<seealso><a href="mod_authz_core.html#authzresults">Authorization Result States</a></seealso>
 
 <section id="requiredirectives"><title>The Require Directives</title>