Merge pull request #1342 from liggitt/anonymous

Describe anonymous access, system:authenticated group

docs/admin/authentication.md

@@ -25,10 +25,11 @@ manually through API calls. Service accounts are tied to a set of credentials
 stored as `Secrets`, which are mounted into pods allowing in cluster processes
 to talk to the Kubernetes API.
 
-All API requests are tied to either a normal user or a service account. This
-means every process inside or outside the cluster, from a human user typing
-`kubectl` on a workstation, to `kubelets` on nodes, to members of the control
-plane, must authenticate when making requests to the the API server.
+API requests are tied to either a normal user or a service account, or are treated
+as anonymous requests. This means every process inside or outside the cluster, from 
+a human user typing `kubectl` on a workstation, to `kubelets` on nodes, to members 
+of the control plane, must authenticate when making requests to the the API server, 
+or be treated as an anonymous user.
 
 ## Authentication strategies
 
@@ -54,6 +55,8 @@ When multiple are enabled, the first authenticator module
 to successfully authenticate the request short-circuits evaluation.
 The API server does not guarantee the order authenticators run in.
 
+The `system:authenticated` group is included in the list of groups for all authenticated users. 
+
 ### X509 Client Certs
 
 Client certificate authentication is enabled by passing the `--client-ca-file=SOMEFILE`
@@ -363,6 +366,22 @@ Please refer to the [discussion](https://github.com/kubernetes/kubernetes/pull/1
 [blueprint](https://github.com/kubernetes/kubernetes/issues/11626) and [proposed
 changes](https://github.com/kubernetes/kubernetes/pull/25536) for more details.
 
+## Anonymous requests
+
+Anonymous access is enabled by default, and can be disabled by passing `--anonymous-auth=false` 
+option to the API server during startup.
+
+When enabled, requests that are not rejected by other configured authentication methods are 
+treated as anonymous requests, and given a username of `system:anonymous` and a group of 
+`system:unauthenticated`.
+
+For example, on a server with token authentication configured, and anonymous access enabled,
+a request providing an invalid bearer token would receive a `401 Unauthorized` error. 
+A request providing no bearer token would be treated as an anonymous request. 
+
+If you rely on authentication alone to authorize access, either change to use an 
+authorization mode other than `AlwaysAllow`, or set `--anonymous-auth=false`.
+
 ## Plugin Development
 
 We plan for the Kubernetes API server to issue tokens after the user has been