diff --git a/README.md b/README.md index 1364b21..38533af 100644 --- a/README.md +++ b/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. -keycloak-login +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,14 +115,14 @@ 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 @@ -125,7 +130,7 @@ users: - -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. diff --git a/docs/keycloak-login.png b/docs/keycloak-login.png deleted file mode 100644 index 2bfe1cd..0000000 Binary files a/docs/keycloak-login.png and /dev/null differ diff --git a/docs/setup.md b/docs/setup.md index d839620..e16f5aa 100644 --- a/docs/setup.md +++ b/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 \ diff --git a/docs/usage.md b/docs/usage.md index c00e4bb..5105db8 100644 --- a/docs/usage.md +++ b/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 resource owner password credentials grant flow +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 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 diff --git a/pkg/usecases/setup/stage2.go b/pkg/usecases/setup/stage2.go index 14a8be7..5e80e76 100644 --- a/pkg/usecases/setup/stage2.go +++ b/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 \ diff --git a/system_test/login/Makefile b/system_test/login/Makefile index 7a7c8c8..99c7e03 100644 --- a/system_test/login/Makefile +++ b/system_test/login/Makefile @@ -9,7 +9,7 @@ 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 \ @@ -17,7 +17,8 @@ test: build --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