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

Format markdown (#1235)

Browse Source
This commit is contained in:
Hidetake Iwata
2025-01-12 14:00:03 +09:00
committed by GitHub
parent ca273c358d
commit 5ebecc534e
4 changed files with 125 additions and 139 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
README.md
View File

@@ -13,7 +13,6 @@ Take a look at the diagram:
![Diagram of the credential plugin](docs/credential-plugin-diagram.svg)
## Getting Started
### Setup
@@ -38,22 +37,21 @@ The kubeconfig looks like:
```yaml
users:
- name: oidc
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: kubectl
args:
- oidc-login
- get-token
- --oidc-issuer-url=ISSUER_URL
- --oidc-client-id=YOUR_CLIENT_ID
- --oidc-client-secret=YOUR_CLIENT_SECRET
- name: oidc
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: kubectl
args:
- oidc-login
- get-token
- --oidc-issuer-url=ISSUER_URL
- --oidc-client-id=YOUR_CLIENT_ID
- --oidc-client-secret=YOUR_CLIENT_SECRET
```
See [setup guide](docs/setup.md) for more.
### Run
Run kubectl.
@@ -82,7 +80,6 @@ If the cached ID token is valid, kubelogin just returns it.
If the cached ID token has expired, kubelogin will refresh the token using the refresh token.
If the refresh token has expired, kubelogin will perform re-authentication (you will have to login via browser again).
### Troubleshoot
You can log out by removing the token cache directory (default `~/.kube/cache/oidc-login`).
@@ -107,20 +104,19 @@ You can increase the log level by `-v1` option.
```yaml
users:
- name: oidc
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: kubectl
args:
- oidc-login
- get-token
- -v1
- name: oidc
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: kubectl
args:
- oidc-login
- get-token
- -v1
```
You can verify kubelogin works with your provider using [acceptance test](acceptance_test).
## Docs
- [Setup guide](docs/setup.md)
@@ -129,7 +125,6 @@ You can verify kubelogin works with your provider using [acceptance test](accept
- [System test](system_test)
- [Acceptance_test for identity providers](acceptance_test)
## Contributions
This is an open source software licensed under Apache License 2.0.

97
docs/setup.md
View File

@@ -10,7 +10,6 @@ Let's see the following steps:
1. Set up the kubeconfig
1. Verify cluster access
## 1. Set up the OIDC provider
### Google Identity Platform
@@ -24,11 +23,11 @@ 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`
`YOUR_CLIENT_SECRET` | random string
| Variable | Value |
| -------------------- | -------------------------------- |
| `ISSUER_URL` | `https://accounts.google.com` |
| `YOUR_CLIENT_ID` | `xxx.apps.googleusercontent.com` |
| `YOUR_CLIENT_SECRET` | random string |
### Keycloak
@@ -39,8 +38,8 @@ Open Keycloak and create an OIDC client as follows:
- Client ID: `YOUR_CLIENT_ID`
- Valid Redirect URLs:
- `http://localhost:8000`
- `http://localhost:18000` (used if the port 8000 is already in use)
- `http://localhost:8000`
- `http://localhost:18000` (used if the port 8000 is already in use)
- Issuer URL: `https://keycloak.example.com/auth/realms/YOUR_REALM`
You can associate client roles by adding the following mapper:
@@ -56,11 +55,11 @@ 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`
`YOUR_CLIENT_SECRET` | random string
| Variable | Value |
| -------------------- | ----------------------------------------------------- |
| `ISSUER_URL` | `https://keycloak.example.com/auth/realms/YOUR_REALM` |
| `YOUR_CLIENT_ID` | `YOUR_CLIENT_ID` |
| `YOUR_CLIENT_SECRET` | random string |
### Dex with GitHub
@@ -77,29 +76,29 @@ Deploy [Dex](https://github.com/dexidp/dex) with the following config:
```yaml
issuer: https://dex.example.com
connectors:
- type: github
id: github
name: GitHub
config:
clientID: YOUR_GITHUB_CLIENT_ID
clientSecret: YOUR_GITHUB_CLIENT_SECRET
redirectURI: https://dex.example.com/callback
- type: github
id: github
name: GitHub
config:
clientID: YOUR_GITHUB_CLIENT_ID
clientSecret: YOUR_GITHUB_CLIENT_SECRET
redirectURI: https://dex.example.com/callback
staticClients:
- id: YOUR_CLIENT_ID
name: Kubernetes
redirectURIs:
- http://localhost:8000
- http://localhost:18000
secret: YOUR_DEX_CLIENT_SECRET
- id: YOUR_CLIENT_ID
name: Kubernetes
redirectURIs:
- http://localhost:8000
- http://localhost:18000
secret: YOUR_DEX_CLIENT_SECRET
```
Replace the following variables in the later sections.
Variable | Value
------------------------|------
`ISSUER_URL` | `https://dex.example.com`
`YOUR_CLIENT_ID` | `YOUR_CLIENT_ID`
`YOUR_CLIENT_SECRET` | `YOUR_DEX_CLIENT_SECRET`
| Variable | Value |
| -------------------- | ------------------------- |
| `ISSUER_URL` | `https://dex.example.com` |
| `YOUR_CLIENT_ID` | `YOUR_CLIENT_ID` |
| `YOUR_CLIENT_SECRET` | `YOUR_DEX_CLIENT_SECRET` |
### Okta
@@ -112,17 +111,17 @@ Open your Okta organization and create an application with the following options
- Application type: Native
- Initiate login URI: `http://localhost:8000`
- Login redirect URIs:
- `http://localhost:8000`
- `http://localhost:18000` (used if the port 8000 is already in use)
- `http://localhost:8000`
- `http://localhost:18000` (used if the port 8000 is already in use)
- Allowed grant types: Authorization Code
- Client authentication: Use PKCE (for public clients)
Replace the following variables in the later sections.
Variable | Value
------------------------|------
`ISSUER_URL` | `https://YOUR_ORGANIZATION.okta.com`
`YOUR_CLIENT_ID` | random string
| Variable | Value |
| ---------------- | ------------------------------------ |
| `ISSUER_URL` | `https://YOUR_ORGANIZATION.okta.com` |
| `YOUR_CLIENT_ID` | random string |
You do not need to set `YOUR_CLIENT_SECRET`.
@@ -135,17 +134,17 @@ Login with an account that has permissions to create applications.
Create an OIDC application with the following configuration:
- Redirect URIs:
- `http://localhost:8000`
- `http://localhost:18000` (used if the port 8000 is already in use)
- `http://localhost:8000`
- `http://localhost:18000` (used if the port 8000 is already in use)
- Grant type: Authorization Code
- PKCE Enforcement: Required
Leverage the following variables in the next steps.
Variable | Value
------------------------|------
`ISSUER_URL` | `https://auth.pingone.com/<PingOne Tenant Id>/as`
`YOUR_CLIENT_ID` | random string
| Variable | Value |
| ---------------- | ------------------------------------------------- |
| `ISSUER_URL` | `https://auth.pingone.com/<PingOne Tenant Id>/as` |
| `YOUR_CLIENT_ID` | random string |
`YOUR_CLIENT_SECRET` is not required for this configuration.
@@ -170,7 +169,6 @@ See also the full options.
kubectl oidc-login setup --help
```
## 3. Bind a cluster role
Here bind `cluster-admin` role to you.
@@ -181,7 +179,6 @@ kubectl create clusterrolebinding oidc-cluster-admin --clusterrole=cluster-admin
As well as you can create a custom cluster role and bind it.
## 4. Set up the Kubernetes API server
Add the following flags to kube-apiserver:
@@ -205,13 +202,12 @@ spec:
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
oidc:
enabled: true
issuerUrl: ISSUER_URL
clientId: YOUR_CLIENT_ID
```
## 5. Set up the kubeconfig
Add `oidc` user to the kubeconfig.
@@ -227,7 +223,6 @@ kubectl config set-credentials oidc \
--exec-arg=--oidc-client-secret=YOUR_CLIENT_SECRET
```
## 6. Verify cluster access
Make sure you can access the Kubernetes cluster.

42
docs/standalone-mode.md
View File

@@ -3,7 +3,6 @@
Kubelogin supports the standalone mode as well.
It writes the token to the kubeconfig (typically `~/.kube/config`) after authentication.
## Getting started
Configure your kubeconfig like:
@@ -53,16 +52,16 @@ 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
- 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.
@@ -75,7 +74,6 @@ 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
You can set path to the kubeconfig file by the option or the environment variable just like kubectl.
@@ -94,15 +92,15 @@ If you set multiple files, kubelogin will find the file which has the current au
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.
| 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. |
See also [usage.md](usage.md).

80
docs/usage.md
View File

@@ -51,7 +51,6 @@ Global Flags:
--vmodule moduleSpec comma-separated list of pattern=N settings for file-filtered logging
```
## Options
### Authentication timeout
@@ -61,7 +60,7 @@ This prevents a process from remaining forever.
You can change the timeout by the following flag:
```yaml
- --authentication-timeout-sec=60
- --authentication-timeout-sec=60
```
For now this timeout works only for the authorization code flow.
@@ -71,8 +70,8 @@ For now this timeout works only for the authorization code flow.
You can set the extra scopes to request to the provider by `--oidc-extra-scope`.
```yaml
- --oidc-extra-scope=email
- --oidc-extra-scope=profile
- --oidc-extra-scope=email
- --oidc-extra-scope=profile
```
### CA certificate
@@ -80,8 +79,8 @@ You can set the extra scopes to request to the provider by `--oidc-extra-scope`.
You can use your self-signed certificate for the provider.
```yaml
- --certificate-authority=/home/user/.kube/keycloak-ca.pem
- --certificate-authority-data=LS0t...
- --certificate-authority=/home/user/.kube/keycloak-ca.pem
- --certificate-authority-data=LS0t...
```
### HTTP proxy
@@ -98,7 +97,6 @@ If a value in the following options begins with a tilde character `~`, it is exp
- `--local-server-key`
- `--token-cache-dir`
## Authentication flows
Kubelogin support the following flows:
@@ -120,40 +118,40 @@ You need to register the following redirect URIs to the provider:
You can change the listening address.
```yaml
- --listen-address=127.0.0.1:12345
- --listen-address=127.0.0.1:23456
- --listen-address=127.0.0.1:12345
- --listen-address=127.0.0.1:23456
```
You can specify a certificate for the local webserver if HTTPS is required by your identity provider.
```yaml
- --local-server-cert=localhost.crt
- --local-server-key=localhost.key
- --local-server-cert=localhost.crt
- --local-server-key=localhost.key
```
You can change the hostname of redirect URI from the default value `localhost`.
```yaml
- --oidc-redirect-url-hostname=127.0.0.1
- --oidc-redirect-url-hostname=127.0.0.1
```
You can add extra parameters to the authentication request.
```yaml
- --oidc-auth-request-extra-params=ttl=86400
- --oidc-auth-request-extra-params=ttl=86400
```
When authentication completed, kubelogin shows a message to close the browser.
You can change the URL to show after authentication.
```yaml
- --open-url-after-authentication=https://example.com/success.html
- --open-url-after-authentication=https://example.com/success.html
```
You can skip opening the browser if you encounter some environment problem.
```yaml
- --skip-open-browser
- --skip-open-browser
```
For Linux users, you change the default browser by `BROWSER` environment variable.
@@ -163,7 +161,7 @@ For Linux users, you change the default browser by `BROWSER` environment variabl
If you cannot access the browser, instead use the authorization code flow with a keyboard.
```yaml
- --grant-type=authcode-keyboard
- --grant-type=authcode-keyboard
```
Kubelogin will show the URL and prompt.
@@ -179,13 +177,13 @@ The default of redirect URI is `urn:ietf:wg:oauth:2.0:oob`.
You can overwrite it.
```yaml
- oidc-redirect-url-authcode-keyboard=http://localhost
- oidc-redirect-url-authcode-keyboard=http://localhost
```
You can add extra parameters to the authentication request.
```yaml
- --oidc-auth-request-extra-params=ttl=86400
- --oidc-auth-request-extra-params=ttl=86400
```
### Resource owner password credentials grant flow
@@ -199,14 +197,14 @@ Keycloak supports this flow but you need to explicitly enable the "Direct Access
You can set the username and password.
```yaml
- --username=USERNAME
- --password=PASSWORD
- --username=USERNAME
- --password=PASSWORD
```
If the password is not set, kubelogin will show the prompt for the password.
```yaml
- --username=USERNAME
- --username=USERNAME
```
```
@@ -217,7 +215,7 @@ Password:
If the username is not set, kubelogin will show the prompt for the username and password.
```yaml
- --grant-type=password
- --grant-type=password
```
```
@@ -233,25 +231,25 @@ The kubeconfig looks like:
```yaml
users:
- name: oidc
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: docker
args:
- run
- --rm
- -v
- /tmp/.token-cache:/.token-cache
- -p
- 8000:8000
- ghcr.io/int128/kubelogin
- get-token
- --token-cache-dir=/.token-cache
- --listen-address=0.0.0.0:8000
- --oidc-issuer-url=ISSUER_URL
- --oidc-client-id=YOUR_CLIENT_ID
- --oidc-client-secret=YOUR_CLIENT_SECRET
- name: oidc
user:
exec:
apiVersion: client.authentication.k8s.io/v1beta1
command: docker
args:
- run
- --rm
- -v
- /tmp/.token-cache:/.token-cache
- -p
- 8000:8000
- ghcr.io/int128/kubelogin
- get-token
- --token-cache-dir=/.token-cache
- --listen-address=0.0.0.0:8000
- --oidc-issuer-url=ISSUER_URL
- --oidc-client-id=YOUR_CLIENT_ID
- --oidc-client-secret=YOUR_CLIENT_SECRET
```
Known limitations: