diff --git a/docs/setup.md b/docs/setup.md index 2b575ac..55d5dc0 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -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//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 diff --git a/docs/usage.md b/docs/usage.md index 9b13578..d6eb311 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -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