README

Pinniped Logo

Overview

Pinniped provides identity services to Kubernetes.

Pinniped allows cluster administrators to easily plug in external identity 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 with IDPs, and distribution-specific integration strategies.

Example Use Cases

  • 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

Architecture

The Pinniped Supervisor component offers identity federation to enable a user to access multiple clusters with a single daily login to their external IDP. The Pinniped Supervisor supports various external IDP types.

The Pinniped Concierge component offers credential exchange to enable a user to exchange an external credential for a short-lived, cluster-specific credential. Pinniped supports various authentication methods and implements different integration strategies for various Kubernetes distributions to make authentication possible.

The Pinniped Concierge can be configured to hook into the Pinniped Supervisor's federated credentials, or it can authenticate users directly via external IDP credentials.

To learn more, see architecture.

Pinniped Architecture Sketch

Trying Pinniped

Care to kick the tires? It's easy to install and try Pinniped.

Community Meetings

Pinniped is better because of our contributors and maintainers. It is because of you that we can bring great software to the community. Please join us during our online community meetings, occuring every first and third Thursday of the month at 9AM PT / 12PM PT. Use this Zoom Link to attend and add any agenda items you wish to discuss to the notes document. Join our Google Group to receive invites to this meeting.

If the meeting day falls on a US holiday, please consider that occurrence of the meeting to be canceled.

Discussion

Got a question, comment, or idea? Please don't hesitate to reach out via the GitHub Discussions tab at the top of this page or reach out in Kubernetes Slack Workspace within the #pinniped channel.

Contributions

Contributions are welcome. Before contributing, please see the contributing guide.

Reporting Security Vulnerabilities

Please follow the procedure described in SECURITY.md.

License

Pinniped is open source and licensed under Apache License Version 2.0. See LICENSE.

Copyright 2020 the Pinniped contributors. All Rights Reserved.

Expand ▾ Collapse ▴

Directories

