Pinniped v0.26.0: Multiple identity providers and identity transformations

Ryan Richard

Sep 19, 2023

Photo from Unsplash

Pinniped’s v0.26.0 relase provides powerful new features enabling cluster administrators to configure their Kubernetes clusters to accept identities from multiple identity providers. Pinniped now enables the simultaneous support of OpenID Connect (OIDC), Lightweight Directory Access Protocol (LDAP), and Active Directory (AD) configured for either one or many clusters. In addition, Pinniped provides a powerful identity transformation mechanism via Common Expression Language (CEL) to enable disambiguation of identities funneled in from different identity providers and more. If you want to learn about using multiple different identity providers with a fleet of clusters federated to a single identity broker, read on!

Additionally, the release includes several dependency updates and fixes. See the release notes for more details.

Background: Identity provider resources

In Kubernetes, a user identity is a username string and a list of group name strings.

Each OIDCIdentityProvider, LDAPIdentityProvider, or ActiveDirectoryIdentityProvider configures how to use a specific protocol (e.g. OIDC or LDAP) to authenticate users and to extract their identities (usernames and group names) for Kubernetes from those external identity providers.

Prior to this release, the Pinniped Supervisor would only allow the use of a single OIDCIdentityProvider, LDAPIdentityProvider, or ActiveDirectoryIdentityProvider at a time. With this new release, you can now use multiple simultaneous identity providers from which to draw user identities.

New: Multiple FederationDomains

The Pinniped Supervisor offers a custom resource called FederationDomain. Any Kubernetes cluster may trust a Supervisor’s FederationDomain to provide authentication services for the cluster. Each FederationDomain defines which users may authenticate into those clusters, and how those users go about authenticating. So, for a given FederationDomain, the same users may authenticate into all the clusters which trust that FederationDomain.

Once authenticated, each cluster may use different authorization policies (e.g. Kubernetes RBAC rules) to determine the capabilities of each user. Pinniped provides user authentication, while still allowing you to choose your preferred system for user authorization on each cluster.

You may configure multiple FederationDomains in the Pinniped Supervisor. Each must have a unique URL called an “issuer URL”. These URLs can be unique by using different hostnames (a form of virtual hosting) or they can simply have different paths on the same host.

When a user authenticates to a FederationDomain, they start a single sign-on session for that FederationDomain only. The user may use all clusters which trust that FederationDomain for the rest of the day without being prompted to authenticate again. Behind the scenes, the Supervisor is constantly checking with the external identity provider to ensure that the user should be allowed to continue their ongoing session.

Prior to this release, there was no way to configure each FederationDomain to be meaningfully different from the others within a single Pinniped Supervisor. However, starting with this release, you can now configure each FederationDomain to allow a different pool of users. (See below for more details.) This makes it possible to use multiple FederationDomains in a single Pinniped Supervisor.

New: Multiple identity providers

This release adds a new spec.identityProviders configuration option to the FederationDomains resource. Each FederationDomain may choose which OIDCIdentityProviders, LDAPIdentityProviders, and ActiveDirectoryIdentityProviders users may use to authenticate into the clusters which trust that FederationDomain.

Why would an administrator want to use multiple identity providers? Here are some examples:

• You might like to configure multiple FederationDomains, each using a different identity provider. Each FederationDomain can be used to provide authentication to a group of Kubernetes clusters. For example, you could configure a FederationDomain for each division of your R&D department, thus preventing developers of each division from using each other’s clusters.
• Within a single FederationDomain, you might like to use one identity provider for admin-level users, while using another identity provider for developer-level users, thus allowing you to draw identities for different roles from different user databases.
• Within a single FederationDomain, you might like to allow users from two different organizations to both be able to authenticate into the same clusters by configuring an identity provider for each. This could allow multiple teams to collaborate on the same clusters.
• Within a single FederationDomain, you might like to use the same external identity provider configured different ways to get different types of users. For example, you could configure one OIDCIdentityProvider resource to use a client ID for your human users which requires them to authenticate using multi-factor authentication (configured as a setting on that client ID), while configuring another OIDCIdentityProvider (with a different client ID) to allow CI/CD “bot” users to authenticate with a single factor to ease automation.
• You might like to configure multiple LDAPIdentityProviders to each search for users or groups in a different branch of your LDAP tree. Then you could use each LDAPIdentityProvider in a different FederationDomain, or you could use multiple within the same FederationDomain.

Configuring a FederationDomain to use one or more identity providers is as easy as listing objectRefs in the FederationDomain’s spec for each OIDCIdentityProviders, LDAPIdentityProviders, or ActiveDirectoryIdentityProviders that you wish to use in the FederationDomain.

New: Identity transformations and policies

Now that you can configure a FederationDomain to allow users from multiple identity providers to authenticate, what happens if one person authenticates as username “ryan” from one provider, while another person also authenticates as username “ryan” from a different provider? Well, Kubernetes usernames are just strings, so those two people would be considered the same user by Kubernetes. The same goes for group names. If conflicting usernames and group names are not desirable, how can you configure Pinniped to work around this? The answer is the new identity transformations feature.

Identity transformations are Common Expression Language (CEL) expressions that may be configured on each FederationDomain’s identity provider to potentially change a user’s username or group names. For example, you could configure transformations to prefix every username and group name from each identity provider with a unique string. For example, “ryan” from LDAP could become “ldap:ryan” while “ryan” from Gitlab could become “gitlab:ryan”, thus making it impossible for two usernames fro these providers to conflict. (Note that Pinniped will not automatically avoid these username and group name conflicts. You must explicitly configure identity transformations to add prefixes or otherwise resolve conflicting names.)

Identity transformations are also useful even when you are using a single identity provider. For example, you could use them to:

• Drop groups from a user’s list of groups which are not interesting for your Kubernetes authorization use cases
• Add groups to a user’s list of groups
• Rename existing groups
• Replace undesirable whitespace in usernames or group names
• Change the case of usernames or group names, because Kubernetes usernames and group names are case-sensitive
• Drop groups that start with the prefix system:, which has a special meaning to Kubernetes

Identity policies are Common Expression Language (CEL) expressions that may be configured on each FederationDomain’s identity provider to potentially reject a user’s authentication. Policies can act based on the user’s username or group names.

For example, you could configure policies to reject a user’s authentication:

• If they belong to a certain group or group(s)
• If they don’t belong to a certain group or group(s)
• If they are in a list of disallowed usernames
• If they are not in a list of allowed usernames
• If their username does not have a certain prefix or substring

Where to read more

This blog post is just a quick overview of these new features. To learn about how to configure the Pinniped Supervisor with these new features, see:

• The documentation for creating FederationDomains.
• The documentation for configuring identity providers on FederationDomains.
• The API documentation for the spec.identityProviders setting on the FederationDomain resource.