authorization: improve authorization debugging docs

docs/admin/authorization/index.md

@@ -68,48 +68,71 @@ of the `bind` verb on `roles` and `clusterroles` resources in the `rbac.authoriz
 
 #### Checking API Access
 
-Kubernetes exposes the `subjectaccessreviews.v1.authorization.k8s.io` resource as a
-normal resource that allows external access to API authorizer decisions.  No matter which authorizer
-you choose to use, you can issue a `POST` with a `SubjectAccessReview` just like the webhook
-authorizer to the `apis/authorization.k8s.io/v1/subjectaccessreviews` endpoint and
-get back a response.  For instance:
+`kubectl` provides the `auth can-i` subcommand for quickly querying the API authorization layer.
+The command uses the `SelfSubjectAccessReview` API to determine if the current user can perform
+a given action, and works regardless of the authorization mode used.
+
+
+```bash
+$ kubectl auth can-i create deployments --namespace dev
+yes
+$ kubectl auth can-i create deployments --namespace prod
+no
+```
+
+Administrators can combine this with ["user impersonation"](/docs/admin/authentication/#user-impersonation)
+to determine what action other users can perform.
 
 ```bash
-kubectl create --v=8 -f -  << __EOF__
+$ kubectl --as dave auth can-i list secrets --namespace=dev
+no
+```
+
+`SelfSubjectAccessReview` is part of the `authorization.k8s.io` API group, which exposes the
+API server authorization to external services. Other resources in this group include:
+
+* `SubjectAccessReview` - Access review for any user, not just the current one. Useful for deferring authorization decisions to the API server.
+* `LocalSubjectAccessReview` - Like `SubjectAccessReview` but restricted to a specific namespace.
+* `SelfSubjectRulesReview` - A review which returns the set of actions a user can perform within a namespace. Useful for users to quickly summarize their own access, or for UIs to hide/show actions.
+
+These APIs can be queried by creating normal Kubernetes resources, where the response "status"
+field of the returned object is the result of the query.
+
+```bash
+$ kubectl create -f - -o yaml << EOF
+{
+    "kind": "SelfSubjectAccessReview",
+    "apiVersion": "authorization.k8s.io/v1",
+    "spec": {
+         "resourceAttributes": {
+             "group": "apps",
+             "name": "deployments",
+             "verb": "create",
+             "namespace": "dev"
+         }
+     }
+}
+EOF
 {
-  "apiVersion": "authorization.k8s.io/v1",
-  "kind": "SubjectAccessReview",
-  "spec": {
-    "resourceAttributes": {
-      "namespace": "kittensandponies",
-      "verb": "get",
-      "group": "unicorn.example.org",
-      "resource": "pods"
+    "apiVersion": "authorization.k8s.io/v1",
+    "kind": "SelfSubjectAccessReview",
+    "metadata": {
+        "creationTimestamp": null
     },
-    "user": "jane",
-    "group": [
-      "group1",
-      "group2"
-    ],
-    "extra": {
-      "scopes": [
-        "openid",
-        "profile"
-      ]
+    "spec": {
+        "resourceAttributes": {
+            "group": "apps",
+            "name": "deployments",
+            "namespace": "dev",
+            "verb": "create"
+        }
+    },
+    "status": {
+        "allowed": true
     }
-  }
 }
-__EOF__
-
---- snip lots of output ---
-
-I0913 08:12:31.362873   27425 request.go:908] Response Body: {"kind":"SubjectAccessReview","apiVersion":"authorization.k8s.io/v1","metadata":{"creationTimestamp":null},"spec":{"resourceAttributes":{"namespace":"kittensandponies","verb":"GET","group":"unicorn.example.org","resource":"pods"},"user":"jane","group":["group1","group2"],"extra":{"scopes":["openid","profile"]}},"status":{"allowed":true}}
-subjectaccessreview "" created
 ```
 
-This is useful for debugging access problems, in that you can use this resource
-to determine what access an authorizer is granting.
-
 ## Using Flags for Your Authorization Module
 
 You must include a flag in your policy to indicate which authorization module your policies include: