SPIFFE/SPIRE Integration

Relevant source files

The following files were used as context for generating this wiki page:

• ground-control/internal/spiffe/authorizer.go
• ground-control/internal/spiffe/middleware.go
• ground-control/internal/spiffe/embedded_server.go
• internal/spiffe/client.go
• deploy/quickstart/spiffe/README.md
• deploy/quickstart/README.md
• internal/state/reporting_process.go

Harbor Satellite utilizes the SPIFFE (Secure Production Identity Framework for Everyone) framework and SPIRE (SPIFFE Runtime Environment) to establish zero-trust identity between Ground Control and Satellite instances. This integration provides cryptographic identity verification, mutual TLS (mTLS) for all communications, and automated certificate rotation, replacing the need for long-lived shared secrets in production environments.

The architecture relies on a central SPIRE Server acting as the trust root, with SPIRE Agents deployed alongside both Ground Control (GC) and Satellite components. These agents perform workload attestation to issue X.509 SVIDs (SPIFFE Verifiable Identity Documents), which are then used by the applications to perform authenticated mTLS handshakes.

Sources: deploy/quickstart/spiffe/README.md, deploy/quickstart/README.md

Architecture and Components

The integration consists of several layers: the identity issuance infrastructure (SPIRE Server/Agent), the identity consumption logic (SPIFFE Client), and the enforcement layer (Auth Middleware).

High-Level Identity Flow

The following diagram illustrates the relationship between SPIRE infrastructure and the Harbor Satellite components:

Identity is established locally between agents and workloads, while mTLS is enforced for cross-component traffic.
Sources: deploy/quickstart/README.md, deploy/quickstart/spiffe/README.md

Component Descriptions

Component	Description
SPIRE Server	The central authority that manages the trust domain, issues SVIDs, and maintains registration entries.
SPIRE Agent	Runs on every node; performs node attestation and provides a Workload API for applications to fetch identities.
SPIFFE Client	A Go-based client within the Satellite and GC that communicates with the SPIRE Agent's socket to retrieve SVIDs.
Embedded SPIRE	A planned/experimental mode where Ground Control manages its own SPIRE server subprocess.

Sources: deploy/quickstart/README.md, ground-control/internal/spiffe/embedded_server.go:19-25

Attestation Methods

The system supports multiple attestation methods to accommodate different deployment environments:

1. Join Token: A simple, single-use token generated by the SPIRE server. Primarily used for development, testing, and CI/CD.
2. X.509 PoP (Proof of Possession): Uses pre-provisioned X.509 certificates from an existing PKI to authenticate agents.
3. SSH PoP: Utilizes SSH host certificates signed by a trusted SSH CA for agent attestation.

Sources: deploy/quickstart/spiffe/README.md, deploy/quickstart/README.md

SPIFFE ID Structure and Extraction

The integration uses structured SPIFFE IDs to encode metadata about the satellite's identity, including its name and region.

ID Format Patterns

• Default: spiffe://<trust-domain>/satellite
• Named: spiffe://<trust-domain>/satellite/<name>
• Regional: spiffe://<trust-domain>/satellite/region/<region>/<name>

Sources: ground-control/internal/spiffe/authorizer.go:167-175

Extraction Logic

The SatelliteAuthorizer and middleware packages contain logic to parse these IDs from incoming TLS connections.

Implementation Details

Workload API Integration

The internal/spiffe package provides a Client that wraps the SPIFFE Workload API. It is responsible for establishing a connection to the SPIRE Agent socket and providing a tls.Config for mTLS.

• Connect(ctx): Establishes the connection to the SPIRE Agent socket (default: unix:///run/spire/sockets/agent.sock).
• GetTLSConfig(): Returns a *tls.Config that automatically uses the current SVID and authorizes peers based on the trust domain.
• CreateHTTPClient(): Returns an *http.Client pre-configured for SPIFFE mTLS.

Sources: internal/spiffe/client.go:30-41, internal/spiffe/client.go:102-120, internal/spiffe/client.go:123-138

Server-Side Authorization

Ground Control implements specific authorizers to validate incoming satellite connections:

• SatelliteAuthorizer: Ensures the SPIFFE ID path starts with /satellite/ or matches /satellite.
• RegionAuthorizer: Restricts access based on the region encoded in the SPIFFE ID path.
• PatternAuthorizer: Uses regex to validate the SPIFFE ID path component.

Sources: ground-control/internal/spiffe/authorizer.go:15-32, ground-control/internal/spiffe/authorizer.go:58-75

Status Reporting with SPIFFE

The StatusReportingProcess in the satellite uses the SPIFFE client to send heartbeats to Ground Control. It dynamically switches between a standard HTTP client and a SPIFFE-enabled client based on the configuration.

if s.spiffeClient != nil {
    if err := s.spiffeClient.Connect(ctx); err != nil {
        return fmt.Errorf("connect to SPIRE agent: %w", err)
    }
    client, err = s.spiffeClient.CreateHTTPClient()
    if err != nil {
        return fmt.Errorf("create SPIFFE HTTP client: %w", err)
    }
}

Sources: internal/state/reporting_process.go:104-113

Configuration

Environment Variable / Config Field	Description	Default Value
SPIFFE_ENABLED	Enables SPIFFE identity for the component.	false
SPIFFE_ENDPOINT_SOCKET	Path to the SPIRE Agent Workload API socket.	unix:///run/spire/sockets/agent.sock
SPIFFE_TRUST_DOMAIN	The SPIFFE trust domain (e.g., harbor-satellite.local).	N/A
expected_server_id	(Satellite only) The specific SPIFFE ID expected from Ground Control.	"" (Authorize Any)

Sources: internal/spiffe/client.go:44-48, ground-control/internal/spiffe/middleware.go:88-92

Summary

The SPIFFE/SPIRE integration provides a robust security layer for Harbor Satellite by automating identity management. By leveraging workload attestation and mTLS, the system ensures that only verified Satellites can communicate with Ground Control, and all data in transit is encrypted with automatically rotated certificates.