github/kubelogin
1
0
Fork 0
mirror of https://github.com/int128/kubelogin.git synced 2026-02-14 16:39:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Refactor docs (#138)

Browse Source 
* Refactor: extract standalone-mode.md

* Refactor: remove diagram

* Refactor: remove DESIGN.md

* Refactor: change README.md
This commit is contained in:
Hidetake Iwata
2019-08-27 11:51:48 +09:00
committed by GitHub
parent 3e30346c9b
commit d9b8d99fae
6 changed files with 193 additions and 268 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
DESIGN.md
View File

@@ -1,47 +0,0 @@
# Design of kubelogin
This explains design of kubelogin.
## Use cases
Kubelogin is a command line tool and designed to run as both a standalone command and a kubectl plugin.
It respects the following flags, commonly used in kubectl:
```
--kubeconfig string Path to the kubeconfig file
--context string The name of the kubeconfig context to use
--user string The name of the kubeconfig user to use. Prior to --context
--certificate-authority string Path to a cert file for the certificate authority
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-v, --v int If set to 1 or greater, it shows debug log
```
As well as it respects the environment variable `KUBECONFIG`.
### Login by the command
TODO
## Architecture
Kubelogin consists of the following layers:
- `usecases`: This provides the use-cases.
- `adaptor`: This provides external access and converts objects between the use-cases and external system.
### Use-cases
This provides the use-cases mentioned in the previous section.
This layer should not contain external access such as HTTP requests and system calls.
### Adaptor
This provides external access such as command line interface and HTTP requests.

5
Makefile
View File

@@ -20,11 +20,6 @@ $(TARGET_PLUGIN): $(TARGET)
run: $(TARGET_PLUGIN)
-PATH=.:$(PATH) kubectl oidc-login --help
diagram: docs/authn.png
%.png: %.seqdiag
seqdiag -a -f /Library/Fonts/Verdana.ttf $<
dist:
VERSION=$(CIRCLE_TAG) goxzst -d dist/gh/ -o "$(TARGET)" -t "kubelogin.rb oidc-login.yaml" -- -ldflags "$(LDFLAGS)"
mv dist/gh/kubelogin.rb dist/

225
README.md
View File

