How vmware/pinniped works
1. What this repository is
Pinniped is a Kubernetes identity platform. It adds two main server-side components—Supervisor and Concierge—plus a CLI. The architecture centers on brokering identity from external identity providers into Kubernetes authentication flows.
2. Top-level system split
The repo is organized around two distinct runtime planes:
- Supervisor: handles user-facing login and federation to upstream identity providers.
- Concierge: runs inside or near target clusters and turns validated identity into Kubernetes credentials or impersonation-friendly auth.
This split is the main boundary to show in an architecture diagram.
3. Supervisor subsystem
The Supervisor is the OIDC federation layer. It manages CRDs for configuration such as:
- FederationDomain
- OIDCClient
- upstream IdPs: OIDCIdentityProvider, LDAPIdentityProvider, ActiveDirectoryIdentityProvider, GitHubIdentityProvider
It exposes browser-oriented endpoints for discovery, login, callback, JWKS, token exchange, and IDP selection under internal/federationdomain/endpoints.
4. Supervisor data flow
A login flow typically goes:
- user/browser hits Supervisor discovery/login endpoints
- Supervisor chooses or discovers an upstream IdP
- user authenticates with the upstream provider
- Supervisor stores/derives session state, issues OIDC responses, and serves JWKS for signing keys
- downstream clients use the resulting OIDC artifacts
The Supervisor relies on Fosite-style OAuth/OIDC state and token storage under internal/fositestorage and internal/federationdomain/storage.
5. Concierge subsystem
The Concierge is the cluster-side authentication service. It exposes Kubernetes-style APIs and custom resources for:
- JWTAuthenticator
- WebhookAuthenticator
- CredentialIssuer
- identity/login requests such as TokenCredentialRequest and WhoAmIRequest
Its role is to authenticate users against cluster-configured mechanisms and produce credentials or identity responses usable by kubectl and cluster clients.
6. Concierge data flow
Concierge receives auth-related requests through its aggregated API surface, then:
- resolves configured authenticators from CRDs
- validates tokens or calls webhooks
- may issue cluster credentials or respond with identity info
- can support impersonation-oriented access flows
It also includes certificate and API-service management controllers so the aggregated API remains reachable and trusted.
7. Controller layer
Most operational behavior is implemented as controllers under internal/controller/*, all built on a reusable controller framework in internal/controllerlib.
Major controller groups include:
- Supervisor config controllers: watch IdP and FederationDomain resources, build secrets, JWKS, TLS material, and resolved provider state
- Authenticator controllers: cache and reconcile JWT/webhook authenticators
- API cert controllers: manage serving certs and APIService registration
- Kube cert agent controllers: support credential/cert distribution for the concierge kube-cert-agent
- Storage cleanup controllers: garbage collect or clean up old storage artifacts
8. Generated Kubernetes API surface
The generated/<k8s-version>/... directories contain versioned, generated clients, informers, listers, deepcopy/conversion code, and CRD YAMLs for each supported Kubernetes minor version. This is a clear boundary between:
- handwritten business logic in internal/
- generated API machinery used to compile against multiple Kubernetes versions
The generated artifacts materially affect how the project stays compatible across clusters.
9. CLI subsystem
The cmd/pinniped tree builds the main user CLI. It provides login and discovery-oriented commands such as:
- login
- OIDC login flows
- whoami
- Kubernetes credential/kubeconfig helpers
It uses pkg/oidcclient for browser-based OIDC login, PKCE/state/nonce handling, and pkg/conciergeclient to talk to the Concierge APIs.
10. Supporting internal libraries
Several shared packages underpin both servers and CLI:
- internal/crypto/ptls and internal/certauthority for TLS and certificate handling
- internal/kubeclient and internal/kubeclient/* for Kubernetes API access
- internal/httputil, internal/net/phttp, internal/plog for HTTP behavior and logging
- internal/dynamiccert, internal/dynamiccertauthority, internal/secret, internal/ownerref for runtime-managed Kubernetes secrets and certs
These are infrastructure-heavy cross-cutting concerns, not separate products.
11. External dependencies and integration points
The system depends on:
- the Kubernetes API server and aggregated APIs/CRDs
- upstream identity providers via OIDC, LDAP, Active Directory, and GitHub
- browser-based redirects and callbacks for login
- Kubernetes RBAC, service accounts, and cert secret management
These external boundaries are central to the architecture; most flows bridge Kubernetes control-plane APIs with identity-provider protocols.
12. Deployment model
The deploy/ manifests show the runtime packaging for:
- Supervisor
- Concierge
- local-user-authenticator
The repo also includes Docker build assets and Carvel package templates, indicating that install/upgrade is treated as part of the system architecture, not just build tooling.
13. Testing and validation structure
The architecture is heavily validated through integration tests in test/integration and reusable test helpers in test/testlib and internal/testutil. This reflects the product’s reliance on end-to-end behavior across Kubernetes, TLS, CRDs, and OIDC redirects, rather than isolated unit-only logic.
14. How to diagram it
A good diagram should show:
- users/kubectl/CLI on one side
- Supervisor as the federation/OIDC broker
- Concierge as the cluster auth/credential service
- Kubernetes API server and CRDs as the control-plane store and API surface
- external IdPs as upstream auth providers
- controller loops watching CRDs/secrets and reconciling certs, JWKS, auth configs, and cached state
The key architectural idea is that Pinniped translates external identity into Kubernetes authentication via a split Supervisor/Concierge control plane.
Main entry points: concierge/server Concierge · supervisor/server Supervisor · endpoints OIDC endpoints · latest Versioned APIs
Components 21
Clients
Human and machine entrypoints into Pinniped.
- CLI · Main pinniped command-line client for login, whoami, and kubeconfig flows.
cmd/pinniped - Browser · Browser-based redirect and callback participant in OIDC login flows.
- kubectl · Downstream Kubernetes client that consumes credentials produced by Pinniped.
Supervisor
Federation and upstream identity brokering plane.
- Supervisor · User-facing federation plane that fronts external identity providers and serves OIDC endpoints.
internal/supervisor/server - OIDC endpoints · Discovery, login, callback, token, JWKS, choose-IDP, and token exchange handlers.
internal/federationdomain/endpoints - Config reconcilers · Watches FederationDomain, OIDCClient, and upstream IdP resources to derive secrets, JWKS, TLS, and resolved provider state.
internal/controller/supervisorconfig - Fosite storage · OAuth/OIDC state, code, token, and session storage used by the Supervisor.
internal/federationdomain/storage - OIDC strategy · OIDC signing, HMAC, ECDSA, CSRF, state, and downstream session mechanics.
internal/federationdomain - Upstream IdPs · OIDC, LDAP, Active Directory, and GitHub identity providers configured for federation.
apis/supervisor/idp/v1alpha1
Concierge
Cluster-side authentication and credential issuance plane.
- Concierge · Cluster-side authentication service that exposes Kubernetes-style APIs and credential issuance.
internal/concierge/server - Auth APIs · JWTAuthenticator, WebhookAuthenticator, CredentialIssuer, TokenCredentialRequest, and WhoAmIRequest surfaces.
apis/concierge - Authenticator cache · Reconciles JWT and webhook authenticators and maintains authn cache state.
internal/controller/authenticator - API certs · Manages serving certificates and APIService registration for the aggregated API.
internal/controller/apicerts - Kube cert agent · Supports certificate distribution and pod-based certificate agent behavior.
internal/controller/kubecertagent
Shared libs
Cross-cutting TLS, Kubernetes, HTTP, and identity helpers.
- TLS & certs · Certificate authorities, dynamic certs, and TLS profile handling.
internal/certauthority - Kube client · Kubernetes API access, schemes, and request middleware.
internal/kubeclient - HTTP utils · HTTP behavior, logging, security headers, and request/response helpers.
internal/httputil - Identity libs · OIDC client, upstream provider, token, and identity transformation helpers.
pkg/oidcclient
Generated APIs
Versioned Kubernetes API machinery and CRDs.
- Versioned APIs · Generated clients, informers, listers, deepcopy, conversion, openapi, and CRDs for supported Kubernetes versions.
generated/latest
Packaging
Deployment manifests and release packaging.
- Deployments · Manifests and Carvel package templates for Supervisor, Concierge, and local-user-authenticator.
deploy - Integration tests · End-to-end tests that exercise Kubernetes, CRDs, TLS, OIDC redirects, and auth flows.
test/integration
Connections 31
- CLI → Supervisor: login/discovery · CLI initiates login and discovery flows against the Supervisor.
- CLI → Concierge: whoami/credentials · CLI exchanges credentials and identity requests with the Concierge.
- Browser → OIDC endpoints: redirects · Browser follows OIDC login, callback, and form-post endpoints.
- kubectl → Concierge: auth requests · Kubernetes clients consume credential issuance and identity endpoints.
- Supervisor → OIDC endpoints: serves · Supervisor runtime mounts the browser-facing OIDC handlers.
- Supervisor → Config reconcilers: reconciles · Supervisor depends on config controllers to build resolved federation state.
- Supervisor → Fosite storage: persists state · OIDC state and session data are stored through Fosite-backed storage.
- Supervisor → OIDC strategy: signs tokens · OIDC strategy and session logic underpin discovery, login, JWKS, and token issuance.
- Config reconcilers → Upstream IdPs: watches · Reconcilers watch IdP and FederationDomain CRDs to derive provider state.
- Config reconcilers → TLS & certs: tls material · Supervisor config reconciliation produces or consumes serving certs and CA material.
- Config reconcilers → Versioned APIs: CRDs/clients · Controller logic uses generated APIs, informers, and versioned CRDs.
- OIDC endpoints → Upstream IdPs: federates · Login and IDP-selection handlers route users to upstream identity providers.
- OIDC endpoints → HTTP utils: http behavior · Handlers use shared HTTP utilities, security headers, and logging.
- OIDC endpoints → Identity libs: oidc state · Endpoints rely on OIDC client helpers for PKCE, state, and nonce handling.
- Concierge → Auth APIs: exposes · Concierge serves aggregated authentication, login, and identity APIs.
- Concierge → Authenticator cache: uses · Cluster auth behavior is driven by authenticator reconciliation and cache filling.
- Concierge → API certs: serving trust · API cert controllers keep the aggregated API reachable and trusted.
- Concierge → Kube cert agent: cert agent · Concierge can coordinate kube-cert-agent behavior for credential distribution.
- Authenticator cache → Versioned APIs: watches CRDs · Authenticator controllers consume versioned Kubernetes auth resources.
- API certs → TLS & certs: certs · Serving certificate and CA handling is shared with TLS infrastructure.
- API certs → Kube client: apiservice · APIService registration and Kubernetes client access are managed through kube APIs.
- Kube cert agent → Kube client: kube access · Kube-cert-agent controllers interact with the Kubernetes API and pods.
- TLS & certs → Versioned APIs: cert CRDs · Deployment and reconciliation rely on generated Kubernetes API types and CRDs.
- Kube client → Versioned APIs: clients · Shared kubeclient code is built on generated clientsets and schemes.
- Identity libs → Upstream IdPs: upstream auth · Shared identity helpers implement OIDC, LDAP, AD, and GitHub provider integrations.
- HTTP utils → CLI: browser login · CLI uses shared HTTP primitives indirectly through browser-based OIDC flows.
- Deployments → Supervisor: packages · Deployment manifests package the Supervisor runtime.
- Deployments → Concierge: packages · Deployment manifests package the Concierge runtime.
- Deployments → Versioned APIs: installs CRDs · Manifests include generated CRDs and overlays for supported versions.
- Integration tests → Supervisor: validates · Integration tests exercise login, discovery, upstream federation, and storage flows.
- Integration tests → Concierge: validates · Integration tests cover credential issuance, authn/authz, API serving certs, and whoami flows.