More doc updates

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

@@ -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 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.
+
 ## Create a JWTAuthenticator
 
 Create a JWTAuthenticator describing how to validate tokens from your Supervisor's FederationDomain:
@@ -36,15 +39,18 @@ kind: JWTAuthenticator
 metadata:
   name: my-supervisor-authenticator
 spec:
+
   # The value of the `issuer` field should exactly match the `issuer`
   # field of your Supervisor's FederationDomain.
   issuer: https://my-issuer.example.com/any/path
+
   # You can use any `audience` identifier for your cluster, but it is
   # important that it is unique for security reasons.
   audience: my-unique-cluster-identifier-da79fa849
+
   # If the TLS certificate of your FederationDomain is not signed by
-  # a standard CA trusted by the Concierge pods, then specify its CA
+  # a standard CA trusted by the Concierge pods by default, then
-  # as a base64-encoded PEM.
+  # specify its CA here as a base64-encoded PEM.
   tls:
     certificateAuthorityData: LS0tLS1CRUdJTiBDRVJUSUZJQ0...0tLQo=
 ```
@@ -66,8 +72,14 @@ Generate a kubeconfig file for one of the clusters in which you installed and co
 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
 
@@ -95,6 +107,15 @@ You should see:
     --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.

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

@@ -5,7 +5,7 @@ cascade:
   layout: docs
 menu:
   docs:
-    name: Configure Supervisor With GitLab
+    name: Configure Supervisor With GitLab OIDC
     weight: 90
     parent: howtos
 ---

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

@@ -16,7 +16,7 @@ The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer
 "a comprehensive and flexible cloud directory platform". It includes the capability to act as an LDAP identity provider.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
-cluster using their identity from an JumpCloud's LDAP service.
+cluster using their identity from JumpCloud's LDAP service.
 
 ## Prerequisites
 

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

@@ -5,7 +5,7 @@ cascade:
   layout: docs
 menu:
   docs:
-    name: Configure Supervisor With Okta
+    name: Configure Supervisor With Okta OIDC
     weight: 80
     parent: howtos
 ---

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

@@ -5,7 +5,7 @@ cascade:
   layout: docs
 menu:
   docs:
-    name: Configure Supervisor
+    name: Configure Supervisor as an OIDC Issuer
     weight: 70
     parent: howtos
 ---
@@ -110,7 +110,7 @@ spec:
 
 ### Configuring the Supervisor to act as an OIDC provider
 
-The Supervisor can be configured as an OIDC provider by creating `FederationDomain` resources
+The Supervisor can be configured as an OIDC provider by creating FederationDomain resources
 in the same namespace where the Supervisor app was installed. For example:
 
 ```yaml
@@ -131,6 +131,9 @@ spec:
     secretName: my-tls-cert-secret
 ```
 
+You can create multiple FederationDomains as long as each has a unique issuer string.
+Each FederationDomain can be used to provide access to a set of Kubernetes clusters for a set of user identities.
+
 #### Configuring TLS for the Supervisor OIDC endpoints
 
 If you have terminated TLS outside the app, for example using an Ingress with TLS certificates, then you do not need to