From db29a0f91e8736b8b264e306607cf7528284fed8 Mon Sep 17 00:00:00 2001
From: Anders Eknert <anders@eknert.com>
Date: Wed, 21 Aug 2019 04:41:16 +0200
Subject: [PATCH] Clarify "no opinion" vs. immediate, short-circuiting deny
 response. (#15849)

---
 .../reference/access-authn-authz/webhook.md   | 25 ++++++++++++++++++-
 1 file changed, 24 insertions(+), 1 deletion(-)

diff --git a/content/en/docs/reference/access-authn-authz/webhook.md b/content/en/docs/reference/access-authn-authz/webhook.md
index e4945b1685..3f667fa5ef 100644
--- a/content/en/docs/reference/access-authn-authz/webhook.md
+++ b/content/en/docs/reference/access-authn-authz/webhook.md
@@ -108,7 +108,13 @@ the request and respond to either allow or disallow access. The response body's
 }
 ```
 
-To disallow access, the remote service would return:
+For disallowing access there are two methods.
+
+The first method is preferred in most cases, and indicates the authorization
+webhook does not allow, or has "no opinion" about the request, but if other 
+authorizers are configured, they are given a chance to allow the request. 
+If there are no other authorizers, or none of them allow the request, the 
+request is forbidden. The webhook would return:
 
 ```json
 {
@@ -121,6 +127,23 @@ To disallow access, the remote service would return:
 }
 ```
 
+The second method denies immediately, short-circuiting evaluation by other 
+configured authorizers. This should only be used by webhooks that have 
+detailed knowledge of the full authorizer configuration of the cluster. 
+The webhook would return:
+
+```json
+{
+  "apiVersion": "authorization.k8s.io/v1beta1",
+  "kind": "SubjectAccessReview",
+  "status": {
+    "allowed": false,
+    "denied": true,
+    "reason": "user does not have read access to the namespace"
+  }
+}
+```
+
 Access to non-resource paths are sent as:
 
 ```json