Project: Pinniped (Provisioning / Key Management)
File: architecture.md

title: Architecture description: Dive into the overall design and implementation details of Pinniped. cascade: layout: docs menu: docs: name: Architecture weight: 100 parent: background The principal purpose of Pinniped is to allow users to access Kubernetes clusters. Pinniped hopes to enable this access across a wide range of Kubernetes environments with zero configuration. Pinniped is composed of two parts. The Pinniped Supervisor is an OIDC server which allows users to authenticate 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. The Pinniped Concierge is a credential exchange API which takes as input a credential from an identity source (e.g., Pinniped Supervisor, proprietary IDP), authenticates the user via that credential, and returns another credential which is understood by the host Kubernetes cluster or by an impersonation proxy which acts on behalf of the user. Pinniped supports various authenticator types and OIDC identity providers and implements different integration strategies for various Kubernetes distributions to make authentication possible. The Pinniped Supervisor will federate identity from one or more IDPs. Administrators will configure the Pinniped Supervisor to use IDPs via Kubernetes custom resources allowing Pinniped to be managed using GitOps and standard Kubernetes tools. Pinniped supports the following IDPs. Any identity provider (e.g., , ). Any identity provider. Any Active Directory identity provider (via LDAP). The API group contains the Kubernetes custom resources that configure the Pinniped Supervisor's upstream IDPs. More IDP integrations are coming soon. The Pinniped Concierge requires one or more authenticators to validate external credentials in order to issue cluster specific credentials. Administrators will configure authenticators via Kubernetes custom resources allowing Pinniped to be managed using GitOps and standard Kubernetes tools. Pinniped supports the following authenticator types. Any webhook which implements the . In addition to allowing the integration of any existing IDP which implements this API, webhooks also serve as an extension point for Pinniped by allowing for integration of arbitrary custom authenticators. While a custom implementation may be in any language or framework, this project provides a sample implementation in Golang. See the `ServeHTTP` method of . A JSON Web Token (JWT) authenticator, which will validate and parse claims from JWTs. This can be used to validate tokens that are issued by the Pinniped Supervisor, any identity provider, or various other identity sources. The JWT authenticator provides the same functionality as the [Kubernetes OIDC authentication mechanism](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens), but it is configurable at cluster runtime instead of requiring flags to be set on the `kube-apiserver` process. The API group contains the Kubernetes custom resources that configure the Pinniped Concierge's authenticators. Pinniped will issue a cluster credential by leveraging cluster-specific

In the longer term, Pinniped hopes to contribute and leverage upstream Kubernetes extension points that cleanly enable this integration. Pinniped supports the following cluster integration strategies. Token Credential Request API: Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server. This API returns a new cluster-specific credential using the cluster's signing keypair to issue short-lived cluster certificates. (In the future, when the Kubernetes CSR API provides a way to issue short-lived certificates, then the Pinniped credential exchange API will use that instead of using the cluster's signing keypair.) Impersonation Proxy: Pinniped hosts an proxy that sends requests to the Kubernetes API server with user information and permissions based on a token. With any of the above IDPs, authentication methods, and cluster integration strategies, `kubectl` commands receive the cluster-specific credential via a . Users may use the Pinniped CLI as the credential plugin, or they may use any proprietary CLI built with the . Pinniped can be configured to authenticate users in a variety of scenarios. Depending on the use case, administrators can deploy the Supervisor, the Concierge, both, or neither. Users can authenticate with the help of the Supervisor, which will issue tokens that can be exchanged at the Concierge for a credential that can be used to authenticate to the host Kubernetes cluster. The Supervisor enables users to log in to their external identity provider once per day and access each cluster in a domain with a distinct scoped-down token. The diagram below shows the components involved in the login flow when both the Concierge and Supervisor are configured. The diagram below demonstrates using `kubectl get pods` with the Pinniped CLI functioning as a that obtains a federation ID token from the Pinniped Supervisor to be sent to a JWT authenticator via the Pinniped Concierge. Users can authenticate directly with their OIDC compliant external identity provider to get credentials which can be exchanged at the Concierge for a credential that can be used to authenticate to the host Kubernetes cluster. The diagram below shows the components involved in the login flow when the Concierge is configured. The diagram below demonstrates using `kubectl get pods` with a that obtains an external credential to be sent to a webhook authenticator via the Pinniped Concierge. Users can authenticate with the help of the Supervisor, which will issue tokens that can be given directly to a Kubernetes API Server that has been configured with The Supervisor enables users to log in to their external identity provider once per day and access each cluster in a domain with a distinct scoped-down token. Users can authenticate directly with their OIDC compliant external identity provider to get credentials that can be given directly to a Kubernetes API Server that has been configured with