mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-25 12:43:23 +00:00
Merge pull request #29350 from ericchiang/kubectl-login-proposal
Automatic merge from submit-queue docs/proposal: add proposal for kubectl login This PR updates https://github.com/kubernetes/features/issues/32 and https://github.com/kubernetes/kubernetes/pull/25758 by adding a proposal for a "kubectl login" command. It's a bit more involved than the implementation discussed with @deads2k in #25758, by proposing a long term goal for the overall subcommand. cc @kubernetes/sig-auth @kubernetes/kubectl
This commit is contained in:
Kubernetes Submit Queue
GitHub
commit
573ad7ac61
249
docs/proposals/kubectl-login.md
Normal file
249
docs/proposals/kubectl-login.md
Normal file
@ -0,0 +1,249 @@
|
|||||||
|
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||||
|
|
||||||
|
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||||
|
|
||||||
|
<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
<img src="http://kubernetes.io/kubernetes/img/warning.png" alt="WARNING"
|
||||||
|
width="25" height="25">
|
||||||
|
|
||||||
|
<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
|
||||||
|
|
||||||
|
If you are using a released version of Kubernetes, you should
|
||||||
|
refer to the docs that go with that version.
|
||||||
|
|
||||||
|
Documentation for other releases can be found at
|
||||||
|
[releases.k8s.io](http://releases.k8s.io).
|
||||||
|
</strong>
|
||||||
|
--
|
||||||
|
|
||||||
|
<!-- END STRIP_FOR_RELEASE -->
|
||||||
|
|
||||||
|
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||||
|
|
||||||
|
# Kubectl Login Subcommand
|
||||||
|
|
||||||
|
**Authors**: Eric Chiang (@ericchiang)
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
|
||||||
|
`kubectl login` is an entrypoint for any user attempting to connect to an
|
||||||
|
existing server. It should provide a more tailored experience than the existing
|
||||||
|
`kubectl config` including config validation, auth challenges, and discovery.
|
||||||
|
|
||||||
|
Short term the subcommand should recognize and attempt to help:
|
||||||
|
|
||||||
|
* New users with an empty configuration trying to connect to a server.
|
||||||
|
* Users with no credentials, by prompt for any required information.
|
||||||
|
* Fully configured users who want to validate credentials.
|
||||||
|
* Users trying to switch servers.
|
||||||
|
* Users trying to reauthenticate as the same user because credentials have expired.
|
||||||
|
* Authenticate as a different user to the same server.
|
||||||
|
|
||||||
|
Long term `kubectl login` should enable authentication strategies to be
|
||||||
|
discoverable from a master to avoid the end-user having to know how their
|
||||||
|
sysadmin configured the Kubernetes cluster.
|
||||||
|
|
||||||
|
## Design
|
||||||
|
|
||||||
|
The "login" subcommand helps users move towards a fully functional kubeconfig by
|
||||||
|
evaluating the current state of the kubeconfig and trying to prompt the user for
|
||||||
|
and validate the necessary information to login to the kubernetes cluster.
|
||||||
|
|
||||||
|
This is inspired by a similar tools such as:
|
||||||
|
|
||||||
|
* [os login](https://docs.openshift.org/latest/cli_reference/get_started_cli.html#basic-setup-and-login)
|
||||||
|
* [gcloud auth login](https://cloud.google.com/sdk/gcloud/reference/auth/login)
|
||||||
|
* [aws configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)
|
||||||
|
|
||||||
|
The steps taken are:
|
||||||
|
|
||||||
|
1. If no cluster configured, prompt user for cluster information.
|
||||||
|
2. If no user is configured, discover the authentication strategies supported by the API server.
|
||||||
|
3. Prompt the user for some information based on the authentication strategy they choose.
|
||||||
|
4. Attempt to login as a user, including authentication challenges such as OAuth2 flows, and display user info.
|
||||||
|
|
||||||
|
Importantly, each step is skipped if the existing configuration is validated or
|
||||||
|
can be supplied without user interaction (refreshing an OAuth token, redeeming
|
||||||
|
a Kerberos ticket, etc.). Users with fully configured kubeconfigs will only see
|
||||||
|
the user they're logged in as, useful for opaque credentials such as X509 certs
|
||||||
|
or bearer tokens.
|
||||||
|
|
||||||
|
The command differs from `kubectl config` by:
|
||||||
|
|
||||||
|
* Communicating with the API server to determine if the user is supplying valid auth events.
|
||||||
|
* Validating input and being opinionated about the input it asks for.
|
||||||
|
* Triggering authentication challenges for example:
|
||||||
|
* Basic auth: Actually try to communicate with the API server.
|
||||||
|
* OpenID Connect: Create an OAuth2 redirect.
|
||||||
|
|
||||||
|
However `kubectl login` should still be seen as a supplement to, not a
|
||||||
|
replacement for, `kubectl config` by helping validate any kubeconfig generated
|
||||||
|
by the latter command.
|
||||||
|
|
||||||
|
## Credential validation
|
||||||
|
|
||||||
|
When clusters utilize authorization plugins access decisions are based on the
|
||||||
|
correct configuration of an auth-N plugin, an auth-Z plugin, and client side
|
||||||
|
credentials. Being rejected then begs several questions. Is the user's
|
||||||
|
kubeconfig mis-configured? Is the authorization plugin setup wrong? Is the user
|
||||||
|
authenticating as a different user than the one they assume?
|
||||||
|
|
||||||
|
To help `kubectl login` diagnose mis-configured credentials, responses from the
|
||||||
|
API server to authenticated requests SHOULD include the `Authentication-Info`
|
||||||
|
header as defined in [RFC 7615](https://tools.ietf.org/html/rfc7615). The value
|
||||||
|
will hold name value pairs for `username` and `uid`. Since usernames and IDs
|
||||||
|
can be arbitrary strings, these values will be escaped using the `quoted-string`
|
||||||
|
format noted in the RFC.
|
||||||
|
|
||||||
|
```
|
||||||
|
HTTP/1.1 200 OK
|
||||||
|
Authentication-Info: username="janedoe@example.com", uid="123456"
|
||||||
|
```
|
||||||
|
|
||||||
|
If the user successfully authenticates this header will be set, regardless of
|
||||||
|
auth-Z decisions. For example a 401 Unauthorized (user didn't provide valid
|
||||||
|
credentials) would lack this header, while a 403 Forbidden response would
|
||||||
|
contain it.
|
||||||
|
|
||||||
|
## Authentication discovery
|
||||||
|
|
||||||
|
A long term goal of `kubectl login` is to facilitate a customized experience
|
||||||
|
for clusters configured with different auth providers. This will require some
|
||||||
|
way for the API server to indicate to `kubectl` how a user is expected to
|
||||||
|
login.
|
||||||
|
|
||||||
|
Currently, this document doesn't propose a specific implementation for
|
||||||
|
discovery. While it'd be preferable to utilize an existing standard (such as the
|
||||||
|
`WWW-Authenticate` HTTP header), discovery may require a solution custom to the
|
||||||
|
API server, such as an additional discovery endpoint with a custom type.
|
||||||
|
|
||||||
|
## Use in non-interactive session
|
||||||
|
|
||||||
|
For the initial implementation, if `kubectl login` requires prompting and is
|
||||||
|
called from a non-interactive session (determined by if the session is using a
|
||||||
|
TTY) it errors out, recommending using `kubectl config` instead. In future
|
||||||
|
updates `kubectl login` may include options for non-interactive sessions so
|
||||||
|
auth strategies which require custom behavior not built into `kubectl config`,
|
||||||
|
such as the exchanges in Kerberos or OpenID Connect, can be triggered from
|
||||||
|
scripts.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
If kubeconfig isn't configured, `kubectl login` will attempt to fully configure
|
||||||
|
and validate the client's credentials.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ kubectl login
|
||||||
|
Cluster URL []: https://172.17.4.99:443
|
||||||
|
Cluster CA [(defaults to host certs)]: ${PWD}/ssl/ca.pem
|
||||||
|
Cluster Name ["cluster-1"]:
|
||||||
|
|
||||||
|
The kubernetes server supports the following methods:
|
||||||
|
|
||||||
|
1. Bearer token
|
||||||
|
2. Username and password
|
||||||
|
3. Keystone
|
||||||
|
4. OpenID Connect
|
||||||
|
5. TLS client certificate
|
||||||
|
|
||||||
|
Enter login method [1]: 4
|
||||||
|
|
||||||
|
Logging in using OpenID Connect.
|
||||||
|
|
||||||
|
Issuer ["valuefromdiscovery"]: https://accounts.google.com
|
||||||
|
Issuer CA [(defaults to host certs)]:
|
||||||
|
Scopes ["profile email"]:
|
||||||
|
Client ID []: client@localhost:foobar
|
||||||
|
Client Secret []: *****
|
||||||
|
|
||||||
|
Open the following address in a browser.
|
||||||
|
|
||||||
|
https://accounts.google.com/o/oauth2/v2/auth?redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scopes=openid%20email&access_type=offline&...
|
||||||
|
|
||||||
|
Enter security code: ****
|
||||||
|
|
||||||
|
Logged in as "janedoe@gmail.com"
|
||||||
|
```
|
||||||
|
|
||||||
|
Human readable names are provided by a combination of the auth providers
|
||||||
|
understood by `kubectl login` and the authenticator discovery. For instance,
|
||||||
|
Keystone uses basic auth credentials in the same way as a static user file, but
|
||||||
|
if the discovery indicates that the Keystone plugin is being used it should be
|
||||||
|
presented to the user differently.
|
||||||
|
|
||||||
|
Users with configured credentials will simply auth against the API server and see
|
||||||
|
who they are. Running this command again simply validates the user's credentials.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ kubectl login
|
||||||
|
Logged in as "janedoe@gmail.com"
|
||||||
|
```
|
||||||
|
|
||||||
|
Users who are halfway through the flow will start where they left off. For
|
||||||
|
instance if a user has configured the cluster field but on a user field, they will
|
||||||
|
be prompted for credentials.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ kubectl login
|
||||||
|
No auth type configured. The kubernetes server supports the following methods:
|
||||||
|
|
||||||
|
1. Bearer token
|
||||||
|
2. Username and password
|
||||||
|
3. Keystone
|
||||||
|
4. OpenID Connect
|
||||||
|
5. TLS client certificate
|
||||||
|
|
||||||
|
Enter login method [1]: 2
|
||||||
|
|
||||||
|
Logging in with basic auth. Enter the following fields.
|
||||||
|
|
||||||
|
Username: janedoe
|
||||||
|
Password: ****
|
||||||
|
|
||||||
|
Logged in as "janedoe@gmail.com"
|
||||||
|
```
|
||||||
|
|
||||||
|
Users who wish to switch servers can provide the `--switch-cluster` flag which
|
||||||
|
will prompt the user for new cluster details and switch the current context. It
|
||||||
|
behaves identically to `kubectl login` when a cluster is not set.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ kubectl login --switch-cluster
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
|
Switching users goes through a similar flow attempting to prompt the user for
|
||||||
|
new credentials to the same server.
|
||||||
|
|
||||||
|
```
|
||||||
|
$ kubectl login --switch-user
|
||||||
|
# ...
|
||||||
|
```
|
||||||
|
|
||||||
|
## Work to do
|
||||||
|
|
||||||
|
Phase 1:
|
||||||
|
|
||||||
|
* Provide a simple dialog for configuring authentication.
|
||||||
|
* Kubectl can trigger authentication actions such as trigging OAuth2 redirects.
|
||||||
|
* Validation of user credentials thought the `Authentication-Info` endpoint.
|
||||||
|
|
||||||
|
Phase 2:
|
||||||
|
|
||||||
|
* Update proposal with auth provider discovery mechanism.
|
||||||
|
* Customize dialog using discovery data.
|
||||||
|
|
||||||
|
Further improvements will require adding more authentication providers, and
|
||||||
|
adapting existing plugins to take advantage of challenge based authentication.
|
||||||
|
|
||||||
|
|
||||||
|
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||||
|
[]()
|
||||||
|
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||||
Loading…
Reference in New Issue
Block a user