Skip to content

Commit

Permalink
client exec auth: updates for 1.11 (#9154)
Browse files Browse the repository at this point in the history
  • Loading branch information
liggitt authored and Misty Linville committed Jun 27, 2018
1 parent cb820ce commit fa75933
Showing 1 changed file with 27 additions and 51 deletions.
78 changes: 27 additions & 51 deletions content/en/docs/reference/access-authn-authz/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -675,7 +675,7 @@ rules:

## client-go credential plugins

{{< feature-state for_k8s_version="v1.10" state="alpha" >}}
{% assign for_k8s_version="v1.11" %}{% include feature-state-beta.md %}

`k8s.io/client-go` and tools using it such as `kubectl` and `kubelet` are able to execute an
external command to receive user credentials.
Expand All @@ -686,8 +686,6 @@ protocol specific logic, then returns opaque credentials to use. Almost all cred
use cases require a server side component with support for the [webhook token authenticator](#webhook-token-authentication)
to interpret the credential format produced by the client plugin.

As of 1.10 only bearer tokens are supported. Support for client certs may be added in a future release.

### Example use case

In a hypothetical use case, an organization would run an external service that exchanges LDAP credentials
Expand Down Expand Up @@ -718,11 +716,13 @@ users:
# Command to execute. Required.
command: "example-client-go-exec-plugin"
# API version to use when encoding and decoding the ExecCredentials
# resource. Required.
# API version to use when decoding the ExecCredentials resource. Required.
#
# The API version returned by the plugin MUST match the version listed here.
#
# The API version returned by the plugin MUST match the version encoded.
apiVersion: "client.authentication.k8s.io/v1alpha1"
# To integrate with tools that support multiple versions (such as client.authentication.k8s.io/v1alpha1),
# set an environment variable or pass an argument to the tool that indicates which version the exec plugin expects.
apiVersion: "client.authentication.k8s.io/v1beta1"
# Environment variables to set when executing the plugin. Optional.
env:
Expand Down Expand Up @@ -756,88 +756,64 @@ the binary `/home/jane/bin/example-client-go-exec-plugin` is executed.
exec:
# Path relative to the directory of the kubeconfig
command: "./bin/example-client-go-exec-plugin"
apiVersion: "client.authentication.k8s.io/v1alpha1"
apiVersion: "client.authentication.k8s.io/v1beta1"
```

### Input and output formats

When executing the command, `k8s.io/client-go` sets the `KUBERNETES_EXEC_INFO` environment
variable to a JSON serialized [`ExecCredential`](
https://github.com/kubernetes/client-go/blob/master/pkg/apis/clientauthentication/v1alpha1/types.go)
resource.

```
KUBERNETES_EXEC_INFO='{
"apiVersion": "client.authentication.k8s.io/v1alpha1",
"kind": "ExecCredential",
"spec": {
"interactive": true
}
}'
```
The executed command prints an `ExecCredential` object to `stdout`. `k8s.io/client-go`
authenticates against the Kubernetes API using the returned credentials in the `status`.

When plugins are executed from an interactive session, `stdin` and `stderr` are directly
exposed to the plugin so the user can provide input for interactive logins.
When run from an interactive session, `stdin` is exposed directly to the plugin. Plugins should use a
[TTY check](https://godoc.org/golang.org/x/crypto/ssh/terminal#IsTerminal) to determine if it's
appropriate to prompt a user interactively.

When responding to a 401 HTTP status code, which indicates invalid credentials, this object
includes metadata about the response.
To use bearer token credentials, the plugin returns a token in the status of the `ExecCredential`.

```json
{
"apiVersion": "client.authentication.k8s.io/v1alpha1",
"apiVersion": "client.authentication.k8s.io/v1beta1",
"kind": "ExecCredential",
"spec": {
"response": {
"code": 401,
"header": {
"WWW-Authenticate": [
"Bearer realm=ldap.example.com"
]
},
},
"interactive": true
"status": {
"token": "my-bearer-token"
}
}
```

After the plugin outputs an `ExecCredential` structure to `stdout`, the `k8s.io/client-go` library
looks for a bearer token or client TLS key and certificate (or all three) in the
`status` field and uses it to authenticate against the Kubernetes API. The library can
use a bearer token on its own (`token`), a client TLS key and certificate
(`clientKeyData` and `clientCertificateData`; both must be present), or a combination
of both methods. `clientCertificateData` may contain additional intermediate
certificates to send to the server.
Alternatively, a PEM-encoded client certificate and key can be returned to use TLS client auth.
If the plugin returns a different certificate and key on a subsequent call, `k8s.io/client-go`
will close existing connections with the server to force a new TLS handshake.

If specified, `clientKeyData` and `clientCertificateData` must both must be present.

`clientCertificateData` may contain additional intermediate certificates to send to the server.

```json
{
"apiVersion": "client.authentication.k8s.io/v1alpha1",
"apiVersion": "client.authentication.k8s.io/v1beta1",
"kind": "ExecCredential",
"status": {
"token": "my-bearer-token",
"clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----"
}
}
```

Optionally, the response can include the expiry of the credential formatted as a
RFC3339 timestamp. Presence or absense of an expiry has the following impact:
RFC3339 timestamp. Presence or absence of an expiry has the following impact:

- If an expiry is included, the bearer token and TLS credentials are cached until
the expiry time is reached, or if the server responds with a 401 HTTP status code,
or when the process exits.
- If an expiry is omitted, the bearer token and TLS credentials are cached until
the server responds with a 401 HTTP status code or until the process exits.


```json
{
"apiVersion": "client.authentication.k8s.io/v1alpha1",
"apiVersion": "client.authentication.k8s.io/v1beta1",
"kind": "ExecCredential",
"status": {
"token": "my-bearer-token",
"clientCertificateData": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----",
"clientKeyData": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
"expirationTimestamp": "2018-03-05T17:30:20-08:00"
}
}
Expand Down

0 comments on commit fa75933

Please sign in to comment.