multiple IDPs and identity transformations docs

site/content/docs/background/architecture.md

@@ -17,7 +17,7 @@ environments with zero configuration.
 Pinniped is composed of two parts.
 
 1. The Pinniped Supervisor is an OIDC server which allows users to authenticate
-with an external identity provider (IDP), and then issues its own federation ID tokens
+with external identity providers (IDP), and then issues its own federation ID tokens
 to be passed on to clusters based on the user information from the IDP.
 1. The Pinniped Concierge is a credential exchange API which takes as input a
 credential from an identity source (e.g., Pinniped Supervisor, proprietary IDP),

site/content/docs/howto/configure-auth-for-webapps.md

@@ -46,6 +46,11 @@ framework (e.g. Spring, Rails, Django, etc.) to implement authentication. The Su
 - Clients must use `query` as the
   [response_mode](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) at the authorization endpoint,
   or not specify the `response_mode` param, which defaults to `query`.
+- If the Supervisor's FederationDomain was configured with explicit `identityProviders` in its spec, then the
+  client must send an extra parameter on the initial authorization request to indicate which identity provider
+  the user would like to use when authenticating. This parameter is called `pinniped_idp_name` and the value
+  of the parameter should be set to the `displayName` of the identity provider as it was configured on the
+  FederationDomain.
 
 Most web application frameworks offer all these capabilities in their OAuth2/OIDC libraries.
 

site/content/docs/howto/login.md

@@ -76,6 +76,11 @@ One flag of note is `--upstream-identity-provider-flow browser_authcode` to choo
 (the default for OIDCIdentityProviders), and `--upstream-identity-provider-flow cli_password` to choose end-user `kubectl`
 login via CLI username/password prompts (the default for LDAPIdentityProviders and ActiveDirectoryIdentityProviders).
 
+If the cluster is using a Pinniped Supervisor's FederationDomain to provide authentication services,
+and if that FederationDomain allows multiple identity providers, then you will need to specify which identity provider
+you would like to use in the resulting kubeconfig with the `--upstream-identity-provider-name` and/or `--upstream-identity-provider-type` flags.
+You may call `pinniped get kubeconfig` multiple times to generate multiple kubeconfigs for the cluster.
+
 ## 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

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

@@ -11,8 +11,8 @@ menu:
 aliases:
   - /docs/howto/configure-supervisor-with-activedirectory/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using their identity from Active Directory.

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

@@ -11,8 +11,8 @@ menu:
 aliases:
    - /docs/howto/configure-supervisor-with-auth0/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using their Auth0 credentials.

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

@@ -12,8 +12,8 @@ aliases:
   - /docs/howto/configure-supervisor-with-dex/
 ---
 
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using Dex and Github.

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

@@ -11,8 +11,8 @@ menu:
 aliases:
    - /docs/howto/configure-supervisor-with-gitlab/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using their GitLab credentials.

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