@@ -9,7 +9,9 @@ Then kubelogin gets a token from the provider and kubectl access Kubernetes APIs
## Getting Started
You can install the latest release from [Homebrew](https://brew.sh/), [Krew](https://github.com/kubernetes-sigs/krew) or [GitHub Releases](https://github.com/int128/kubelogin/releases) as follows:
### Setup
Install the latest release from [Homebrew](https://brew.sh/), [Krew](https://github.com/kubernetes-sigs/krew) or [GitHub Releases](https://github.com/int128/kubelogin/releases) as follows:
```sh
# Homebrew
@@ -24,25 +26,16 @@ unzip kubelogin_linux_amd64.zip
ln -s kubelogin kubectl-oidc_login
```
You need to configure the OIDC provider, Kubernetes API server, kubeconfig and role binding.
You need to configure the OIDC provider, Kubernetes API server and role binding.
See the following documents for more:
- [Getting Started with Keycloak](docs/keycloak.md)
- [Getting Started with dex and GitHub](docs/dex.md)
- [Getting Started with Google Identity Platform](docs/google.md)
You can run kubelogin as the following methods:
- Credential plugin mode (recommended)
- Standalone mode
### Credential plugin mode
You can run kubelogin as a [client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
This provides transparent login without manually running `kubelogin` command.
Configure the kubeconfig like:
Configure the kubeconfig to run kubelogin as a [client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
It provides transparent login without manually running kubelogin command.
For example,
```yaml
users:
@@ -59,6 +52,8 @@ users:
- --oidc-client-secret=YOUR_CLIENT_SECRET
```
### Run
Run kubectl.
```sh
@@ -89,90 +84,17 @@ If the refresh token has expired, kubelogin will perform reauthentication.
You can log out by removing the token cache directory (default `~/.kube/cache/oidc-login`).
Kubelogin will perform authentication if the token cache file does not exist.
### Standalone mode
You can run kubelogin as a standalone command.
In this method, you need to manually run the command before running kubectl.
Configure the kubeconfig like:
```yaml
- name: keycloak
user:
auth-provider:
config:
client-id: YOUR_CLIENT_ID
client-secret: YOUR_CLIENT_SECRET
idp-issuer-url: https://issuer.example.com
name: oidc
```
Run kubelogin:
```sh
kubelogin
# or run as a kubectl plugin
kubectl oidc-login
```
It 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 authentication, kubelogin writes the ID token and refresh token to the kubeconfig.
```
% kubelogin
Open http://localhost:8000 for authentication
You got a valid token until 2019-05-18 10:28:51 +0900 JST
Updated ~/.kubeconfig
```
Now you can access the cluster.
```
% kubectl get pods
NAME READY STATUS RESTARTS AGE
echoserver-86c78fdccd-nzmd5 1/1 Running 0 26d
```
Your kubeconfig looks like:
```yaml
users:
- name: keycloak
user:
auth-provider:
config:
client-id: YOUR_CLIENT_ID
client-secret: YOUR_CLIENT_SECRET
idp-issuer-url: https://issuer.example.com
id-token: ey... # kubelogin will add or update the ID token here
refresh-token: ey... # kubelogin will add or update the refresh token here
name: oidc
```
If the ID token is valid, kubelogin does nothing.
```
% kubelogin
You already have a valid token until 2019-05-18 10:28:51 +0900 JST
```
If the ID token has expired, kubelogin will refresh the token using the refresh token in the kubeconfig.
If the refresh token has expired, kubelogin will proceed the authentication.
As well as you can update the ID token in the kubeconfig by running the command.
See [standalone mode](docs/standalone-mode.md) for more.
## Configuration
## Usage
This document is for the development version.
If you are looking for a specific version, see [the release tags](https://github.com/int128/kubelogin/tags).
### Credential plugin mode
Kubelogin supports the following options:
```
@@ -198,7 +120,9 @@ Flags:
-h, --help help for get-token
```
#### Extra scopes
See also the options in [standalone mode](docs/standalone-mode.md).
### Extra scopes
You can set the extra scopes to request to the provider by `--oidc-extra-scope`.
@@ -207,110 +131,14 @@ You can set the extra scopes to request to the provider by `--oidc-extra-scope`.
- --oidc-extra-scope=profile
```
#### CA Certificates
### CA Certificates
You can use your self-signed certificates for the provider.
You can use your self-signed certificate for the provider.
```yaml
- --certificate-authority=/home/user/.kube/keycloak-ca.pem
```
### Standalone mode
Kubelogin supports the following options:
```
% kubelogin -h
Login to the OpenID Connect provider and update the kubeconfig
Usage:
kubelogin [flags]
kubelogin [command]
Examples:
# Login to the provider using the authorization code flow.
kubelogin
# Login to the provider using the resource owner password credentials flow.
kubelogin --username USERNAME --password PASSWORD
# Run as a credential plugin.
kubelogin get-token --oidc-issuer-url=https://issuer.example.com
Available Commands:
get-token Run as a kubectl credential plugin
help Help about any command
version Print the version information
Flags:
--kubeconfig string Path to the kubeconfig file
--context string The name of the kubeconfig context to use
--user string The name of the kubeconfig user to use. Prior to --context
--certificate-authority string Path to a cert file for the certificate authority
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-v, --v int If set to 1 or greater, it shows debug log
--listen-port ints Port to bind to the local server. If multiple ports are given, it will try the ports in order (default [8000,18000])
--skip-open-browser If true, it does not open the browser on authentication
--username string If set, perform the resource owner password credentials grant
--password string If set, use the password instead of asking it
-h, --help help for kubelogin
```
#### Kubeconfig
You can set path to the kubeconfig file by the option or the environment variable just like kubectl.
It defaults to `~/.kube/config`.
```sh
# by the option
kubelogin --kubeconfig /path/to/kubeconfig
# by the environment variable
KUBECONFIG="/path/to/kubeconfig1:/path/to/kubeconfig2" kubelogin
```
If you set multiple files, kubelogin will find the file which has the current authentication (i.e. `user` and `auth-provider`) and write a token to it.
Kubelogin supports the following keys of `auth-provider` in a kubeconfig.
See [kubectl authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#using-kubectl) for more.
Key | Direction | Value
----|-----------|------
`idp-issuer-url` | Read (Mandatory) | Issuer URL of the provider.
`client-id` | Read (Mandatory) | Client ID of the provider.
`client-secret` | Read (Mandatory) | Client Secret of the provider.
`idp-certificate-authority` | Read | CA certificate path of the provider.
`idp-certificate-authority-data` | Read | Base64 encoded CA certificate of the provider.
`extra-scopes` | Read | Scopes to request to the provider (comma separated).
`id-token` | Write | ID token got from the provider.
`refresh-token` | Write | Refresh token got from the provider.
#### Extra scopes
You can set the extra scopes to request to the provider by `extra-scopes` in the kubeconfig.
```sh
kubectl config set-credentials keycloak --auth-provider-arg extra-scopes=email
```
Currently kubectl does not accept multiple scopes, so you need to edit the kubeconfig as like:
```sh
kubectl config set-credentials keycloak --auth-provider-arg extra-scopes=SCOPES
sed -i '' -e s/SCOPES/email,profile/ $KUBECONFIG
```
#### CA Certificates
You can use your self-signed certificates for the provider.
```sh
kubectl config set-credentials keycloak \
--auth-provider-arg idp-certificate-authority=$HOME/.kube/keycloak-ca.pem
```
### HTTP Proxy
You can set the following environment variables if you are behind a proxy: `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY`.
@@ -331,15 +159,11 @@ You need to register the following redirect URIs to the provider:
You can change the ports by the option:
```sh
# run as a standalone command
kubelogin --listen-port 12345 --listen-port 23456
# run as a credential plugin
kubelogin get-token --listen-port 12345 --listen-port 23456
```yaml
- --listen-port 12345
- --listen-port 23456
```
#### Resource owner password credentials grant flow
As well as you can use the resource owner password credentials grant flow.
@@ -348,11 +172,12 @@ Most OIDC providers do not support this flow.
You can pass the username and password:
```
% kubelogin --username USER --password PASS
```yaml
- --username USERNAME
- --password PASSWORD
```
or use the password prompt:
If the password is not set, kubelogin will show the prompt.
```
% kubelogin --username USER
@@ -360,7 +185,7 @@ Password:
```
## Related topics
## Related works
### Kubernetes Dashboard

BIN
docs/authn.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 65 KiB

16
docs/authn.seqdiag
View File

@@ -1,16 +0,0 @@
seqdiag {
User -> kubelogin [label = "execute"];
kubelogin -> Browser [label = "open"];
Browser -> Provider [label = "authentication request"];
Browser <-- Provider [label = "redirect"];
User -> Browser [label = "enter credentials"];
Browser -> Provider [label = "credentials"];
Browser <-- Provider [label = "authentication response"];
User <-- Browser [label = "success"];
kubelogin <-- Browser [label = "close"];
kubelogin -> Provider [label = "token request"];
kubelogin <-- Provider [label = "token response"];
kubelogin -> kubeconfig [label = "write token"];
kubelogin <-- kubeconfig;
User <-- kubelogin;
}

168
docs/standalone-mode.md Normal file
View File

@@ -0,0 +1,168 @@
# Standalone mode
You can run kubelogin as a standalone command.
In this mode, you need to manually run the command before running kubectl.
Configure the kubeconfig like:
```yaml
- name: keycloak
user:
auth-provider:
config:
client-id: YOUR_CLIENT_ID
client-secret: YOUR_CLIENT_SECRET
idp-issuer-url: https://issuer.example.com
name: oidc
```
Run kubelogin:
```sh
kubelogin
# or run as a kubectl plugin
kubectl oidc-login
```
It automatically opens the browser and you can log in to the provider.
<img src="keycloak-login.png" alt="keycloak-login" width="455" height="329">
After authentication, kubelogin writes the ID token and refresh token to the kubeconfig.
```
% kubelogin
Open http://localhost:8000 for authentication
You got a valid token until 2019-05-18 10:28:51 +0900 JST
Updated ~/.kubeconfig
```
Now you can access the cluster.
```
% kubectl get pods
NAME READY STATUS RESTARTS AGE
echoserver-86c78fdccd-nzmd5 1/1 Running 0 26d
```
Your kubeconfig looks like:
```yaml
users:
- name: keycloak
user:
auth-provider:
config:
client-id: YOUR_CLIENT_ID
client-secret: YOUR_CLIENT_SECRET
idp-issuer-url: https://issuer.example.com
id-token: ey... # kubelogin will add or update the ID token here
refresh-token: ey... # kubelogin will add or update the refresh token here
name: oidc
```
If the ID token is valid, kubelogin does nothing.
```
% kubelogin
You already have a valid token until 2019-05-18 10:28:51 +0900 JST
```
If the ID token has expired, kubelogin will refresh the token using the refresh token in the kubeconfig.
If the refresh token has expired, kubelogin will proceed the authentication.
## Usage
Kubelogin supports the following options:
```
% kubelogin -h
Login to the OpenID Connect provider and update the kubeconfig
Usage:
kubelogin [flags]
kubelogin [command]
Examples:
# Login to the provider using the authorization code flow.
kubelogin
# Login to the provider using the resource owner password credentials flow.
kubelogin --username USERNAME --password PASSWORD
# Run as a credential plugin.
kubelogin get-token --oidc-issuer-url=https://issuer.example.com
Available Commands:
get-token Run as a kubectl credential plugin
help Help about any command
version Print the version information
Flags:
--kubeconfig string Path to the kubeconfig file
--context string The name of the kubeconfig context to use
--user string The name of the kubeconfig user to use. Prior to --context
--certificate-authority string Path to a cert file for the certificate authority
--insecure-skip-tls-verify If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure
-v, --v int If set to 1 or greater, it shows debug log
--listen-port ints Port to bind to the local server. If multiple ports are given, it will try the ports in order (default [8000,18000])
--skip-open-browser If true, it does not open the browser on authentication
--username string If set, perform the resource owner password credentials grant
--password string If set, use the password instead of asking it
-h, --help help for kubelogin
```
### Kubeconfig
You can set path to the kubeconfig file by the option or the environment variable just like kubectl.
It defaults to `~/.kube/config`.
```sh
# by the option
kubelogin --kubeconfig /path/to/kubeconfig
# by the environment variable
KUBECONFIG="/path/to/kubeconfig1:/path/to/kubeconfig2" kubelogin
```
If you set multiple files, kubelogin will find the file which has the current authentication (i.e. `user` and `auth-provider`) and write a token to it.
Kubelogin supports the following keys of `auth-provider` in a kubeconfig.
See [kubectl authentication](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#using-kubectl) for more.
Key | Direction | Value
----|-----------|------
`idp-issuer-url` | Read (Mandatory) | Issuer URL of the provider.
`client-id` | Read (Mandatory) | Client ID of the provider.
`client-secret` | Read (Mandatory) | Client Secret of the provider.
`idp-certificate-authority` | Read | CA certificate path of the provider.
`idp-certificate-authority-data` | Read | Base64 encoded CA certificate of the provider.
`extra-scopes` | Read | Scopes to request to the provider (comma separated).
`id-token` | Write | ID token got from the provider.
`refresh-token` | Write | Refresh token got from the provider.
### Extra scopes
You can set the extra scopes to request to the provider by `extra-scopes` in the kubeconfig.
```sh
kubectl config set-credentials keycloak --auth-provider-arg extra-scopes=email
```
Currently kubectl does not accept multiple scopes, so you need to edit the kubeconfig as like:
```sh
kubectl config set-credentials keycloak --auth-provider-arg extra-scopes=SCOPES
sed -i '' -e s/SCOPES/email,profile/ $KUBECONFIG
```
### CA Certificates
You can use your self-signed certificates for the provider.
```sh
kubectl config set-credentials keycloak \
--auth-provider-arg idp-certificate-authority=$HOME/.kube/keycloak-ca.pem
```