Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

client exec auth: updates for 1.11 #9154

Merged
merged 1 commit into from
Jun 19, 2018
Merged

client exec auth: updates for 1.11 #9154

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 27 additions & 51 deletions content/en/docs/reference/access-authn-authz/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -664,7 +664,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 @@ -675,8 +675,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 @@ -707,11 +705,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 @@ -745,88 +745,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/cient-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