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 auth can-i list secrets --namespace dev --as dave
+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 delegating authorization decisions to the API server. For example, the kubelet and extension API servers use this to determine user access to their own APIs.
+* `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: