From 5ebecc534e01920fe4134b646c13457c9017d433 Mon Sep 17 00:00:00 2001 From: Hidetake Iwata Date: Sun, 12 Jan 2025 14:00:03 +0900 Subject: [PATCH] Format markdown (#1235) --- README.md | 45 +++++++++---------- docs/setup.md | 97 +++++++++++++++++++---------------------- docs/standalone-mode.md | 42 +++++++++--------- docs/usage.md | 80 +++++++++++++++++---------------- 4 files changed, 125 insertions(+), 139 deletions(-) diff --git a/README.md b/README.md index f5ee3fb..186a118 100644 --- a/README.md +++ b/README.md @@ -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. diff --git a/docs/setup.md b/docs/setup.md index c72140b..5311515 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -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//as` -`YOUR_CLIENT_ID` | random string +| Variable | Value | +| ---------------- | ------------------------------------------------- | +| `ISSUER_URL` | `https://auth.pingone.com//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. diff --git a/docs/standalone-mode.md b/docs/standalone-mode.md index f857c87..6a53fba 100644 --- a/docs/standalone-mode.md +++ b/docs/standalone-mode.md @@ -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). diff --git a/docs/usage.md b/docs/usage.md index 387498b..6ccd893 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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: