From fcf6ec67311269a1502b5b9223e15dbb9bd474b4 Mon Sep 17 00:00:00 2001 From: Ryan Richard Date: Wed, 7 Aug 2024 10:39:30 -0700 Subject: [PATCH] update cicd.md to discuss using multiple IDPs for human vs bot accounts --- site/content/docs/howto/cicd.md | 57 +++++++++++++++++++++++++++++---- 1 file changed, 50 insertions(+), 7 deletions(-) diff --git a/site/content/docs/howto/cicd.md b/site/content/docs/howto/cicd.md index 87fbddf24..09b1cef66 100644 --- a/site/content/docs/howto/cicd.md +++ b/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" >}}).