From f3e5318ce61afd4c534cd4c875505e12e8b951f8 Mon Sep 17 00:00:00 2001 From: Eric Chiang Date: Tue, 5 Jun 2018 16:22:12 -0700 Subject: [PATCH] client exec auth: updates for 1.11 --- .../access-authn-authz/authentication.md | 78 +++++++------------ 1 file changed, 27 insertions(+), 51 deletions(-) diff --git a/content/en/docs/reference/access-authn-authz/authentication.md b/content/en/docs/reference/access-authn-authz/authentication.md index c186cc8cf9594..fadcb79ef4af1 100644 --- a/content/en/docs/reference/access-authn-authz/authentication.md +++ b/content/en/docs/reference/access-authn-authz/authentication.md @@ -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. @@ -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 @@ -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: @@ -745,64 +745,43 @@ 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 key pair can be returned to use TLS client auth. +If the plugin returns a different key pair 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-----" } @@ -810,7 +789,7 @@ certificates to send to the server. ``` 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, @@ -818,15 +797,12 @@ RFC3339 timestamp. Presence or absense of an expiry has the following impact: - 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" } }