diff --git a/README.md b/README.md index 63cf3800..d855a6b6 100644 --- a/README.md +++ b/README.md @@ -28,35 +28,9 @@ credential for a short-lived, cluster-specific credential. Pinniped supports var IDP types and implements different integration strategies for various Kubernetes distributions to make authentication possible. -#### Supported Identity Provider Types +To learn more, see [architecture.md](doc/architecture.md). -The currently supported external IDP types are outlined here. More will be added in the future. - -1. Any webhook which implements the -[Kubernetes TokenReview API](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#webhook-token-authentication) - -#### Supported Cluster Integration Strategies - -The currently supported cluster integration strategies are outlined here. More -will be added in the future. - -1. 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.) - -#### `kubectl` Integration - -With any of the above IDPs and 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](generated). - -#### Cluster Authentication Sequence Diagram - -![implementation](doc/img/pinniped.svg) +Pinniped Architecture Sketch ## Trying Pinniped diff --git a/doc/architecture.md b/doc/architecture.md new file mode 100644 index 00000000..a7b83d9c --- /dev/null +++ b/doc/architecture.md @@ -0,0 +1,71 @@ +# Architecture + +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. + +This integration is implemented using a credential exchange API which takes as +input a credential from the external IDP (or internal federation trust +relationship) and returns a credential which is understood by the host +Kubernetes cluster. To learn more about this integration, see [Cluster +Integration Strategies](#cluster-integration-strategies). + +Pinniped Architecture Sketch + +## External Identity Provider Integrations + +Pinniped will consume identity from one or more external identity providers +(IDPs). Administrators will configure external IDPs via [Kubernetes custom +resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/), +allowing Pinniped to be managed using GitOps and standard Kubernetes tools. + +IDP integration support will be driven by empirical use case. + +IDPs that support only just-in-time flows (such as OIDC) can be optionally +paired with a separate directory backend to enable directory-based flows such as +first-class support for policy editing UX. + +### Supported External Identity Provider Types + +The currently supported external IDP types are outlined here. More will be added +in the future. + +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 + [cmd/local-user-authenticator/main.go](../cmd/local-user-authenticator/main.go). + +## Cluster Integration Strategies + +Pinniped will issue a cluster credential by leveraging cluster-specific +functionality. In the near term, cluster integrations will happen via different +cluster-specific flows depending on the type of cluster. In the longer term, +Pinniped hopes to contribute and leverage upstream Kubernetes extension points that +cleanly enable this integration. + +### Supported Cluster Integration Strategies + +The currently supported cluster integration strategies are outlined here. More +will be added in the future. + +1. 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.) + +## `kubectl` Integration + +With any of the above IDPs and 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](generated). + +## Example Cluster Authentication Sequence Diagram + +![example-cluster-authentication-sequence-diagram](img/pinniped.svg) diff --git a/doc/img/README.md b/doc/img/README.md index 05ffb7d0..6069e9e3 100644 --- a/doc/img/README.md +++ b/doc/img/README.md @@ -1,8 +1,12 @@ -# README +# `doc/img` README -Note! Some of the image files in this directory (e.g., -[pinniped.svg](pinniped.svg)) were generated using -[`plantuml`](https://plantuml.com/). To use `plantuml` to regenerate the image -files, you simply run `plantuml -tsvg ` from this directory. For -example, to regenerate [pinniped.svg](pinniped.svg), run `plantuml -tsvg -pinniped.txt`. +## How to Update these Images + +- [pinniped.svg](pinniped.svg) was generated using [`plantuml`](https://plantuml.com/). + To regenerate the image, run `plantuml -tsvg pinniped.txt` from this directory. + +- [pinniped_architecture.svg](pinniped_architecture.svg) was created on [draw.io](https://draw.io). + It can be opened again for editing on that site by choosing "File" -> "Open from" -> "Device". + Because it includes embedded icons it should be exported using "File" -> "Export as" -> "SVG", + with the "Transparent Background", "Embed Images", and "Include a copy of my diagram" options + checked. The icons in this diagram are from their "CAE" shapes set. diff --git a/doc/img/pinniped_architecture.svg b/doc/img/pinniped_architecture.svg new file mode 100644 index 00000000..ded0bdf4 --- /dev/null +++ b/doc/img/pinniped_architecture.svg @@ -0,0 +1,3 @@ + + +
Identity Provider
Identity Provider
Kubernetes Cluster
Kubernetes Cluster
Client Machine
Client Machine
Pinniped Service
Pinniped Service
Pod
Pod
Pod
Pod
Pinniped's Aggregated API
Pinniped's Ag...
Pinniped's exec plugin
Pinniped's ex...
"kubectl get pods"
"kubectl get pods"
1.) Credential Exchange Request
1.) Credential...
3.) "get pods" Request Including Auth
3.) "get pods"...
Kubernetes API Server
Kubernetes API Server
2.) Confirm User Identity
2.) Confirm Us...Viewer does not support full SVG 1.1 diff --git a/doc/scope.md b/doc/scope.md index eea4ed7c..f3878732 100644 --- a/doc/scope.md +++ b/doc/scope.md @@ -1,7 +1,7 @@ # Project Scope The Pinniped project is guided by the following principles. -* Pinniped lets you plug any upstream identitiy providers into +* Pinniped lets you plug any external identitiy providers into Kubernetes. These integrations follow enterprise-grade security principles. * Pinniped is easy to install and use on any Kubernetes cluster via distribution-specific integration mechanisms.