Improve docs (#1250)

* Refactor docs

* Update --exec-api-version

* Add device authorization grant

* Fix

README.md

@@ -30,17 +30,19 @@ kubectl krew install oidc-login
 choco install kubelogin
 ```
 
-If you install via GitHub releases, you need to put the `kubelogin` binary on your path under the name `kubectl-oidc_login` so that the [kubectl plugin mechanism](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/) can find it when you invoke `kubectl oidc-login`. The other install methods do this for you.
+If you install via GitHub releases, save the binary as the name `kubectl-oidc_login` on your path.
+When you invoke `kubectl oidc-login`, kubectl finds it by the [naming convention of kubectl plugins](https://kubernetes.io/docs/tasks/extend-kubectl/kubectl-plugins/).
+The other install methods do this for you.
 
 You need to set up the OIDC provider, cluster role binding, Kubernetes API server and kubeconfig.
-The kubeconfig looks like:
+Your kubeconfig looks like this:
 
 ```yaml
 users:
   - name: oidc
     user:
       exec:
-        apiVersion: client.authentication.k8s.io/v1beta1
+        apiVersion: client.authentication.k8s.io/v1
         command: kubectl
         args:
           - oidc-login
@@ -49,7 +51,7 @@ users:
           - --oidc-client-id=YOUR_CLIENT_ID
 ```
 
-See [setup guide](docs/setup.md) for more.
+See the [setup guide](docs/setup.md) for more.
 
 ### Run
 
@@ -62,27 +64,28 @@ kubectl get pods
 Kubectl executes kubelogin before calling the Kubernetes APIs.
 Kubelogin automatically opens the browser, and you can log in to the provider.
 
-<img src="docs/keycloak-login.png" alt="keycloak-login" width="455" height="329">
+After the authentication, kubelogin returns the credentials to kubectl.
+Kubectl then calls the Kubernetes APIs with the credentials.
 
-After authentication, kubelogin returns the credentials to kubectl and kubectl then calls the Kubernetes APIs with these credentials.
-
-```
+```console
 % kubectl get pods
 Open http://localhost:8000 for authentication
 NAME                          READY   STATUS    RESTARTS   AGE
 echoserver-86c78fdccd-nzmd5   1/1     Running   0          26d
 ```
 
-Kubelogin stores the ID token and refresh token to the token cache storage.
-If the OS keyring is available, it stores the token cache to the keyring.
-Otherwise, it stores the token cache to the file system.
-
-Kubelogin refreshes the expired token cache.
+Kubelogin stores the ID token and refresh token to the cache.
 If the ID token is valid, it just returns it.
 If the ID token has expired, it will refresh the token using the refresh token.
 If the refresh token has expired, it will perform re-authentication.
 
-### Troubleshoot
+## Troubleshooting
+
+### Token cache
+
+If the OS keyring is available, kubelogin stores the token cache to the OS keyring.
+Otherwise, kubelogin stores the token cache to the file system.
+See the [token cache](docs/usage.md#token-cache) for details.
 
 You can log out by deleting the token cache.
 
@@ -95,10 +98,12 @@ Deleted the token cache in the keyring
 Kubelogin will ask you to log in via the browser again.
 If the browser has a cookie for the provider, you need to log out from the provider or clear the cookie.
 
-You can dump claims of an ID token by `setup` command.
+### ID token claims
+
+You can run `setup` command to dump the claims of an ID token from the provider.
 
 ```console
-% kubectl oidc-login setup --oidc-issuer-url https://accounts.google.com --oidc-client-id REDACTED
+% kubectl oidc-login setup --oidc-issuer-url=ISSUER_URL --oidc-client-id=REDACTED
 ...
 You got a token with the following claims:
 
@@ -110,22 +115,22 @@ You got a token with the following claims:
 }
 ```
 
-You can increase the log level by `-v1` option.
+You can set `-v1` option to increase the log level.
 
 ```yaml
 users:
   - name: oidc
     user:
       exec:
-        apiVersion: client.authentication.k8s.io/v1beta1
+        apiVersion: client.authentication.k8s.io/v1
         command: kubectl
         args:
           - oidc-login
           - get-token
           - -v1
 ```
 
-You can verify kubelogin works with your provider using [acceptance test](acceptance_test).
+You can run the [acceptance test](acceptance_test) to verify if kubelogin works with your provider.
 
 ## Docs
 
@@ -139,6 +144,3 @@ You can verify kubelogin works with your provider using [acceptance test](accept
 
 This is an open source software licensed under Apache License 2.0.
 Feel free to open issues and pull requests for improving code and documents.
-
-This software is developed with [GoLand](https://www.jetbrains.com/go/) licensed for open source development.
-Special thanks for the support.

docs/setup.md

@@ -12,6 +12,14 @@ Let's see the following steps:
 
 ## 1. Set up the OIDC provider
 
+Kubelogin supports the following authentication flows:
+
+- Authorization code flow
+- Device authorization grant
+- Resource owner password credentials grant
+
+See the [usage](usage.md) for the details.
+
 ### Google Identity Platform
 
 You can log in with a Google account.
@@ -23,10 +31,10 @@ Open [Google APIs Console](https://console.developers.google.com/apis/credential
 Check the client ID and secret.
 Replace the following variables in the later sections.
 
-| Variable             | Value                            |
-| -------------------- | -------------------------------- |
-| `ISSUER_URL`         | `https://accounts.google.com`    |
-| `YOUR_CLIENT_ID`     | `xxx.apps.googleusercontent.com` |
+| Variable         | Value                            |
+| ---------------- | -------------------------------- |
+| `ISSUER_URL`     | `https://accounts.google.com`    |
+| `YOUR_CLIENT_ID` | `xxx.apps.googleusercontent.com` |
 
 ### Keycloak
 
@@ -54,10 +62,10 @@ For example, if you have `admin` role of the client, you will get a JWT with the
 
 Replace the following variables in the later sections.
 
-| Variable             | Value                                                 |
-| -------------------- | ----------------------------------------------------- |
-| `ISSUER_URL`         | `https://keycloak.example.com/auth/realms/YOUR_REALM` |
-| `YOUR_CLIENT_ID`     | `YOUR_CLIENT_ID`                                      |
+| Variable         | Value                                                 |
+| ---------------- | ----------------------------------------------------- |
+| `ISSUER_URL`     | `https://keycloak.example.com/auth/realms/YOUR_REALM` |
+| `YOUR_CLIENT_ID` | `YOUR_CLIENT_ID`                                      |
 
 ### Dex with GitHub
 
@@ -187,31 +195,13 @@ Add the following flags to kube-apiserver:
 
 See [Kubernetes Authenticating: OpenID Connect Tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) for the all flags.
 
-If you are using [kops](https://github.com/kubernetes/kops), run `kops edit cluster` and append the following settings:
-
-```yaml
-spec:
-  kubeAPIServer:
-    oidcIssuerURL: ISSUER_URL
-    oidcClientID: YOUR_CLIENT_ID
-```
-
-If you are using [kube-aws](https://github.com/kubernetes-incubator/kube-aws), append the following settings to the `cluster.yaml`:
-
-```yaml
-oidc:
-  enabled: true
-  issuerUrl: ISSUER_URL
-  clientId: YOUR_CLIENT_ID
-```
-
 ## 5. Set up the kubeconfig
 
 Add `oidc` user to the kubeconfig.
 
 ```sh
 kubectl config set-credentials oidc \
-  --exec-api-version=client.authentication.k8s.io/v1beta1 \
+  --exec-api-version=client.authentication.k8s.io/v1 \
   --exec-command=kubectl \
   --exec-arg=oidc-login \
   --exec-arg=get-token \

docs/usage.md

@@ -108,7 +108,7 @@ See also [net/http#ProxyFromEnvironment](https://golang.org/pkg/net/http/#ProxyF
 Kubelogin stores the token cache to the OS keyring if available.
 It depends on [zalando/go-keyring](https://github.com/zalando/go-keyring) for the keyring storage.
 
-You can enforce the storage by `--token-cache-storage`.
+If you encounter a problem, try `--token-cache-storage` to set the storage.
 
 ```yaml
 # Force to use the OS keyring
@@ -130,13 +130,14 @@ If a value in the following options begins with a tilde character `~`, it is exp
 
 Kubelogin support the following flows:
 
-- Authorization code flow
-- Authorization code flow with a keyboard
-- Resource owner password credentials grant flow
+- [Authorization code flow](#authorization-code-flow)
+- [Authorization code flow with a keyboard](#authorization-code-flow-with-a-keyboard)
+- [Device authorization grant](#device-authorization-grant)
+- [Resource owner password credentials grant](#resource-owner-password-credentials-grant)
 
 ### Authorization code flow
 
-Kubelogin performs the authorization code flow by default.
+Kubelogin performs the [authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) by default.
 
 It starts the local server at port 8000 or 18000 by default.
 You need to register the following redirect URIs to the provider:
@@ -177,14 +178,15 @@ You can change the URL to show after authentication.
 - --open-url-after-authentication=https://example.com/success.html
 ```
 
-You can skip opening the browser if you encounter some environment problem.
+If you encounter a problem with the browser, you can change the browser command or skip opening the browser.
 
 ```yaml
+# Change the browser command
+- --browser-command=google-chrome
+# Do not open the browser
 - --skip-open-browser
 ```
 
-For Linux users, you change the default browser by `BROWSER` environment variable.
-
 ### Authorization code flow with a keyboard
 
 If you cannot access the browser, instead use the authorization code flow with a keyboard.
@@ -215,13 +217,34 @@ You can add extra parameters to the authentication request.
 - --oidc-auth-request-extra-params=ttl=86400
 ```
 
-### Resource owner password credentials grant flow
+### Device authorization grant
+
+Kubelogin performs the [device authorization grant](https://tools.ietf.org/html/rfc8628) when `--grant-type=device-code` is set.
+
+```yaml
+- --grant-type=device-code
+```
+
+It automatically opens the browser.
+If the provider returns the `verification_uri_complete` parameter, you don't need to enter the code.
+Otherwise, you need to enter the code shown.
+
+If you encounter a problem with the browser, you can change the browser command or skip opening the browser.
+
+```yaml
+# Change the browser command
+- --browser-command=google-chrome
+# Do not open the browser
+- --skip-open-browser
+```
+
+### Resource owner password credentials grant
 
-Kubelogin performs the resource owner password credentials grant flow
+Kubelogin performs the resource owner password credentials grant
 when `--grant-type=password` or `--username` is set.
 
-Note that most OIDC providers do not support this flow.
-Keycloak supports this flow but you need to explicitly enable the "Direct Access Grants" feature in the client settings.
+Note that most OIDC providers do not support this grant.
+Keycloak supports this grant but you need to explicitly enable the "Direct Access Grants" feature in the client settings.
 
 You can set the username and password.
 
@@ -263,7 +286,7 @@ users:
   - name: oidc
     user:
       exec:
-        apiVersion: client.authentication.k8s.io/v1beta1
+        apiVersion: client.authentication.k8s.io/v1
         command: docker
         args:
           - run

pkg/usecases/setup/stage2.go

@@ -37,7 +37,7 @@ Add the following options to the kube-apiserver:
 Run the following command:
 
 	kubectl config set-credentials oidc \
-	  --exec-api-version=client.authentication.k8s.io/v1beta1 \
+	  --exec-api-version=client.authentication.k8s.io/v1 \
 	  --exec-command=kubectl \
 	  --exec-arg=oidc-login \
 	  --exec-arg=get-token \

system_test/login/Makefile

@@ -9,15 +9,16 @@ export KUBECONFIG
 
 .PHONY: test
 test: build
-	# see the setup instruction
+	# See the setup instruction.
 	kubectl oidc-login setup \
 		--oidc-issuer-url=https://dex-server:10443/dex \
 		--oidc-client-id=YOUR_CLIENT_ID \
 		--oidc-client-secret=YOUR_CLIENT_SECRET \
 		--oidc-extra-scope=email \
 		--certificate-authority=$(CERT_DIR)/ca.crt \
 		--browser-command=$(BIN_DIR)/chromelogin
-	# set up the kubeconfig
+
+	# Set up the kubeconfig.
 	kubectl config set-credentials oidc \
 		--exec-api-version=client.authentication.k8s.io/v1 \
 		--exec-interactive-mode=Never \
@@ -30,7 +31,11 @@ test: build
 		--exec-arg=--oidc-extra-scope=email \
 		--exec-arg=--certificate-authority=$(CERT_DIR)/ca.crt \
 		--exec-arg=--browser-command=$(BIN_DIR)/chromelogin
-	# make sure we can access the cluster
+
+	# Show the kubeconfig.
+	kubectl config view
+
+	# Test the authentication.
 	kubectl --user=oidc cluster-info
 
 .PHONY: build