Path Synopsis
cmd
local-user-authenticator
Package main provides a authentication webhook program.
Package main provides a authentication webhook program.
generated
1.17/apis Module
1.17/client Module
1.18/apis Module
1.18/client Module
1.19/apis Module
1.19/client Module
1.20/apis Module
1.20/client Module
pkg
conciergeclient
Package conciergeclient provides login helpers for the Pinniped concierge.
Package conciergeclient provides login helpers for the Pinniped concierge.
oidcclient
Package oidcclient implements a CLI OIDC login flow.
Package oidcclient implements a CLI OIDC login flow.
oidcclient/filesession
Package cachefile implements the file format for session caches.
Package cachefile implements the file format for session caches.
oidcclient/nonce
Package nonce implements
Package nonce implements
oidcclient/oidctypes
Package oidctypes provides core data types for OIDC token structures.
Package oidctypes provides core data types for OIDC token structures.
test
library/browsertest
Package browsertest provides integration test helpers for our browser-based tests.
Package browsertest provides integration test helpers for our browser-based tests.
internal
certauthority
Package certauthority implements a simple x509 certificate authority suitable for use in an aggregated API service.
Package certauthority implements a simple x509 certificate authority suitable for use in an aggregated API service.
certauthority/dynamiccertauthority
Package dynamiccertauthority implements a x509 certificate authority capable of issuing certificates from a dynamically updating CA keypair.
Package dynamiccertauthority implements a x509 certificate authority capable of issuing certificates from a dynamically updating CA keypair.
concierge/server
Package server is the command line entry point for pinniped-concierge.
Package server is the command line entry point for pinniped-concierge.
config/concierge
Package concierge contains functionality to load/store Config's from/to some source.
Package concierge contains functionality to load/store Config's from/to some source.
config/supervisor
Package supervisor contains functionality to load/store Config's from/to some source.
Package supervisor contains functionality to load/store Config's from/to some source.
controller/apicerts
Package apicerts contains controllers that work together to provide rotating API certs.
Package apicerts contains controllers that work together to provide rotating API certs.
controller/authenticator
Package authenticator contains helper code for dealing with *Authenticator CRDs.
Package authenticator contains helper code for dealing with *Authenticator CRDs.
controller/authenticator/authncache
Package authncache implements a cache of active authenticators.
Package authncache implements a cache of active authenticators.
controller/authenticator/cachecleaner
Package cachecleaner implements a controller for garbage collecting authenticators from an authenticator cache.
Package cachecleaner implements a controller for garbage collecting authenticators from an authenticator cache.
controller/authenticator/jwtcachefiller
Package jwtcachefiller implements a controller for filling an authncache.Cache with each added/updated JWTAuthenticator.
Package jwtcachefiller implements a controller for filling an authncache.Cache with each added/updated JWTAuthenticator.
controller/authenticator/webhookcachefiller
Package webhookcachefiller implements a controller for filling an authncache.Cache with each added/updated WebhookAuthenticator.
Package webhookcachefiller implements a controller for filling an authncache.Cache with each added/updated WebhookAuthenticator.
controller/issuerconfig
Package issuerconfig contains controller(s) for reconciling CredentialIssuer's.
Package issuerconfig contains controller(s) for reconciling CredentialIssuer's.
controller/kubecertagent
Package kubecertagent provides controllers that ensure a set of pods (the kube-cert-agent), is colocated with the Kubernetes controller manager so that Pinniped can access its signing keys.
Package kubecertagent provides controllers that ensure a set of pods (the kube-cert-agent), is colocated with the Kubernetes controller manager so that Pinniped can access its signing keys.
controller/supervisorconfig/generator
Package secretgenerator provides a supervisorSecretsController that can ensure existence of a generated secret.
Package secretgenerator provides a supervisorSecretsController that can ensure existence of a generated secret.
controller/supervisorconfig/upstreamwatcher
Package upstreamwatcher implements a controller that watches OIDCIdentityProvider objects.
Package upstreamwatcher implements a controller that watches OIDCIdentityProvider objects.
controllermanager
Package controllermanager provides an entrypoint into running all of the controllers that run as a part of Pinniped.
Package controllermanager provides an entrypoint into running all of the controllers that run as a part of Pinniped.
downward
Package downward implements a client interface for interacting with Kubernetes "downwardAPI" volumes.
Package downward implements a client interface for interacting with Kubernetes "downwardAPI" volumes.
dynamiccert
Package dynamiccert provides a simple way of communicating a dynamically updating PEM-encoded certificate and key.
Package dynamiccert provides a simple way of communicating a dynamically updating PEM-encoded certificate and key.
httputil/httperr
Package httperr contains some helpers for nicer error handling in http.Handler implementations.
Package httperr contains some helpers for nicer error handling in http.Handler implementations.
httputil/securityheader
Package securityheader implements an HTTP middleware for setting security-related response headers.
Package securityheader implements an HTTP middleware for setting security-related response headers.
mocks/credentialrequestmocks
Package credentialrequestmocks is a generated GoMock package.
Package credentialrequestmocks is a generated GoMock package.
mocks/mockkeyset
Package mockkeyset is a generated GoMock package.
Package mockkeyset is a generated GoMock package.
mocks/mocksecrethelper
Package mocksecrethelper is a generated GoMock package.
Package mocksecrethelper is a generated GoMock package.
mocks/mocktokenauthenticator
Package mocktokenauthenticator is a generated GoMock package.
Package mocktokenauthenticator is a generated GoMock package.
mocks/mocktokenauthenticatorcloser
Package mocktokenauthenticatorcloser is a generated GoMock package.
Package mocktokenauthenticatorcloser is a generated GoMock package.
mocks/mockupstreamoidcidentityprovider
Package mockupstreamoidcidentityprovider is a generated GoMock package.
Package mockupstreamoidcidentityprovider is a generated GoMock package.
oidc
Package oidc contains common OIDC functionality needed by Pinniped.
Package oidc contains common OIDC functionality needed by Pinniped.
oidc/auth
Package auth provides a handler for the OIDC authorization endpoint.
Package auth provides a handler for the OIDC authorization endpoint.
oidc/callback
Package callback provides a handler for the OIDC callback endpoint.
Package callback provides a handler for the OIDC callback endpoint.
oidc/discovery
Package discovery provides a handler for the OIDC discovery endpoint.
Package discovery provides a handler for the OIDC discovery endpoint.
oidc/dynamiccodec
Package dynamiccodec provides a type that can encode information using a just-in-time signing and (optionally) encryption secret.
Package dynamiccodec provides a type that can encode information using a just-in-time signing and (optionally) encryption secret.
oidc/jwks
Package discovery provides a handler for the OIDC discovery endpoint.
Package discovery provides a handler for the OIDC discovery endpoint.
oidc/token
Package token provides a handler for the OIDC token endpoint.
Package token provides a handler for the OIDC token endpoint.
plog
Package plog implements a thin layer over klog to help enforce pinniped's logging convention.
Package plog implements a thin layer over klog to help enforce pinniped's logging convention.
registry/credentialrequest
Package credentialrequest provides REST functionality for the CredentialRequest resource.
Package credentialrequest provides REST functionality for the CredentialRequest resource.
testutil
Package testutil contains shared test utilities for the Pinniped project.
Package testutil contains shared test utilities for the Pinniped project.
testutil/fakekubeapi
Package fakekubeapi contains a *very* simple httptest.Server that can be used to stand in for a real Kube API server in tests.
Package fakekubeapi contains a *very* simple httptest.Server that can be used to stand in for a real Kube API server in tests.
testutil/testlogger
Package testlogger implements a logr.Logger suitable for writing test assertions.
Package testlogger implements a logr.Logger suitable for writing test assertions.
upstreamoidc
Package upstreamoidc implements an abstraction of upstream OIDC provider interactions.
Package upstreamoidc implements an abstraction of upstream OIDC provider interactions.