kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #24349 from liggitt/tokenreview 

Clarify tokenreview API
This commit is contained in:
Kubernetes Prow Robot 2020-10-07 16:00:15 -07:00 committed by GitHub
parent 11ee97d567 5ff7c64134
commit 0703805305
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 126 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -414,6 +414,8 @@ Webhook authentication is a hook for verifying bearer tokens.
* `--authentication-token-webhook-config-file` a configuration file describing how to access the remote webhook service. * `--authentication-token-webhook-config-file` a configuration file describing how to access the remote webhook service.
* `--authentication-token-webhook-cache-ttl` how long to cache authentication decisions. Defaults to two minutes. * `--authentication-token-webhook-cache-ttl` how long to cache authentication decisions. Defaults to two minutes.
* `--authentication-token-webhook-version` determines whether to use `authentication.k8s.io/v1beta1` or `authentication.k8s.io/v1`
`TokenReview` objects to send/receive information from the webhook. Defaults to `v1beta1`.
The configuration file uses the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) The configuration file uses the [kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
file format. Within the file, `clusters` refers to the remote service and file format. Within the file, `clusters` refers to the remote service and
@ -447,72 +449,167 @@ contexts:
name: webhook name: webhook
``` ```
When a client attempts to authenticate with the API server using a bearer token When a client attempts to authenticate with the API server using a bearer token as discussed [above](#putting-a-bearer-token-in-a-request),
as discussed [above](#putting-a-bearer-token-in-a-request), the authentication webhook POSTs a JSON-serialized `TokenReview` object containing the token to the remote service.
the authentication webhook POSTs a JSON-serialized `authentication.k8s.io/v1beta1` `TokenReview` object containing the token
to the remote service. Kubernetes will not challenge a request that lacks such a header.
Note that webhook API objects are subject to the same [versioning compatibility rules](/docs/concepts/overview/kubernetes-api/) Note that webhook API objects are subject to the same [versioning compatibility rules](/docs/concepts/overview/kubernetes-api/) as other Kubernetes API objects.
as other Kubernetes API objects. Implementers should be aware of looser Implementers should check the `apiVersion` field of the request to ensure correct deserialization,
compatibility promises for beta objects and check the "apiVersion" field of the and **must** respond with a `TokenReview` object of the same version as the request.
request to ensure correct deserialization. Additionally, the API server must
enable the `authentication.k8s.io/v1beta1` API extensions group (`--runtime-config=authentication.k8s.io/v1beta1=true`).
The POST body will be of the following format: {{< tabs name="TokenReview_request" >}}
{{% tab name="authentication.k8s.io/v1" %}}
{{< note >}}
The Kubernetes API server defaults to sending `authentication.k8s.io/v1beta1` token reviews for backwards compatibility.
To opt into receiving `authentication.k8s.io/v1` token reviews, the API server must be started with `--authentication-token-webhook-version=v1`.
{{< /note >}}
```json ```yaml
{
"apiVersion": "authentication.k8s.io/v1",
"kind": "TokenReview",
"spec": {
# Opaque bearer token sent to the API server
"token": "014fbff9a07c...",
# Optional list of the audience identifiers for the server the token was presented to.
# Audience-aware token authenticators (for example, OIDC token authenticators)
# should verify the token was intended for at least one of the audiences in this list,
# and return the intersection of this list and the valid audiences for the token in the response status.
# This ensures the token is valid to authenticate to the server it was presented to.
# If no audiences are provided, the token should be validated to authenticate to the Kubernetes API server.
"audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"]
}
}
```
{{% /tab %}}
{{% tab name="authentication.k8s.io/v1beta1" %}}
```yaml
{ {
"apiVersion": "authentication.k8s.io/v1beta1", "apiVersion": "authentication.k8s.io/v1beta1",
"kind": "TokenReview", "kind": "TokenReview",
"spec": { "spec": {
"token": "(BEARERTOKEN)" # Opaque bearer token sent to the API server
"token": "014fbff9a07c...",
# Optional list of the audience identifiers for the server the token was presented to.
# Audience-aware token authenticators (for example, OIDC token authenticators)
# should verify the token was intended for at least one of the audiences in this list,
# and return the intersection of this list and the valid audiences for the token in the response status.
# This ensures the token is valid to authenticate to the server it was presented to.
# If no audiences are provided, the token should be validated to authenticate to the Kubernetes API server.
"audiences": ["https://myserver.example.com", "https://myserver.internal.example.com"]
} }
} }
``` ```
{{% /tab %}}
{{< /tabs >}}
The remote service is expected to fill the `status` field of The remote service is expected to fill the `status` field of the request to indicate the success of the login.
the request to indicate the success of the login. The response body's `spec` The response body's `spec` field is ignored and may be omitted.
field is ignored and may be omitted. A successful validation of the bearer The remote service must return a response using the same `TokenReview` API version that it received.
token would return: A successful validation of the bearer token would return:
```json {{< tabs name="TokenReview_response_success" >}}
{{% tab name="authentication.k8s.io/v1" %}}
```yaml
{ {
"apiVersion": "authentication.k8s.io/v1beta1", "apiVersion": "authentication.k8s.io/v1",
"kind": "TokenReview", "kind": "TokenReview",
"status": { "status": {
"authenticated": true, "authenticated": true,
"user": { "user": {
# Required
"username": "janedoe@example.com", "username": "janedoe@example.com",
# Optional
"uid": "42", "uid": "42",
"groups": [ # Optional group memberships
"developers", "groups": ["developers", "qa"],
"qa" # Optional additional information provided by the authenticator.
], # This should not contain confidential data, as it can be recorded in logs
# or API objects, and is made available to admission webhooks.
"extra": { "extra": {
"extrafield1": [ "extrafield1": [
"extravalue1", "extravalue1",
"extravalue2" "extravalue2"
] ]
} }
} },
# Optional list audience-aware token authenticators can return,
# containing the audiences from the `spec.audiences` list for which the provided token was valid.
# If this is omitted, the token is considered to be valid to authenticate to the Kubernetes API server.
"audiences": ["https://myserver.example.com"]
} }
} }
``` ```
{{% /tab %}}
An unsuccessful request would return: {{% tab name="authentication.k8s.io/v1beta1" %}}
```yaml
```json
{ {
"apiVersion": "authentication.k8s.io/v1beta1", "apiVersion": "authentication.k8s.io/v1beta1",
"kind": "TokenReview", "kind": "TokenReview",
"status": { "status": {
"authenticated": false "authenticated": true,
"user": {
# Required
"username": "janedoe@example.com",
# Optional
"uid": "42",
# Optional group memberships
"groups": ["developers", "qa"],
# Optional additional information provided by the authenticator.
# This should not contain confidential data, as it can be recorded in logs
# or API objects, and is made available to admission webhooks.
"extra": {
"extrafield1": [
"extravalue1",
"extravalue2"
]
}
},
# Optional list audience-aware token authenticators can return,
# containing the audiences from the `spec.audiences` list for which the provided token was valid.
# If this is omitted, the token is considered to be valid to authenticate to the Kubernetes API server.
"audiences": ["https://myserver.example.com"]
} }
} }
``` ```
{{% /tab %}}
{{< /tabs >}}
HTTP status codes can be used to supply additional error context. An unsuccessful request would return:
{{< tabs name="TokenReview_response_error" >}}
{{% tab name="authentication.k8s.io/v1" %}}
```yaml
{
"apiVersion": "authentication.k8s.io/v1",
"kind": "TokenReview",
"status": {
"authenticated": false,
# Optionally include details about why authentication failed.
# If no error is provided, the API will return a generic Unauthorized message.
# The error field is ignored when authenticated=true.
"error": "Credentials are expired"
}
}
```
{{% /tab %}}
{{% tab name="authentication.k8s.io/v1beta1" %}}
```yaml
{
"apiVersion": "authentication.k8s.io/v1beta1",
"kind": "TokenReview",
"status": {
"authenticated": false,
# Optionally include details about why authentication failed.
# If no error is provided, the API will return a generic Unauthorized message.
# The error field is ignored when authenticated=true.
"error": "Credentials are expired"
}
}
```
{{% /tab %}}
{{< /tabs >}}
### Authenticating Proxy ### Authenticating Proxy