mirror of
https://github.com/vmware-tanzu/pinniped.git
synced 2026-02-04 03:52:41 +00:00
181 lines
9.3 KiB
Markdown
181 lines
9.3 KiB
Markdown
|
|
---
|
|
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 three parts.
|
|
|
|
1. 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.
|
|
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),
|
|
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.
|
|
1. The Pinniped CLI help generate Pinniped-compatible kubeconfigs for clusters
|
|
and helps end-users authenticate using those kubeconfigs.
|
|
|
|
|
|
|
|
Pinniped supports various authenticator types and OIDC identity providers and implements different integration strategies
|
|
for various Kubernetes distributions to make authentication possible.
|
|
|
|
## External Identity Provider Integrations
|
|
|
|
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 currently supports the following external identity provider types.
|
|
|
|
1. Any [OIDC-compliant](https://openid.net/specs/openid-connect-core-1_0.html)
|
|
identity provider (e.g., [Dex](https://github.com/dexidp/dex),
|
|
[Okta](https://www.okta.com/)).
|
|
|
|
1. Any [LDAP](https://ldap.com) identity provider.
|
|
|
|
1. Any Active Directory identity provider (via LDAP).
|
|
|
|
1. Identities from GitHub or GitHub Enterprise.
|
|
|
|
The
|
|
[`idp.supervisor.pinniped.dev`](https://github.com/vmware/pinniped/blob/main/generated/latest/README.adoc#k8s-api-idp-supervisor-pinniped-dev-v1alpha1)
|
|
API group contains the Kubernetes custom resources that configure the Pinniped
|
|
Supervisor's external IDPs.
|
|
|
|
## Authenticators
|
|
|
|
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.
|
|
|
|
1. Any webhook which implements the
|
|
[Kubernetes TokenReview API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication).
|
|
|
|
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
|
|
[internal/localuserauthenticator/localuserauthenticator.go](https://github.com/vmware/pinniped/blob/main/internal/localuserauthenticator/localuserauthenticator.go).
|
|
|
|
1. 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
|
|
[OIDC-compliant](https://openid.net/specs/openid-connect-core-1_0.html)
|
|
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
|
|
[`authentication.concierge.pinniped.dev`](https://github.com/vmware/pinniped/blob/main/generated/latest/README.adoc#k8s-api-authentication-concierge-pinniped-dev-v1alpha1)
|
|
API group contains the Kubernetes custom resources that configure the Pinniped
|
|
Concierge's authenticators.
|
|
|
|
## Cluster Integration Strategies
|
|
|
|
The Pinniped Concierge will issue a cluster credential by leveraging cluster-specific
|
|
functionality. In the longer term,
|
|
Pinniped hopes to contribute and leverage upstream Kubernetes extension points that
|
|
cleanly enable this integration.
|
|
|
|
The Concierge hosts a credential exchange API endpoint via a Kubernetes aggregated API server.
|
|
This API returns a short-lived mTLS client certificate which can then be used to invoke the Kubernetes API.
|
|
The method used to sign the short-lived cluster certificates depends on the cluster integration strategy selected
|
|
for that cluster.
|
|
|
|
The Concierge supports the following cluster integration strategies.
|
|
|
|
* Kube Cluster Signing Certificate: Pinniped signs the short-lived client certificates using the
|
|
Kubernetes API server's signing key. These can be used to make Kubernetes API requests directly
|
|
to the Kubernetes API server.
|
|
* Impersonation Proxy: Pinniped signs the short-lived client certificates using its own signing key.
|
|
Pinniped hosts an
|
|
[impersonation](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#user-impersonation)
|
|
proxy that relays requests to the Kubernetes API server with the end user's identity and group memberships.
|
|
When Kubernetes API requests are made through the impersonation proxy, Pinniped validates that the client's
|
|
certificate was signed by its own key before submitting the API request to the Kubernetes API server on
|
|
behalf of the user via impersonation as that user.
|
|
|
|
## kubectl Integration
|
|
|
|
With any of the above IDPs, authentication methods, and cluster integration strategies, `kubectl` commands receive the
|
|
cluster-specific credential via a
|
|
[Kubernetes client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins).
|
|
Users may use the Pinniped CLI as the credential plugin, or they may use any proprietary CLI
|
|
built with the [Pinniped Go client library](https://github.com/vmware/pinniped/tree/main/generated).
|
|
|
|
|
|
## Pinniped Deployment Strategies
|
|
|
|
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.
|
|
|
|
### Full Integration -- Concierge, Supervisor, and CLI
|
|
|
|
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 [Kubernetes client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins)
|
|
that obtains a federation ID token from the Pinniped Supervisor to be sent to a
|
|
JWT authenticator via the Pinniped Concierge.
|
|
|
|
|
|
|
|
### Dynamic Cluster Authentication -- Concierge and CLI
|
|
|
|
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 [Kubernetes client-go credential plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins)
|
|
that obtains an external credential to be sent to a webhook authenticator via the Pinniped Concierge.
|
|
|
|
|
|
|
|
### Static Cluster Integration -- Supervisor and CLI
|
|
|
|
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
|
|
[OIDC Authentication.](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens)
|
|
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.
|
|
|
|
### Minimal -- CLI only
|
|
|
|
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
|
|
[OIDC Authentication.](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens)
|