Merge branch 'main' into merge_impersonator_service_annotations

pkg/oidcclient/login.go

@@ -60,6 +60,11 @@ const (
 	defaultLDAPUsernamePrompt = "Username: "
 	defaultLDAPPasswordPrompt = "Password: "
 
+	// For CLI-based auth, such as with LDAP upstream identity providers, the user may use these environment variables
+	// to avoid getting interactively prompted for username and password.
+	defaultUsernameEnvVarName = "PINNIPED_USERNAME"
+	defaultPasswordEnvVarName = "PINNIPED_PASSWORD" //nolint:gosec // this is not a credential
+
 	httpLocationHeaderName = "Location"
 
 	debugLogLevel = 4
@@ -99,6 +104,7 @@ type handlerState struct {
 	generatePKCE    func() (pkce.Code, error)
 	generateNonce   func() (nonce.Nonce, error)
 	openURL         func(string) error
+	getEnv          func(key string) string
 	listen          func(string, string) (net.Listener, error)
 	isTTY           func(int) bool
 	getProvider     func(*oauth2.Config, *oidc.Provider, *http.Client) provider.UpstreamOIDCIdentityProviderI
@@ -275,6 +281,7 @@ func Login(issuer string, clientID string, opts ...Option) (*oidctypes.Token, er
 		generateNonce: nonce.Generate,
 		generatePKCE:  pkce.Generate,
 		openURL:       browser.OpenURL,
+		getEnv:        os.Getenv,
 		listen:        net.Listen,
 		isTTY:         term.IsTerminal,
 		getProvider:   upstreamoidc.New,
@@ -402,14 +409,10 @@ func (h *handlerState) baseLogin() (*oidctypes.Token, error) {
 // Make a direct call to the authorize endpoint, including the user's username and password on custom http headers,
 // and parse the authcode from the response. Exchange the authcode for tokens. Return the tokens or an error.
 func (h *handlerState) cliBasedAuth(authorizeOptions *[]oauth2.AuthCodeOption) (*oidctypes.Token, error) {
-	// Ask the user for their username and password.
+	// Ask the user for their username and password, or get them from env vars.
-	username, err := h.promptForValue(h.ctx, defaultLDAPUsernamePrompt)
+	username, password, err := h.getUsernameAndPassword()
 	if err != nil {
-		return nil, fmt.Errorf("error prompting for username: %w", err)
+		return nil, err
-	}
-	password, err := h.promptForSecret(h.ctx, defaultLDAPPasswordPrompt)
-	if err != nil {
-		return nil, fmt.Errorf("error prompting for password: %w", err)
 	}
 
 	// Make a callback URL even though we won't be listening on this port, because providing a redirect URL is
@@ -499,6 +502,33 @@ func (h *handlerState) cliBasedAuth(authorizeOptions *[]oauth2.AuthCodeOption) (
 	return token, nil
 }
 
+// Prompt for the user's username and password, or read them from env vars if they are available.
+func (h *handlerState) getUsernameAndPassword() (string, string, error) {
+	var err error
+
+	username := h.getEnv(defaultUsernameEnvVarName)
+	if username == "" {
+		username, err = h.promptForValue(h.ctx, defaultLDAPUsernamePrompt)
+		if err != nil {
+			return "", "", fmt.Errorf("error prompting for username: %w", err)
+		}
+	} else {
+		h.logger.V(debugLogLevel).Info("Pinniped: Read username from environment variable", "name", defaultUsernameEnvVarName)
+	}
+
+	password := h.getEnv(defaultPasswordEnvVarName)
+	if password == "" {
+		password, err = h.promptForSecret(h.ctx, defaultLDAPPasswordPrompt)
+		if err != nil {
+			return "", "", fmt.Errorf("error prompting for password: %w", err)
+		}
+	} else {
+		h.logger.V(debugLogLevel).Info("Pinniped: Read password from environment variable", "name", defaultPasswordEnvVarName)
+	}
+
+	return username, password, nil
+}
+
 // Open a web browser, or ask the user to open a web browser, to visit the authorize endpoint.
 // Create a localhost callback listener which exchanges the authcode for tokens. Return the tokens or an error.
 func (h *handlerState) webBrowserBasedAuth(authorizeOptions *[]oauth2.AuthCodeOption) (*oidctypes.Token, error) {

pkg/oidcclient/login_test.go

@@ -993,7 +993,7 @@ func TestLogin(t *testing.T) { // nolint:gocyclo
 			wantErr:  "error during authorization code exchange: some authcode exchange or token validation error",
 		},
 		{
-			name:     "successful ldap login",
+			name:     "successful ldap login with prompts for username and password",
 			clientID: "test-client-id",
 			opt: func(t *testing.T) Option {
 				return func(h *handlerState) error {
@@ -1011,6 +1011,9 @@ func TestLogin(t *testing.T) { // nolint:gocyclo
 					h.generateState = func() (state.State, error) { return "test-state", nil }
 					h.generatePKCE = func() (pkce.Code, error) { return "test-pkce", nil }
 					h.generateNonce = func() (nonce.Nonce, error) { return "test-nonce", nil }
+					h.getEnv = func(_ string) string {
+						return "" // asking for any env var returns empty as if it were unset
+					}
 					h.promptForValue = func(_ context.Context, promptLabel string) (string, error) {
 						require.Equal(t, "Username: ", promptLabel)
 						return "some-upstream-username", nil
@@ -1089,6 +1092,117 @@ func TestLogin(t *testing.T) { // nolint:gocyclo
 			wantLogs:  []string{"\"level\"=4 \"msg\"=\"Pinniped: Performing OIDC discovery\"  \"issuer\"=\"" + successServer.URL + "\""},
 			wantToken: &testToken,
 		},
+		{
+			name:     "successful ldap login with env vars for username and password",
+			clientID: "test-client-id",
+			opt: func(t *testing.T) Option {
+				return func(h *handlerState) error {
+					fakeAuthCode := "test-authcode-value"
+
+					h.getProvider = func(_ *oauth2.Config, _ *oidc.Provider, _ *http.Client) provider.UpstreamOIDCIdentityProviderI {
+						mock := mockUpstream(t)
+						mock.EXPECT().
+							ExchangeAuthcodeAndValidateTokens(
+								gomock.Any(), fakeAuthCode, pkce.Code("test-pkce"), nonce.Nonce("test-nonce"), "http://127.0.0.1:0/callback").
+							Return(&testToken, nil)
+						return mock
+					}
+
+					h.generateState = func() (state.State, error) { return "test-state", nil }
+					h.generatePKCE = func() (pkce.Code, error) { return "test-pkce", nil }
+					h.generateNonce = func() (nonce.Nonce, error) { return "test-nonce", nil }
+					h.getEnv = func(key string) string {
+						switch key {
+						case "PINNIPED_USERNAME":
+							return "some-upstream-username"
+						case "PINNIPED_PASSWORD":
+							return "some-upstream-password"
+						default:
+							return "" // all other env vars are treated as if they are unset
+						}
+					}
+					h.promptForValue = func(_ context.Context, promptLabel string) (string, error) {
+						require.FailNow(t, fmt.Sprintf("saw unexpected prompt from the CLI: %q", promptLabel))
+						return "", nil
+					}
+					h.promptForSecret = func(_ context.Context, promptLabel string) (string, error) {
+						require.FailNow(t, fmt.Sprintf("saw unexpected prompt from the CLI: %q", promptLabel))
+						return "", nil
+					}
+
+					cache := &mockSessionCache{t: t, getReturnsToken: nil}
+					cacheKey := SessionCacheKey{
+						Issuer:      successServer.URL,
+						ClientID:    "test-client-id",
+						Scopes:      []string{"test-scope"},
+						RedirectURI: "http://localhost:0/callback",
+					}
+					t.Cleanup(func() {
+						require.Equal(t, []SessionCacheKey{cacheKey}, cache.sawGetKeys)
+						require.Equal(t, []SessionCacheKey{cacheKey}, cache.sawPutKeys)
+						require.Equal(t, []*oidctypes.Token{&testToken}, cache.sawPutTokens)
+					})
+					require.NoError(t, WithSessionCache(cache)(h))
+					require.NoError(t, WithCLISendingCredentials()(h))
+					require.NoError(t, WithUpstreamIdentityProvider("some-upstream-name", "ldap")(h))
+
+					discoveryRequestWasMade := false
+					authorizeRequestWasMade := false
+					t.Cleanup(func() {
+						require.True(t, discoveryRequestWasMade, "should have made an discovery request")
+						require.True(t, authorizeRequestWasMade, "should have made an authorize request")
+					})
+
+					require.NoError(t, WithClient(&http.Client{
+						Transport: roundtripper.Func(func(req *http.Request) (*http.Response, error) {
+							switch req.URL.Scheme + "://" + req.URL.Host + req.URL.Path {
+							case "http://" + successServer.Listener.Addr().String() + "/.well-known/openid-configuration":
+								discoveryRequestWasMade = true
+								return defaultDiscoveryResponse(req)
+							case "http://" + successServer.Listener.Addr().String() + "/authorize":
+								authorizeRequestWasMade = true
+								require.Equal(t, "some-upstream-username", req.Header.Get("Pinniped-Username"))
+								require.Equal(t, "some-upstream-password", req.Header.Get("Pinniped-Password"))
+								require.Equal(t, url.Values{
+									// This is the PKCE challenge which is calculated as base64(sha256("test-pkce")). For example:
+									// $ echo -n test-pkce | shasum -a 256 | cut -d" " -f1 | xxd -r -p | base64 | cut -d"=" -f1
+									// VVaezYqum7reIhoavCHD1n2d+piN3r/mywoYj7fCR7g
+									"code_challenge":        []string{"VVaezYqum7reIhoavCHD1n2d-piN3r_mywoYj7fCR7g"},
+									"code_challenge_method": []string{"S256"},
+									"response_type":         []string{"code"},
+									"scope":                 []string{"test-scope"},
+									"nonce":                 []string{"test-nonce"},
+									"state":                 []string{"test-state"},
+									"access_type":           []string{"offline"},
+									"client_id":             []string{"test-client-id"},
+									"redirect_uri":          []string{"http://127.0.0.1:0/callback"},
+									"pinniped_idp_name":     []string{"some-upstream-name"},
+									"pinniped_idp_type":     []string{"ldap"},
+								}, req.URL.Query())
+								return &http.Response{
+									StatusCode: http.StatusFound,
+									Header: http.Header{"Location": []string{
+										fmt.Sprintf("http://127.0.0.1:0/callback?code=%s&state=test-state", fakeAuthCode),
+									}},
+								}, nil
+							default:
+								// Note that "/token" requests should not be made. They are mocked by mocking calls to ExchangeAuthcodeAndValidateTokens().
+								require.FailNow(t, fmt.Sprintf("saw unexpected http call from the CLI: %s", req.URL.String()))
+								return nil, nil
+							}
+						}),
+					})(h))
+					return nil
+				}
+			},
+			issuer: successServer.URL,
+			wantLogs: []string{
+				"\"level\"=4 \"msg\"=\"Pinniped: Performing OIDC discovery\"  \"issuer\"=\"" + successServer.URL + "\"",
+				"\"level\"=4 \"msg\"=\"Pinniped: Read username from environment variable\"  \"name\"=\"PINNIPED_USERNAME\"",
+				"\"level\"=4 \"msg\"=\"Pinniped: Read password from environment variable\"  \"name\"=\"PINNIPED_PASSWORD\"",
+			},
+			wantToken: &testToken,
+		},
 		{
 			name:     "with requested audience, session cache hit with valid token, but discovery fails",
 			clientID: "test-client-id",

site/content/docs/howto/_index.md

@@ -1,5 +1,5 @@
 ---
-title: Pinniped How-To Guides
+title: Pinniped how-to guides
 cascade:
   layout: docs
 menu:

site/content/docs/howto/configure-concierge-jwt.md

@@ -15,6 +15,7 @@ This guide shows you how to use this capability _without_ the Pinniped Superviso
 This is most useful if you have only a single cluster and want to authenticate to it via an existing OIDC provider.
 
 If you have multiple clusters, you may want to [install]({{< ref "install-supervisor" >}}) and [configure]({{< ref "configure-supervisor" >}}) the Pinniped Supervisor.
+Then you can [configure the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}}).
 
 ## Prerequisites
 
@@ -121,7 +122,7 @@ You should see:
 
   ```sh
   kubectl create clusterrolebinding my-user-admin \
-    --clusterrole admin \
+    --clusterrole edit \
     --user my-username@example.com
   ```
 

site/content/docs/howto/configure-concierge-supervisor-jwt.md

@@ -1,6 +1,6 @@
 ---
 title: Configure the Pinniped Concierge to validate JWT tokens issued by the Pinniped Supervisor
-description: Set up JSON Web Token (JWT) based token authentication on an individual Kubernetes cluster using the Pinniped Supervisor as the OIDC Provider.
+description: Set up JSON Web Token (JWT) based token authentication on an individual Kubernetes cluster using the Pinniped Supervisor as the OIDC provider.
 cascade:
   layout: docs
 menu:
@@ -26,6 +26,9 @@ If you would rather not use the Supervisor, you may want to [configure the Conci
 This how-to guide assumes that you have already [installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress,
 and that you have [configured a FederationDomain to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}).
 
+It also assumes that you have configured an `OIDCIdentityProvider` or an `LDAPIdentityProvider` for the Supervisor as the source of your user's identities.
+Various examples of configuring these resources can be found in these guides.
+
 It also assumes that you have already [installed the Pinniped Concierge]({{< ref "install-concierge" >}})
 on all the clusters in which you would like to allow users to have a unified identity.
 
@@ -64,62 +67,6 @@ kubectl apply -f my-supervisor-authenticator.yaml
 Do this on each cluster in which you would like to allow users from that FederationDomain to log in.
 Don't forget to give each cluster a unique `audience` value for security reasons.
 
-## Generate a kubeconfig file
+## Next steps
 
-Generate a kubeconfig file for one of the clusters in which you installed and configured the Concierge as described above:
+Next, [log in to your cluster]({{< ref "login" >}})!
-
-```sh
-pinniped get kubeconfig > my-cluster.yaml
-```
-
-This assumes that your current kubeconfig is an admin-level kubeconfig for the cluster, such as the kubeconfig
-that you used to install the Concierge.
-
-This creates a kubeconfig YAML file `my-cluster.yaml`, unique to that cluster, which targets your JWTAuthenticator
-using `pinniped login oidc` as an [ExecCredential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
-This new kubeconfig can be shared with the other users of this cluster. It does not contain any specific
-identity or credentials. When a user uses this new kubeconfig with `kubectl`, the Pinniped plugin will
-prompt them to log in using their own identity.
-
-## Use the kubeconfig file
-
-Use the kubeconfig with `kubectl` to access your cluster:
-
-```sh
-kubectl --kubeconfig my-cluster.yaml get namespaces
-```
-
-You should see:
-
-- The `pinniped login oidc` command is executed automatically by `kubectl`.
-
-- Pinniped directs you to login with whatever identity provider is configured in the Supervisor, either by opening
-  your browser (for upstream OIDC Providers) or by prompting for your username and password (for upstream LDAP providers).
-
-- In your shell, you see your clusters namespaces.
-
-  If instead you get an access denied error, you may need to create a ClusterRoleBinding for username of your account
-  in the Supervisor's upstream identity provider, for example:
-
-  ```sh
-  kubectl create clusterrolebinding my-user-admin \
-    --clusterrole admin \
-    --user my-username@example.com
-  ```
-
-  Alternatively, you could create role bindings based on the group membership of your users
-  in the upstream identity provider, for example:
-
-  ```sh
-  kubectl create clusterrolebinding my-auditors \
-    --clusterrole view \
-    --group auditors
-  ```
-
-## Other notes
-
-- Pinniped kubeconfig files do not contain secrets and are safe to share between users.
-
-- Temporary session credentials such as ID, access, and refresh tokens are stored in:
-  - `~/.config/pinniped/sessions.yaml` (macOS/Linux)
-  - `%USERPROFILE%/.config/pinniped/sessions.yaml` (Windows).

site/content/docs/howto/configure-concierge-webhook.md

@@ -112,5 +112,5 @@ You should see:
   If instead you get an access denied error, you may need to create a ClusterRoleBinding for the username/groups returned by your webhook, for example:
 
   ```sh
-  kubectl create clusterrolebinding my-user-admin --clusterrole admin --user my-username
+  kubectl create clusterrolebinding my-user-admin --clusterrole edit --user my-username
   ```

site/content/docs/howto/configure-supervisor-with-gitlab.md

@@ -1,5 +1,5 @@
 ---
-title: Configure the Pinniped Supervisor to use GitLab as an OIDC Provider
+title: Configure the Pinniped Supervisor to use GitLab as an OIDC provider
 description: Set up the Pinniped Supervisor to use GitLab login.
 cascade:
   layout: docs
@@ -136,6 +136,7 @@ spec:
 # [...]
 ```
 
-## Next Steps
+## Next steps
 
-Now that you have configured the Supervisor to use GitLab, you will want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}}).
+Next, [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}})!
+Then you'll be able to log into those clusters as any of the users from the GitLab directory.

site/content/docs/howto/configure-supervisor-with-jumpcloudldap.md

@@ -1,5 +1,5 @@
 ---
-title: Configure the Pinniped Supervisor to use JumpCloud as an LDAP Provider
+title: Configure the Pinniped Supervisor to use JumpCloud as an LDAP provider
 description: Set up the Pinniped Supervisor to use JumpCloud LDAP
 cascade:
   layout: docs
@@ -152,7 +152,7 @@ kubectl describe LDAPIdentityProvider -n pinniped-supervisor jumpcloudldap
 
 Look at the `status` field. If it was configured correctly, you should see `phase: Ready`.
 
-## Next Steps
+## Next steps
 
-Now that you have configured the Supervisor to use JumpCloud LDAP, you will want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}}).
+Next, [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}})!
 Then you'll be able to log into those clusters as any of the users from the JumpCloud directory.

site/content/docs/howto/configure-supervisor-with-okta.md

@@ -1,5 +1,5 @@
 ---
-title: Configure the Pinniped Supervisor to use Okta as an OIDC Provider
+title: Configure the Pinniped Supervisor to use Okta as an OIDC provider
 description: Set up the Pinniped Supervisor to use Okta login.
 cascade:
   layout: docs
@@ -108,4 +108,5 @@ Look at the `status` field. If it was configured correctly, you should see `phas
 
 ## Next steps
 
-Now that you have configured the Supervisor to use Okta, you will want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}}).
+Next, [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}})!
+Then you'll be able to log into those clusters as any of the users from the Okta directory.

site/content/docs/howto/configure-supervisor-with-openldap.md

@@ -1,5 +1,5 @@
 ---
-title: Configure the Pinniped Supervisor to use OpenLDAP as an LDAP Provider
+title: Configure the Pinniped Supervisor to use OpenLDAP as an LDAP provider
 description: Set up the Pinniped Supervisor to use OpenLDAP login.
 cascade:
   layout: docs
@@ -22,7 +22,7 @@ cluster using their identity from an OpenLDAP server.
 This how-to guide assumes that you have already [installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress,
 and that you have [configured a FederationDomain to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}).
 
-## An Example of Deploying OpenLDAP on Kubernetes
+## An example of deploying OpenLDAP on Kubernetes
 
 *Note: If you already have an OpenLDAP server installed and configured, please skip to the next section to configure the Supervisor.*
 
@@ -292,7 +292,7 @@ kubectl describe LDAPIdentityProvider -n pinniped-supervisor openldap
 
 Look at the `status` field. If it was configured correctly, you should see `phase: Ready`.
 
-## Next Steps
+## Next steps
 
-Now that you have configured the Supervisor to use OpenLDAP, you will want to [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}}).
+Next, [configure the Concierge to validate JWTs issued by the Supervisor]({{< ref "configure-concierge-supervisor-jwt" >}})!
 Then you'll be able to log into those clusters as any of the users from the OpenLDAP directory.

site/content/docs/howto/configure-supervisor.md

@@ -163,3 +163,9 @@ You can create the certificate Secrets however you like, for example you could u
 or `kubectl create secret tls`.
 Keep in mind that your users must load some of these endpoints in their web browsers, so the TLS certificates
 should be signed by a certificate authority that is trusted by their browsers.
+
+## Next steps
+
+Next, configure an `OIDCIdentityProvider` or an `LDAPIdentityProvider` for the Supervisor (several examples are available in these guides),
+and [configure the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}})
+on each cluster!

site/content/docs/howto/install-cli.md

@@ -44,6 +44,8 @@ Click Open to allow the command to proceed.
 
 ## Install a specific version via script
 
+Choose your preferred [release](https://github.com/vmware-tanzu/pinniped/releases) version number and use it to replace the version number in the URL below.
+
 For example, to install v0.9.2 on Linux/amd64:
 
 ```sh
@@ -52,4 +54,8 @@ curl -Lso pinniped https://get.pinniped.dev/v0.9.2/pinniped-cli-linux-amd64 \
   && sudo mv pinniped /usr/local/bin/pinniped
 ```
 
-*Next, [install the Concierge]({{< ref "install-concierge.md" >}})!*
+*Replace v0.9.2 with your preferred version number.*
+
+## Next steps
+
+Next, [install the Supervisor]({{< ref "install-supervisor.md" >}}) and/or [install the Concierge]({{< ref "install-concierge.md" >}})!

site/content/docs/howto/install-concierge.md

@@ -68,4 +68,8 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/)
 
      `ytt --file . | kapp deploy --yes --app pinniped-concierge --diff-changes --file -`
 
-*Next, configure the Concierge for [JWT]({{< ref "configure-concierge-jwt.md" >}}) or [webhook]({{< ref "configure-concierge-webhook.md" >}}) authentication.*
+## Next steps
+
+Next, configure the Concierge for
+[JWT]({{< ref "configure-concierge-jwt.md" >}}) or [webhook]({{< ref "configure-concierge-webhook.md" >}}) authentication,
+or [configure the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}}).

site/content/docs/howto/install-supervisor.md

@@ -67,6 +67,6 @@ Pinniped uses [ytt](https://carvel.dev/ytt/) from [Carvel](https://carvel.dev/)
 
      `ytt --file . | kapp deploy --yes --app pinniped-supervisor --diff-changes --file -`
 
-## Next Steps
+## Next steps
 
-Now that you have installed the Supervisor, you will want to [configure the Supervisor]({{< ref "configure-supervisor" >}}).
+Next, [configure the Supervisor as an OIDC issuer]({{< ref "configure-supervisor" >}})!

site/content/docs/howto/login.md

@@ -0,0 +1,138 @@
+---
+title: Logging into your cluster using Pinniped
+description: Logging into your Kubernetes cluster using Pinniped for authentication.
+cascade:
+  layout: docs
+menu:
+  docs:
+    name: Log in to a Cluster
+    weight: 500
+    parent: howtos
+---
+
+## Prerequisites
+
+This how-to guide assumes that you have already configured the following Pinniped server-side components within your Kubernetes cluster(s):
+
+1. If you would like to use the Pinniped Supervisor for federated authentication across multiple Kubernetes clusters
+   then you have already:
+     1. [Installed the Pinniped Supervisor]({{< ref "install-supervisor" >}}) with working ingress.
+     1. [Configured a FederationDomain to issue tokens for your downstream clusters]({{< ref "configure-supervisor" >}}).
+     1. Configured an `OIDCIdentityProvider` or an `LDAPIdentityProvider` for the Supervisor as the source of your user's identities.
+        Various examples of configuring these resources can be found in these guides.
+1. In each cluster for which you would like to use Pinniped for authentication, you have [installed the Concierge]({{< ref "install-concierge" >}}).
+1. In each cluster's Concierge, you have configured an authenticator. For example, if you are using the Pinniped Supervisor,
+   then you have configured each Concierge to [use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}}).
+
+You should have also already [installed the `pinniped` command-line]({{< ref "install-cli" >}}) client, which is used to generate Pinniped-compatible kubeconfig files, and is also a `kubectl` plugin to enable the Pinniped-based login flow.
+
+## Overview
+
+1. A cluster admin uses Pinniped to generate a kubeconfig for each cluster, and shares the kubeconfig for each cluster with all users of that cluster.
+1. A cluster user uses `kubectl` with the generated kubeconfig given to them by the cluster admin. `kubectl` interactively prompts the user to log in using their own unique identity.
+
+## Key advantages of using the Pinniped Supervisor
+
+Although you can choose to use Pinniped without using the Pinniped Supervisor, there are several key advantages of choosing to use the Pinniped Supervisor to manage identity across fleets of Kubernetes clusters.
+
+1. A generated kubeconfig for a cluster will be specific for that cluster, however **it will not contain any specific user identity or credentials. 
+   This kubeconfig file can be safely shared with all cluster users.** When the user runs `kubectl` commands using this kubeconfig, they will be interactively prompted to log in using their own unique identity from the OIDC or LDAP identity provider configured in the Supervisor.
+
+1. The Supervisor will provide a federated identity across all clusters that use the same `FederationDomain`. 
+   The user will be **prompted by `kubectl`  to interactively authenticate once per day**, and then will be able to use all clusters 
+   from the same `FederationDomain` for the rest of the day without being asked to authenticate again. 
+   This federated identity is secure because behind the scenes the Supervisor is issuing very short-lived credentials
+   that are uniquely scoped to each cluster.
+
+1. The Supervisor makes it easy to **bring your own OIDC or LDAP identity provider to act as the source of user identities**. 
+   It also allows you to configure how identities and group memberships in the OIDC or LDAP identity provider map to identities 
+   and group memberships in the Kubernetes clusters.
+
+## Generate a Pinniped-compatible kubeconfig file
+
+You will need to generate a Pinniped-compatible kubeconfig file for each cluster in which you have installed the Concierge.
+This requires admin-level access to each cluster, so this would typically be performed by the same user who installed the Concierge.
+
+For each cluster, use `pinniped get kubeconfig` to generate the new kubeconfig file for that cluster.
+
+It is typically sufficient to run this command with no arguments, aside from pointing the command at your admin kubeconfig.
+The command uses the [same rules](https://kubernetes.io/docs/concepts/configuration/organize-cluster-access-kubeconfig/)
+as `kubectl` to find your admin kubeconfig:
+
+> "By default, `kubectl` looks for a file named config in the `$HOME/.kube` directory. You can specify other kubeconfig files by setting the `KUBECONFIG` environment variable or by setting the `--kubeconfig` flag."
+
+For example, if your admin `kubeconfig` file were at the path `$HOME/admin-kubeconfig.yaml`, then you could use:
+
+```sh
+pinniped get kubeconfig \
+  --kubeconfig "$HOME/admin-kubeconfig.yaml" > pinniped-kubeconfig.yaml
+```
+
+The new Pinniped-compatible kubeconfig YAML will be output as stdout, and can be redirected to a file.
+
+Various default behaviors of `pinniped get kubeconfig` can be overridden using [its command-line options]({{< ref "cli" >}}).
+
+## Use the generated kubeconfig with `kubectl` to access the cluster
+
+A cluster user will typically be given a Pinniped-compatible kubeconfig by their cluster admin. They can use this kubeconfig
+with `kubectl` just like any other kubeconfig, as long as they have also installed the `pinniped` CLI tool at the
+same absolute path where it is referenced inside the kubeconfig's YAML. The `pinniped` CLI will act as a `kubectl` plugin
+to manage the user's authentication to the cluster.
+
+For example, if the kubeconfig were saved at `$HOME/pinniped-kubeconfig.yaml`:
+
+```bash
+kubectl get namespaces \
+  --kubeconfig "$HOME/pinniped-kubeconfig.yaml"
+```
+
+This command, when configured to use the Pinniped-compatible kubeconfig, will invoke the `pinniped` CLI behind the scenes
+as an [ExecCredential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins)
+to authenticate the user to the cluster.
+
+If the Pinniped Supervisor is used for authentication to that cluster, then the user's authentication experience
+will depend on which type of identity provider was configured.
+
+- For an OIDC identity provider, `kubectl` will open the user's web browser and direct it to the login page of
+  their OIDC Provider. This login flow is controlled by the provider, so it may include two-factor authentication or
+  other features provided by the OIDC Provider.
+   
+  If the user's browser is not available, then `kubectl` will instead print a URL which can be visited in a
+  browser (potentially on a different computer) to complete the authentication.
+
+- For an LDAP identity provider, `kubectl` will interactively prompt the user for their username and password at the CLI.
+   
+  Alternatively, the user can set the environment variables `PINNIPED_USERNAME` and `PINNIPED_PASSWORD` for the
+  `kubectl` process to avoid the interactive prompts.
+
+Once the user completes authentication, the `kubectl` command will automatically continue and complete the user's requested command.
+For the example above, `kubectl` would list the cluster's namespaces.
+
+## Authorization
+
+Pinniped provides authentication (usernames and group memberships) but not authorization. Kubernetes authorization is often
+provided by the [Kubernetes RBAC system](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) on each cluster.
+
+In the example above, if the user gets an access denied error, then they may need authorization to list namespaces.
+For example, an admin could grant the user "edit" access to all cluster resources via the user's username:
+
+  ```sh
+  kubectl create clusterrolebinding my-user-can-edit \
+    --clusterrole edit \
+    --user my-username@example.com
+  ```
+
+Alternatively, an admin could create role bindings based on the group membership of the users
+in the upstream identity provider, for example:
+
+  ```sh
+  kubectl create clusterrolebinding my-auditors \
+    --clusterrole view \
+    --group auditors
+  ```
+
+## Other notes
+
+- Temporary session credentials such as ID, access, and refresh tokens are stored in:
+    - `~/.config/pinniped/sessions.yaml` (macOS/Linux)
+    - `%USERPROFILE%/.config/pinniped/sessions.yaml` (Windows).

test/integration/e2e_test.go

@@ -249,15 +249,16 @@ func TestE2EFullIntegration(t *testing.T) {
 		// It should now be in the "success" state.
 		formpostExpectSuccessState(t, page)
 
-		// Expect the CLI to output a list of namespaces in JSON format.
+		// Expect the CLI to output a list of namespaces.
-		t.Logf("waiting for kubectl to output namespace list JSON")
+		t.Logf("waiting for kubectl to output namespace list")
 		var kubectlOutput string
 		select {
 		case <-time.After(10 * time.Second):
 			require.Fail(t, "timed out waiting for kubectl output")
 		case kubectlOutput = <-kubectlOutputChan:
 		}
-		require.Greaterf(t, len(strings.Split(kubectlOutput, "\n")), 2, "expected some namespaces to be returned, got %q", kubectlOutput)
+		requireKubectlGetNamespaceOutput(t, env, kubectlOutput)
+
 		t.Logf("first kubectl command took %s", time.Since(start).String())
 
 		requireUserCanUseKubectlWithoutAuthenticatingAgain(ctx, t, env,
@@ -364,10 +365,11 @@ func TestE2EFullIntegration(t *testing.T) {
 
 		// Read all of the remaining output from the subprocess until EOF.
 		t.Logf("waiting for kubectl to output namespace list")
-		remainingOutput, _ := ioutil.ReadAll(ptyFile)
+		// Read all of the output from the subprocess until EOF.
 		// Ignore any errors returned because there is always an error on linux.
-		require.Greaterf(t, len(remainingOutput), 0, "expected to get some more output from the kubectl subcommand, but did not")
+		kubectlOutputBytes, _ := ioutil.ReadAll(ptyFile)
-		require.Greaterf(t, len(strings.Split(string(remainingOutput), "\n")), 2, "expected some namespaces to be returned, got %q", string(remainingOutput))
+		requireKubectlGetNamespaceOutput(t, env, string(kubectlOutputBytes))
+
 		t.Logf("first kubectl command took %s", time.Since(start).String())
 
 		requireUserCanUseKubectlWithoutAuthenticatingAgain(ctx, t, env,
@@ -380,8 +382,9 @@ func TestE2EFullIntegration(t *testing.T) {
 		)
 	})
 
-	// Add an LDAP upstream IDP and try using it to authenticate during kubectl commands.
+	// Add an LDAP upstream IDP and try using it to authenticate during kubectl commands
-	t.Run("with Supervisor LDAP upstream IDP", func(t *testing.T) {
+	// by interacting with the CLI's username and password prompts.
+	t.Run("with Supervisor LDAP upstream IDP using username and password prompts", func(t *testing.T) {
 		if len(env.ToolsNamespace) == 0 && !env.HasCapability(testlib.CanReachInternetLDAPPorts) {
 			t.Skip("LDAP integration test requires connectivity to an LDAP server")
 		}
@@ -389,12 +392,130 @@ func TestE2EFullIntegration(t *testing.T) {
 		expectedUsername := env.SupervisorUpstreamLDAP.TestUserMailAttributeValue
 		expectedGroups := env.SupervisorUpstreamLDAP.TestUserDirectGroupsDNs
 
+		setupClusterForEndToEndLDAPTest(t, expectedUsername, env)
+
+		// Use a specific session cache for this test.
+		sessionCachePath := tempDir + "/ldap-test-sessions.yaml"
+
+		kubeconfigPath := runPinnipedGetKubeconfig(t, env, pinnipedExe, tempDir, []string{
+			"get", "kubeconfig",
+			"--concierge-api-group-suffix", env.APIGroupSuffix,
+			"--concierge-authenticator-type", "jwt",
+			"--concierge-authenticator-name", authenticator.Name,
+			"--oidc-session-cache", sessionCachePath,
+		})
+
+		// Run "kubectl get namespaces" which should trigger an LDAP-style login CLI prompt via the plugin.
+		start := time.Now()
+		kubectlCmd := exec.CommandContext(ctx, "kubectl", "get", "namespace", "--kubeconfig", kubeconfigPath)
+		kubectlCmd.Env = append(os.Environ(), env.ProxyEnv()...)
+		ptyFile, err := pty.Start(kubectlCmd)
+		require.NoError(t, err)
+
+		// Wait for the subprocess to print the username prompt, then type the user's username.
+		readFromFileUntilStringIsSeen(t, ptyFile, "Username: ")
+		_, err = ptyFile.WriteString(expectedUsername + "\n")
+		require.NoError(t, err)
+
+		// Wait for the subprocess to print the password prompt, then type the user's password.
+		readFromFileUntilStringIsSeen(t, ptyFile, "Password: ")
+		_, err = ptyFile.WriteString(env.SupervisorUpstreamLDAP.TestUserPassword + "\n")
+		require.NoError(t, err)
+
+		// Read all of the output from the subprocess until EOF.
+		// Ignore any errors returned because there is always an error on linux.
+		kubectlOutputBytes, _ := ioutil.ReadAll(ptyFile)
+		requireKubectlGetNamespaceOutput(t, env, string(kubectlOutputBytes))
+
+		t.Logf("first kubectl command took %s", time.Since(start).String())
+
+		requireUserCanUseKubectlWithoutAuthenticatingAgain(ctx, t, env,
+			downstream,
+			kubeconfigPath,
+			sessionCachePath,
+			pinnipedExe,
+			expectedUsername,
+			expectedGroups,
+		)
+	})
+
+	// Add an LDAP upstream IDP and try using it to authenticate during kubectl commands
+	// by passing username and password via environment variables, thus avoiding the CLI's username and password prompts.
+	t.Run("with Supervisor LDAP upstream IDP using PINNIPED_USERNAME and PINNIPED_PASSWORD env vars", func(t *testing.T) {
+		if len(env.ToolsNamespace) == 0 && !env.HasCapability(testlib.CanReachInternetLDAPPorts) {
+			t.Skip("LDAP integration test requires connectivity to an LDAP server")
+		}
+
+		expectedUsername := env.SupervisorUpstreamLDAP.TestUserMailAttributeValue
+		expectedGroups := env.SupervisorUpstreamLDAP.TestUserDirectGroupsDNs
+
+		setupClusterForEndToEndLDAPTest(t, expectedUsername, env)
+
+		// Use a specific session cache for this test.
+		sessionCachePath := tempDir + "/ldap-test-with-env-vars-sessions.yaml"
+
+		kubeconfigPath := runPinnipedGetKubeconfig(t, env, pinnipedExe, tempDir, []string{
+			"get", "kubeconfig",
+			"--concierge-api-group-suffix", env.APIGroupSuffix,
+			"--concierge-authenticator-type", "jwt",
+			"--concierge-authenticator-name", authenticator.Name,
+			"--oidc-session-cache", sessionCachePath,
+		})
+
+		// Set up the username and password env vars to avoid the interactive prompts.
+		const usernameEnvVar = "PINNIPED_USERNAME"
+		originalUsername, hadOriginalUsername := os.LookupEnv(usernameEnvVar)
+		t.Cleanup(func() {
+			if hadOriginalUsername {
+				require.NoError(t, os.Setenv(usernameEnvVar, originalUsername))
+			}
+		})
+		require.NoError(t, os.Setenv(usernameEnvVar, expectedUsername))
+		const passwordEnvVar = "PINNIPED_PASSWORD" //nolint:gosec // this is not a credential
+		originalPassword, hadOriginalPassword := os.LookupEnv(passwordEnvVar)
+		t.Cleanup(func() {
+			if hadOriginalPassword {
+				require.NoError(t, os.Setenv(passwordEnvVar, originalPassword))
+			}
+		})
+		require.NoError(t, os.Setenv(passwordEnvVar, env.SupervisorUpstreamLDAP.TestUserPassword))
+
+		// Run "kubectl get namespaces" which should run an LDAP-style login without interactive prompts for username and password.
+		start := time.Now()
+		kubectlCmd := exec.CommandContext(ctx, "kubectl", "get", "namespace", "--kubeconfig", kubeconfigPath)
+		kubectlCmd.Env = append(os.Environ(), env.ProxyEnv()...)
+		ptyFile, err := pty.Start(kubectlCmd)
+		require.NoError(t, err)
+
+		// Read all of the output from the subprocess until EOF.
+		// Ignore any errors returned because there is always an error on linux.
+		kubectlOutputBytes, _ := ioutil.ReadAll(ptyFile)
+		requireKubectlGetNamespaceOutput(t, env, string(kubectlOutputBytes))
+
+		t.Logf("first kubectl command took %s", time.Since(start).String())
+
+		// The next kubectl command should not require auth, so we should be able to run it without these env vars.
+		require.NoError(t, os.Unsetenv(usernameEnvVar))
+		require.NoError(t, os.Unsetenv(passwordEnvVar))
+
+		requireUserCanUseKubectlWithoutAuthenticatingAgain(ctx, t, env,
+			downstream,
+			kubeconfigPath,
+			sessionCachePath,
+			pinnipedExe,
+			expectedUsername,
+			expectedGroups,
+		)
+	})
+}
+
+func setupClusterForEndToEndLDAPTest(t *testing.T, username string, env *testlib.TestEnv) {
 	// Create a ClusterRoleBinding to give our test user from the upstream read-only access to the cluster.
 	testlib.CreateTestClusterRoleBinding(t,
-			rbacv1.Subject{Kind: rbacv1.UserKind, APIGroup: rbacv1.GroupName, Name: expectedUsername},
+		rbacv1.Subject{Kind: rbacv1.UserKind, APIGroup: rbacv1.GroupName, Name: username},
 		rbacv1.RoleRef{Kind: "ClusterRole", APIGroup: rbacv1.GroupName, Name: "view"},
 	)
-		testlib.WaitForUserToHaveAccess(t, expectedUsername, []string{}, &authorizationv1.ResourceAttributes{
+	testlib.WaitForUserToHaveAccess(t, username, []string{}, &authorizationv1.ResourceAttributes{
 		Verb:     "get",
 		Group:    "",
 		Version:  "v1",
@@ -434,51 +555,6 @@ func TestE2EFullIntegration(t *testing.T) {
 			},
 		},
 	}, idpv1alpha1.LDAPPhaseReady)
-
-		// Use a specific session cache for this test.
-		sessionCachePath := tempDir + "/ldap-test-sessions.yaml"
-
-		kubeconfigPath := runPinnipedGetKubeconfig(t, env, pinnipedExe, tempDir, []string{
-			"get", "kubeconfig",
-			"--concierge-api-group-suffix", env.APIGroupSuffix,
-			"--concierge-authenticator-type", "jwt",
-			"--concierge-authenticator-name", authenticator.Name,
-			"--oidc-session-cache", sessionCachePath,
-		})
-
-		// Run "kubectl get namespaces" which should trigger an LDAP-style login CLI prompt via the plugin.
-		start := time.Now()
-		kubectlCmd := exec.CommandContext(ctx, "kubectl", "get", "namespace", "--kubeconfig", kubeconfigPath)
-		kubectlCmd.Env = append(os.Environ(), env.ProxyEnv()...)
-		ptyFile, err := pty.Start(kubectlCmd)
-		require.NoError(t, err)
-
-		// Wait for the subprocess to print the username prompt, then type the user's username.
-		readFromFileUntilStringIsSeen(t, ptyFile, "Username: ")
-		_, err = ptyFile.WriteString(expectedUsername + "\n")
-		require.NoError(t, err)
-
-		// Wait for the subprocess to print the password prompt, then type the user's password.
-		readFromFileUntilStringIsSeen(t, ptyFile, "Password: ")
-		_, err = ptyFile.WriteString(env.SupervisorUpstreamLDAP.TestUserPassword + "\n")
-		require.NoError(t, err)
-
-		// Read all of the remaining output from the subprocess until EOF.
-		remainingOutput, _ := ioutil.ReadAll(ptyFile)
-		// Ignore any errors returned because there is always an error on linux.
-		require.Greaterf(t, len(remainingOutput), 0, "expected to get some more output from the kubectl subcommand, but did not")
-		require.Greaterf(t, len(strings.Split(string(remainingOutput), "\n")), 2, "expected some namespaces to be returned, got %q", string(remainingOutput))
-		t.Logf("first kubectl command took %s", time.Since(start).String())
-
-		requireUserCanUseKubectlWithoutAuthenticatingAgain(ctx, t, env,
-			downstream,
-			kubeconfigPath,
-			sessionCachePath,
-			pinnipedExe,
-			expectedUsername,
-			expectedGroups,
-		)
-	})
 }
 
 func readFromFileUntilStringIsSeen(t *testing.T, f *os.File, until string) string {
@@ -510,6 +586,19 @@ func readAvailableOutput(t *testing.T, r io.Reader) (string, bool) {
 	return string(buf[:n]), false
 }
 
+func requireKubectlGetNamespaceOutput(t *testing.T, env *testlib.TestEnv, kubectlOutput string) {
+	t.Log("kubectl command output:\n", kubectlOutput)
+	require.Greaterf(t, len(kubectlOutput), 0, "expected to get some more output from the kubectl subcommand, but did not")
+
+	// Should look generally like a list of namespaces, with one namespace listed per line in a table format.
+	require.Greaterf(t, len(strings.Split(kubectlOutput, "\n")), 2, "expected some namespaces to be returned, got %q", kubectlOutput)
+	require.Contains(t, kubectlOutput, fmt.Sprintf("\n%s ", env.ConciergeNamespace))
+	require.Contains(t, kubectlOutput, fmt.Sprintf("\n%s ", env.SupervisorNamespace))
+	if len(env.ToolsNamespace) == 0 {
+		require.Contains(t, kubectlOutput, fmt.Sprintf("\n%s ", env.ToolsNamespace))
+	}
+}
+
 func requireUserCanUseKubectlWithoutAuthenticatingAgain(
 	ctx context.Context,
 	t *testing.T,