2020-08-20 17:54:15 +00:00
|
|
|
# Pinniped
|
2020-08-09 17:04:05 +00:00
|
|
|
|
2020-08-26 14:06:21 +00:00
|
|
|
## Overview
|
|
|
|
|
|
|
|
Pinniped provides identity services to Kubernetes.
|
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
Pinniped allows cluster administrators to easily plug in external identity
|
2020-08-26 14:06:21 +00:00
|
|
|
providers (IDPs) into Kubernetes clusters. This is achieved via a uniform
|
|
|
|
install procedure across all types and origins of Kubernetes clusters,
|
|
|
|
declarative configuration via Kubernetes APIs, enterprise-grade integrations
|
2020-08-27 17:14:03 +00:00
|
|
|
with IDPs, and distribution-specific integration strategies.
|
2020-08-26 14:06:21 +00:00
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
### Example Use Cases
|
2020-08-26 14:06:21 +00:00
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
* Your team uses a large enterprise IDP, and has many clusters that they
|
|
|
|
manage. Pinniped provides:
|
|
|
|
* Seamless and robust integration with the IDP
|
|
|
|
* Easy installation across clusters of any type and origin
|
|
|
|
* A simplified login flow across all clusters
|
|
|
|
* Your team shares a single cluster. Pinniped provides:
|
|
|
|
* Simple configuration to integrate an IDP
|
|
|
|
* Individual, revocable identities
|
2020-08-26 14:06:21 +00:00
|
|
|
|
|
|
|
### Architecture
|
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
Pinniped offers credential exchange to enable a user to exchange an external IDP
|
|
|
|
credential for a short-lived, cluster-specific credential. Pinniped supports various
|
|
|
|
IDP types and implements different integration strategies for various Kubernetes
|
|
|
|
distributions to make authentication possible.
|
|
|
|
|
2020-08-27 22:11:38 +00:00
|
|
|
#### Supported Identity Provider Types
|
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
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)
|
|
|
|
|
2020-08-27 22:11:38 +00:00
|
|
|
#### Supported Cluster Integration Strategies
|
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
The currently supported cluster integration strategies are outlined here. More
|
|
|
|
will be added in the future.
|
|
|
|
|
2020-08-27 22:11:38 +00:00
|
|
|
1. Pinniped hosts a credential exchange API endpoint via a Kubernetes aggregated API server.
|
2020-08-27 17:14:03 +00:00
|
|
|
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
|
2020-08-27 22:11:38 +00:00
|
|
|
provides a way to issue short-lived certificates, then the Pinniped credential exchange API
|
2020-08-27 17:14:03 +00:00
|
|
|
will use that instead of using the cluster's signing keypair.)
|
|
|
|
|
2020-08-27 22:11:38 +00:00
|
|
|
#### `kubectl` Integration
|
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
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
|
2020-08-27 21:43:16 +00:00
|
|
|
built with the [Pinniped Go client library](generated).
|
2020-08-27 17:14:03 +00:00
|
|
|
|
|
|
|
#### Cluster Authentication Sequence Diagram
|
2020-08-26 14:06:21 +00:00
|
|
|
|
|
|
|
![implementation](doc/img/pinniped.svg)
|
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
## Installation
|
|
|
|
|
2020-08-27 21:43:16 +00:00
|
|
|
Currently, Pinniped supports self-hosted clusters where the Kube Controller Manager pod
|
|
|
|
is accessible from Pinniped's pods.
|
|
|
|
Support for other types of Kubernetes distributions is coming soon.
|
2020-08-26 14:06:21 +00:00
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
To try Pinniped, see [deploy/README.md](deploy/README.md).
|
2020-08-26 14:06:21 +00:00
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
## Contributions
|
2020-08-26 14:06:21 +00:00
|
|
|
|
2020-08-27 17:14:03 +00:00
|
|
|
Contributions are welcome. Before contributing, please see
|
2020-08-28 16:28:27 +00:00
|
|
|
the [Code of Conduct](doc/code_of_conduct.md) and
|
2020-08-27 17:14:03 +00:00
|
|
|
[the contributing guide](doc/contributing.md).
|
2020-08-20 17:54:15 +00:00
|
|
|
|
2020-08-27 22:02:11 +00:00
|
|
|
## Reporting Security Vulnerabilities
|
|
|
|
|
|
|
|
Please follow the procedure described in [SECURITY.md](SECURITY.md).
|
|
|
|
|
2020-08-27 12:39:20 +00:00
|
|
|
## License
|
2020-08-20 17:54:15 +00:00
|
|
|
|
2020-08-27 12:39:20 +00:00
|
|
|
Pinniped is open source and licensed under Apache License Version 2.0. See [LICENSE](LICENSE) file.
|
2020-08-20 17:54:15 +00:00
|
|
|
|
|
|
|
Copyright 2020 VMware, Inc.
|