Merge pull request #35385 from nabokihms/patch-2

Add doc about how to get self subject attributes

content/en/docs/reference/access-authn-authz/authentication.md

@@ -1219,6 +1219,147 @@ The following `ExecCredential` manifest describes a cluster information sample.
 {{% /tab %}}
 {{< /tabs >}}
 
+## API access to authentication information for a client {#self-subject-review}
+
+{{< feature-state for_k8s_version="v1.26" state="alpha" >}}
+
+If your cluster has the API enabled, you can use the `SelfSubjectReview` API to find out how your Kubernetes cluster maps your authentication
+information to identify you as a client. This works whether you are authenticating as a user (typically representing
+a real person) or as a ServiceAccount.
+
+`SelfSubjectReview` objects do not have any configurable fields. On receiving a request, the Kubernetes API server fills the status with the user attributes and returns it to the user.
+
+Request example (the body would be a `SelfSubjectReview`):
+```
+POST /apis/authentication.k8s.io/v1alpha1/selfsubjectreviews
+```
+```json
+{
+  "apiVersion": "authentication.k8s.io/v1alpha1",
+  "kind": "SelfSubjectReview"
+}
+```
+Response example:
+
+```json
+{
+  "apiVersion": "authentication.k8s.io/v1alpha1",
+  "kind": "SelfSubjectReview",
+  "status": {
+    "userInfo": {
+      "name": "jane.doe",
+      "uid": "b6c7cfd4-f166-11ec-8ea0-0242ac120002",
+      "groups": [
+        "viewers",
+        "editors",
+        "system:authenticated"
+      ],
+      "extra": {
+        "provider_id": ["token.company.example"]
+      }
+    }
+  }
+}
+```
+
+For convenience, the `kubectl alpha auth whoami` command is present. Executing this command will produce the following output (yet different user attributes will be shown):
+
+* Simple output example
+    ```
+    ATTRIBUTE         VALUE
+    Username          jane.doe
+    Groups            [system:authenticated]
+    ```
+
+* Complex example including extra attributes
+    ```
+    ATTRIBUTE         VALUE
+    Username          jane.doe
+    UID               b79dbf30-0c6a-11ed-861d-0242ac120002
+    Groups            [students teachers system:authenticated]
+    Extra: skills     [reading learning]
+    Extra: subjects   [math sports]
+    ```
+By providing the output flag, it is also possible to print the JSON or YAML representation of the result:
+
+{{< tabs name="self_subject_attributes_review_Example_1" >}}
+{{% tab name="JSON" %}}
+```json
+{
+  "apiVersion": "authentication.k8s.io/v1alpha1",
+  "kind": "SelfSubjectReview",
+  "status": {
+    "userInfo": {
+      "username": "jane.doe",
+      "uid": "b79dbf30-0c6a-11ed-861d-0242ac120002",
+      "groups": [
+        "students",
+        "teachers",
+        "system:authenticated"
+      ],
+      "extra": {
+        "skills": [
+          "reading",
+          "learning"
+        ],
+        "subjects": [
+          "math",
+          "sports"
+        ]
+      }
+    }
+  }
+}
+```
+{{% /tab %}}
+
+{{% tab name="YAML" %}}
+```yaml
+apiVersion: authentication.k8s.io/v1alpha1
+kind: SelfSubjectReview
+status:
+  userInfo:
+    username: jane.doe
+    uid: b79dbf30-0c6a-11ed-861d-0242ac120002
+    groups:
+    - students
+    - teachers
+    - system:authenticated
+    extra:
+      skills:
+      - reading
+      - learning
+      subjects:
+      - math
+      - sports
+```
+{{% /tab %}}
+{{< /tabs >}}
+
+This feature is extremely useful when a complicated authentication flow is used in a Kubernetes cluster, 
+for example, if you use [webhook token authentication](/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) or [authenticating proxy](/docs/reference/access-authn-authz/authentication/#authenticating-proxy).
+
+{{< note >}}
+The Kubernetes API server fills the `userInfo` after all authentication mechanisms are applied,
+including [impersonation](/docs/reference/access-authn-authz/authentication/#user-impersonation).
+If you, or an authentication proxy, make a SelfSubjectReview using impersonation,
+you see the user details and properties for the user that was impersonated.
+{{< /note >}}
+
+By default, all authenticated users can create `SelfSubjectReview` objects when the `APISelfSubjectReview` feature is enabled. It is allowed by the `system:basic-user` cluster role. 
+
+{{< note >}}
+You can only make `SelfSubjectReview` requests if:
+* the `APISelfSubjectReview`
+  [feature gate](/docs/reference/command-line-tools-reference/feature-gates/)
+  is enabled for your cluster
+* the API server for your cluster has the `authentication.k8s.io/v1alpha1`
+  {{< glossary_tooltip term_id="api-group" text="API group" >}}
+  enabled.
+{{< /note >}}
+
+
+
 ## {{% heading "whatsnext" %}}
 
 * Read the [client authentication reference (v1beta1)](/docs/reference/config-api/client-authentication.v1beta1/)

content/en/docs/reference/command-line-tools-reference/feature-gates.md

@@ -62,6 +62,7 @@ For a reference to old feature gates that are removed, please refer to
 | `APIPriorityAndFairness` | `true` | Beta | 1.20 | |
 | `APIResponseCompression` | `false` | Alpha | 1.7 | 1.15 |
 | `APIResponseCompression` | `true` | Beta | 1.16 | |
+| `APISelfSubjectAttributesReview` | `false` | Alpha | 1.26 | |
 | `APIServerIdentity` | `false` | Alpha | 1.20 | |
 | `APIServerTracing` | `false` | Alpha | 1.22 | |
 | `AllowInsecureBackendProxy` | `true` | Beta | 1.17 | |
@@ -387,6 +388,10 @@ Each feature gate is designed for enabling/disabling a specific feature:
 - `APIServerIdentity`: Assign each API server an ID in a cluster.
 - `APIServerTracing`: Add support for distributed tracing in the API server.
   See [Traces for Kubernetes System Components](/docs/concepts/cluster-administration/system-traces) for more details.
+- `APISelfSubjectAttributesReview`: Activate the `SelfSubjectReview` API which allows users
+  to see the requesting subject's authentication information.
+  See [API access to authentication information for a client](/docs/reference/access-authn-authz/authentication/#self-subject-review)
+  for more details.
 - `AdvancedAuditing`: Enable [advanced auditing](/docs/tasks/debug/debug-cluster/audit/#advanced-audit)
 - `AllowInsecureBackendProxy`: Enable the users to skip TLS verification of
   kubelets on Pod log requests.

content/en/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md

@@ -398,6 +398,18 @@ export KUBECONFIG="$KUBECONFIG_SAVED"
 $Env:KUBECONFIG=$ENV:KUBECONFIG_SAVED
 ```
 
+## Check the subject represented by the kubeconfig
+
+It is not always obvious what attributes (username, groups) you will get after authenticating to the cluster. 
+It can be even more challenging if you are managing more than one cluster at the same time.
+
+There is a `kubectl` alpha subcommand command to check subject attributes, such as username,
+for your selected Kubernetes client context: `kubectl alpha auth whoami`.
+
+Read [API access to authentication information for a client](/docs/reference/access-authn-authz/authentication/#self-subject-review)
+to learn about this in more detail.
+
+
 ## {{% heading "whatsnext" %}}
 
 * [Organizing Cluster Access Using kubeconfig Files](/docs/concepts/configuration/organize-cluster-access-kubeconfig/)