@@ -11,8 +11,8 @@ menu:
 aliases:
    - /docs/howto/configure-supervisor-with-jumpcloudldap/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 [JumpCloud](https://jumpcloud.com) is a cloud-based service which bills itself as
 "a comprehensive and flexible cloud directory platform". It includes the capability to act as an LDAP identity provider.

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

@@ -11,8 +11,8 @@ menu:
 aliases:
    - /docs/howto/configure-supervisor-with-okta/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using their Okta credentials.

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

@@ -11,8 +11,8 @@ menu:
 aliases: 
   - /docs/howto/configure-supervisor-with-openldap/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 [OpenLDAP](https://www.openldap.org) is a popular open source LDAP server for Linux/UNIX.
 

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

@@ -11,8 +11,8 @@ menu:
 aliases:
    - /docs/howto/configure-supervisor-with-workspace_one_access/
 ---
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients.
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients.
 
 This guide shows you how to configure the Supervisor so that users can authenticate to their Kubernetes
 cluster using their [Workspace ONE Access](https://www.vmware.com/products/workspace-one/access.html) credentials.

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

@@ -12,8 +12,8 @@ aliases:
   - /docs/howto/configure-supervisor/
 ---
 
-The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting a single
-"upstream" identity provider to many "downstream" cluster clients. When a user authenticates, the Supervisor can issue
+The Supervisor is an [OpenID Connect (OIDC)](https://openid.net/connect/) issuer that supports connecting
+"upstream" identity providers to many "downstream" cluster clients. When a user authenticates, the Supervisor can issue
 [JSON Web Tokens (JWTs)](https://tools.ietf.org/html/rfc7519) that can be [validated by the Pinniped Concierge]({{< ref "configure-concierge-jwt" >}}).
 
 This guide explains how to expose the Supervisor's REST endpoints to clients.
@@ -246,10 +246,54 @@ spec:
   # for the HTTPS endpoints served by this OIDC Provider.
   tls:
     secretName: my-tls-cert-secret
+  # Configure which identity providers (OIDCIdentityProvider,
+  # ActiveDirectoryIdentityProvider, or LDAPIdentityProvider)
+  # shall be used by this FederationDomain.
+  identityProviders:
+    # See the "IDPs on FederationDomains" Supervisor configuration guide
+    # for details on how to configure this section of the FederationDomain's
+    # spec.
 ```
 
-You can create multiple FederationDomains as long as each has a unique issuer string.
+### How FederationDomains Work
+
 Each FederationDomain can be used to provide access to a set of Kubernetes clusters for a set of user identities.
+A FederationDomain will allow the same set of users to authenticate into all Kubernetes clusters
+which choose to trust that FederationDomain to provide authentication services. Authenticating to a FederationDomain
+will only provide access to those clusters which choose to trust that FederationDomain, and will not provide access
+to any clusters that are trusting other FederationDomains. Therefore, FederationDomains are a means of providing
+authentication isolation.
+
+You can create multiple FederationDomains in a single Pinniped Supervisor, as long as each has a unique issuer string.
+
+When a user authenticates into any cluster that chooses to trust the FederationDomain for authentication,
+then the user has started a single sign-on session with that FederationDomain which will last approximately 9 hours.
+The user will not need to manually authenticate again into any cluster any cluster that chooses to trust the
+FederationDomain for authentication until the session expires. Behind the scenes, the user's client (e.g. `kubectl`)
+will only be given short-lived access to each cluster (approximately 5 minutes), but will automatically refresh those
+credentials without the need for user interaction. During each refresh, the Supervisor will perform checks against
+the external identity provider to determine if the user's session should be allowed to continue.
+A user may have active sessions with multiple FederationDomains at the same time, but each will require authenticating
+separately to start the single sign-on session with that FederationDomain.
+
+Technically, each FederationDomain is a separate OIDC issuer which serves multiple REST endpoints to clients, such
+as the Pinniped CLI. The tokens issued by each FederationDomain are signed by that FederationDomain and cannot
+be used by any other FederationDomain, which provides the isolation properties of the FederationDomain concept.
+
+Any Kubernetes cluster can choose to trust a FederationDomain to provide user authentication
+for that cluster by using the FederationDomain its OIDC issuer for JSON Web Token (JWT) formatted ID tokens.
+This can be done by installing the Pinniped Concierge on each cluster and
+[configuring the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}})
+on each cluster. Alternatively, it can be done by [configuring the Kubernetes API server on each cluster to use
+the FederationDomain as its OIDC issuer]({{< ref "../../tutorials/supervisor-without-concierge-demo" >}}).
+
+When two FederationDomains use the same hostname in the `spec.issuer`, then:
+1. They must use different paths in their `spec.issuer` URLs to differentiate them from each other.
+2. They must use the same `tls.secretName` if they both configure a `tls.secretName` (see below for details of TLS configuration).
+
+The Supervisor uses the hostname on the each incoming request to determine which TLS certificate to serve for that
+request, and then it uses the path to determine which FederationDomain should serve the request if there are multiple
+FederationDomains with the same hostname.
 
 ### Configuring TLS for the Supervisor OIDC endpoints
 
@@ -295,6 +339,7 @@ should be signed by a certificate authority that is trusted by their browsers.
 ## Next steps
 
 Next, configure an OIDCIdentityProvider, ActiveDirectoryIdentityProvider, or an LDAPIdentityProvider for the Supervisor
-(several examples are available in these guides). Then
+(several examples are available in these guides). Then learn [how to configure a FederationDomain to use one or more
+identity providers]({{< ref "configure-supervisor-federationdomain-idps" >}}). And finally,
 [configure the Concierge to use the Supervisor for authentication]({{< ref "configure-concierge-supervisor-jwt" >}})
-on each cluster!
+on each cluster.