* the prefix to append to all extra headers via `--requestheader-extra-headers-prefix`

These header names are also placed in the `extension-apiserver-authentication` configmap,
so they can be retrieved and used by extension apiservers.

### Extension Apiserver Authenticates the Request

The extension apiserver, upon receiving a proxied request from the Kubernetes apiserver,
must validate that the request actually did come from a valid authenticating proxy,
which role the Kubernetes apiserver is fulfilling. The extension apiserver validates it via:

1. Retrieve the following from the configmap in `kube-system`, as described above:
    * Client CA certificate
    * List of allowed names (CNs)
    * Header names for username, group and extra info
2. Check that the TLS connection was authenticated using a client certificate which:
    * Was signed by the CA whose certificate matches the retrieved CA certificate.
    * Has a CN in the list of allowed CNs, unless the list is blank, in which case all CNs are allowed.
    * Extract the username and group from the appropriate headers

If the above passes, then the request is a valid proxied request from a legitimate
authenticating proxy, in this case the Kubernetes apiserver.

Note that it is the responsibility of the extension apiserver implementation to provide
the above. Many do it by default, leveraging the `k8s.io/apiserver/` package.
Others may provide options to override it using command-line options.

In order to have permission to retrieve the configmap, an extension apiserver
requires the appropriate role. There is a default role named `extension-apiserver-authentication-reader`
in the `kube-system` namespace which can be assigned.

### Extension Apiserver Authorizes the Request

The extension apiserver now can validate that the user/group retrieved from
the headers are authorized to execute the given request. It does so by sending
a standard [SubjectAccessReview](/docs/reference/access-authn-authz/authorization/)
request to the Kubernetes apiserver. 

In order for the extension apiserver to be authorized itself to submit the
`SubjectAccessReview` request to the Kubernetes apiserver, it needs the correct permissions.
Kubernetes includes a default `ClusterRole` named `system:auth-delegator` that
has the appropriate permissions. It can be granted to the extension apiserver's service account.

### Extension Apiserver Executes

If the `SubjectAccessReview` passes, the extension apiserver executes the request.


## Enable Kubernetes Apiserver flags

Enable the aggregation layer via the following `kube-apiserver` flags.
They may have already been taken care of by your provider.

    --requestheader-client-ca-file=<path to aggregator CA cert>
    --requestheader-allowed-names=front-proxy-client
    --requestheader-extra-headers-prefix=X-Remote-Extra-
    --requestheader-group-headers=X-Remote-Group
    --requestheader-username-headers=X-Remote-User
    --proxy-client-cert-file=<path to aggregator proxy cert>
    --proxy-client-key-file=<path to aggregator proxy key>

### CA Reusage and Conflicts

The Kubernetes apiserver has two client CA options:

* `--client-ca-file`
* `--requestheader-client-ca-file`

Each of these functions independently and can conflict with each other,
if not used correctly.

* `--client-ca-file`: When a request arrives to the Kubernetes apiserver,
  if this option is enabled, the Kubernetes apiserver checks the certificate
  of the request. If it is signed by one of the CA certificates in the file referenced by
  `--client-ca-file`, then the request is treated as a legitimate request,
  and the user is the value of the common name `CN=`, while the group is the organization `O=`.
  See the [documentation on TLS authentication](/docs/reference/access-authn-authz/authentication/#x509-client-certificates).
* `--requestheader-client-ca-file`: When a request arrives to the Kubernetes apiserver,
  if this option is enabled, the Kubernetes apiserver checks the certificate of the request.