update cicd.md to discuss using multiple IDPs for human vs bot accounts

site/content/docs/howto/cicd.md

@@ -16,11 +16,12 @@ Pinniped provides user authentication to Kubernetes clusters.
 It does not provide service-to-service (non-user) authentication.
 There are many other systems for service-to-service authentication in Kubernetes.
 
-If an organization prefers to manage CI/CD access with non-human user accounts in their IDP, Pinniped can provide authentication for those
-non-human user accounts. Humans can also use the same steps below to log into clusters non-interactively.
+If an organization prefers to manage CI/CD access with non-human user accounts in their external identity provider (IDP),
+Pinniped can provide authentication for those non-human user accounts. Humans can also use the same steps below to log
+into clusters non-interactively.
 
 Note that the guide below assumes that you are using a non-human user account within the IDP of your choice.
-It is never recommended to use a human's credentials for CI/CD or other automated processes.
+It is never recommended to share a human's credentials for CI/CD or other automated processes.
 
 ## Prerequisites
 
@@ -38,8 +39,8 @@ on each cluster.
    * It can run shell scripts, or at least invoke binaries (such as `pinniped` and `kubectl`) 
    * It can access Pinniped-style kubeconfigs for each cluster
 4. A user account (that does not represent a human) within the IDP of your choice
-   * This account should be granted the least amount of privileges necessary
-   * This account should likely be single-purposed for CI/CD use
+   * This account should be granted the least amount of privileges necessary in your Kubernetes clusters
+   * This account should likely be created single-purpose for CI/CD use
 
 ## Overview
 
@@ -49,8 +50,50 @@ on each cluster.
    * When using OIDC, the optional CLI-based flow must be enabled by the administrator in the OIDCIdentityProvider configuration before use
      (see `allowPasswordGrant` in the [API docs](https://github.com/vmware-tanzu/pinniped/blob/main/generated/latest/README.adoc#oidcauthorizationconfig) for more details).
 2. A CI/CD admin should make the non-human user account credentials available to CI/CD tasks
-3. Each CI/CD task should set the environment variables `PINNIPED_USERNAME` and `PINNIPED_PASSWORD` for the `kubectl` process to avoid the interactive prompts.
-The values should be provided from the non-human user account credentials.
+3. Each CI/CD task should set the environment variables `PINNIPED_USERNAME` and `PINNIPED_PASSWORD` for the `kubectl` (or similar)
+   process to avoid the interactive username and password prompts. The values should be provided from the non-human user account credentials.
 
 At this point, your CI/CD has now authenticated into your kubernetes cluster.
 Be sure to set up the appropriate IDP groups and Kubernetes roles to enable your non-human user account to perform the necessary operations.
+
+## GitHubIdentityProvider
+
+Currently, the GitHubIdentityProvider resource does not support the `cli_password` flow, due to limitations of
+GitHub's OAuth 2.0 authentication system. Therefore, the above steps for non-interactive authentication will not
+work for GitHubIdentityProvider.
+
+However, if your human users are authenticating using their GitHub identities, you can still use non-human identities
+for CI/CD tasks by configuring another identity provider on your Pinniped Supervisor FederationDomain. That secondary
+identity provider can be OIDC, LDAP, or Active Directory, which all support the `cli_password` flow. For more details,
+see below.
+
+## Getting your human and non-human identities from different IDPs
+
+The Pinniped Supervisor supports configuring multiple identity providers. This makes it possible to source human
+and non-human identities from different IDPs.
+
+Consider the following example use cases:
+1. Your human users authenticate using their GitHub identities, but since GitHubIdentityProvider does not support
+   non-interactive authentication, your non-human users will use OIDC, LDAP, or AD for authentication.
+2. Your human users authenticate with your OIDC provider, and they are always required to provide multiple
+   factors (e.g. OTP codes) during authentication. Your non-human users also come from the same OIDC provider, but
+   they should be allowed to authenticate with only a username and password.
+
+Both of these examples can be solved by configuring multiple identity providers:
+1. For the first example, configure a GitHubIdentityProvider for your human users. Also create an OIDCIdentityProvider,
+   LDAPIdentityProvider, or ActiveDirectoryIdentityProvider for the non-human accounts. Configure your FederationDomain
+   to use both providers. Create kubeconfigs using the GitHub provider and distribute them to your human users.
+   Create kubeconfigs for your CI/CD use cases using the second provider.
+2. For the second example, configure an OIDCIdentityProvider for your human users. Disable non-interactive
+   authentication (see `allowPasswordGrant` in the [API docs](https://github.com/vmware-tanzu/pinniped/blob/main/generated/latest/README.adoc#oidcauthorizationconfig)). Create another OIDCIdentityProvider for your
+   non-human users, and enable non-interactive authentication for it. For the second OIDCIdentityProvider, use a
+   different client ID and client secret from your OIDC provider. Configure your FederationDomain to use both providers.
+   In your OIDC provider's admin UI, configure this second client to allow the Resource Owner Password Credentials Grant
+   and to not require multi-factor authentication. Prevent human users from using this second OIDCIdentityProvider
+   by either configuring which users are allowed for that client in your OIDC provider's admin UI, or by configuring
+   identity policies for it on your FederationDomain to reject auth from all users except those with certain non-human
+   usernames or group memberships. Create kubeconfigs using the first provider and distribute them to your human users.
+   Create kubeconfigs for your CI/CD use cases using the second provider.
+
+For more information, refer to the documentation about
+[using multiple identity providers and identity policies]({{< ref "../howto/supervisor/configure-supervisor-federationdomain-idps" >}}).