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 setup and usage docs (#1357)

Browse Source 
* Refactor seup and usage docs

* Fix
This commit is contained in:
Hidetake Iwata
2025-06-16 14:58:20 +09:00
committed by GitHub
parent cefacba2d2
commit b2dbe2beda
2 changed files with 49 additions and 184 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
docs/setup.md
View File

@@ -12,167 +12,32 @@ 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.
Open [Google APIs Console](https://console.cloud.google.com/apis/credentials) and create an OAuth client with the following setting:
- Application Type: Desktop app
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` | `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` |
### Keycloak
You can log in with a user of Keycloak.
Make sure you have an administrator role of the Keycloak realm.
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)
- Issuer URL: `https://keycloak.example.com/auth/realms/YOUR_REALM`
You can associate client roles by adding the following mapper:
- Name: `groups`
- Mapper Type: `User Client Role`
- Client ID: `YOUR_CLIENT_ID`
- Client Role prefix: `kubernetes:`
- Token Claim Name: `groups`
- Add to ID token: on
For example, if you have `admin` role of the client, you will get a JWT with the claim `{"groups": ["kubernetes:admin"]}`.
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` is not required for this configuration.
### Dex with GitHub
You can log in with a GitHub account.
Open [GitHub OAuth Apps](https://github.com/settings/developers) and create an application with the following setting:
- Application name: (any)
- Homepage URL: `https://dex.example.com`
- Authorization callback URL: `https://dex.example.com/callback`
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
staticClients:
- 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` |
### Okta
You can log in with an Okta user.
Okta supports [the authorization code flow with PKCE](https://developer.okta.com/docs/guides/implement-auth-code-pkce/overview/)
and this section explains how to set up it.
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)
- 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 |
`YOUR_CLIENT_SECRET` is not required for this configuration.
If you need `groups` claim for access control,
see [jetstack/okta-kubectl-auth](https://github.com/jetstack/okta-kubectl-auth/blob/master/docs/okta-setup.md) and [#250](https://github.com/int128/kubelogin/issues/250).
### Ping Identity
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)
- 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 |
`YOUR_CLIENT_SECRET` is not required for this configuration.
Kubelogin supports the authentication flows such as Device Authorization Grant or Authorization Code Flow.
For the details of flows supported in Kubelogin, see the [usage](usage.md).
For the details of your provider, ask the administrator of your provider.
## 2. Authenticate with the OpenID Connect Provider
Run the following command:
Run the following command to show the instruction to set up the configuration:
```sh
kubectl oidc-login setup \
--oidc-issuer-url=ISSUER_URL \
--oidc-client-id=YOUR_CLIENT_ID
kubectl oidc-login setup --oidc-issuer-url=ISSUER_URL --oidc-client-id=YOUR_CLIENT_ID
```
If your provider requires a client secret, add `--oidc-client-secret=YOUR_CLIENT_SECRET`.
Set the following flags:
It launches the browser and navigates to `http://localhost:8000`.
Please log in to the provider.
- Set the issuer URL of your OpenID Connect provider to `--oidc-issuer-url`.
- Set the client ID for your OpenID Connect provider to `--oidc-client-id`.
- If your provider requires a client secret, set `--oidc-client-secret`.
For the full options,
If your provider supports the Device Authorization Grant, set `--grant-type=device-code`.
It launches the browser and navigates to the authentication page of your provider.
If your provider supports the Authorization Code Flow, set `--grant-type=authcode`.
It starts a local server for the authentication.
It launches the browser and navigates to the authentication page of your provider.
You can see the full options:
```sh
kubectl oidc-login setup --help

64
docs/usage.md
View File

@@ -136,15 +136,36 @@ 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)
- [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)
- [Client Credentials flow](#client-credentials-flow)
- [Device Authorization Grant](#device-authorization-grant)
- [Authorization Code Flow](#authorization-code-flow)
- [Authorization Code Flow with a Keyboard](#authorization-code-flow-with-a-keyboard)
- [Resource Owner Password Credentials Grant](#resource-owner-password-credentials-grant)
- [Client Credentials Flow](#client-credentials-flow)
### Authorization code flow
### Device Authorization Grant
Kubelogin performs the [authorization code flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) by default.
It performs the [Device Authorization Grant (RFC 8628)](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
```
### Authorization Code Flow
It performs the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth) when `--grant-type=authcode` is set or the flag is not given.
It starts the local server at port 8000 or 18000 by default.
You need to register the following redirect URIs to the provider:
@@ -196,7 +217,7 @@ If you encounter a problem with the browser, you can change the browser command
- --skip-open-browser
```
### Authorization code flow with a keyboard
### Authorization Code Flow with a keyboard
If you cannot access the browser, instead use the authorization code flow with a keyboard.
@@ -226,30 +247,9 @@ You can add extra parameters to the authentication request.
- --oidc-auth-request-extra-params=ttl=86400
```
### Device authorization grant
### Resource Owner Password Credentials 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
It performs the [Resource Owner Password Credentials Grant](https://datatracker.ietf.org/doc/html/rfc6749#section-4.3)
when `--grant-type=password` or `--username` is set.
Note that most OIDC providers do not support this grant.
@@ -287,7 +287,7 @@ Password:
### Client Credentials Flow
Kubelogin performs the [OAuth 2.0 client credentials flow](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) when `--grant-type=client-credentials` is set.
It performs the [OAuth 2.0 Client Credentials Flow](https://datatracker.ietf.org/doc/html/rfc6749#section-1.3.4) when `--grant-type=client-credentials` is set.
```yaml
- --grant-type=client-credentials