github/kubelogin
1
0
Fork 0
mirror of https://github.com/int128/kubelogin.git synced 2026-08-23 21:06:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve docs (#1250)

Browse Source 
* Refactor docs

* Update --exec-api-version

* Add device authorization grant

* Fix
This commit is contained in:
Hidetake Iwata
2025-01-19 15:02:02 +09:00
committed by GitHub
parent e7819f15eb
commit a2a6ea229d
6 changed files with 86 additions and 66 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+24 -22
View File
@@ -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,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.
docs/keycloak-login.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 278 KiB

docs/setup.md
+17 -27
View File
@@ -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
+36 -13
View File
@@ -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
pkg/usecases/setup/stage2.go
+1 -1
View File
@@ -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
+8 -3
View File
@@ -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