Middleware & API Security
Relevant source files
The following files were used as context for generating this wiki page:
Middleware and API security in Harbor Satellite provide a robust defense-in-depth strategy for both Ground Control and Satellite components. The system supports multiple authentication tiers, ranging from standard HTTP Basic Auth and Bearer tokens to advanced zero-trust identities using SPIFFE/SPIRE. These layers ensure that only authorized administrative users can manage configurations while verified satellites can securely replicate artifacts.
The security architecture is designed to handle different deployment environments, including development (token-based ZTR) and production (mTLS with automatic certificate rotation). By leveraging middleware, the project decouples security logic from business logic, allowing for consistent enforcement of identity extraction, role-based access control (RBAC), and cryptographic verification across the fleet.
Authentication Mechanisms
The system employs three primary methods for authenticating requests, depending on the client type and deployment configuration.
Administrative User Authentication
Ground Control uses an AuthMiddleware to validate requests from administrators. It supports a fallback mechanism where it first attempts to validate a Bearer token against an active session in the database and, if unsuccessful, attempts to validate Basic Authentication credentials.
The diagram shows the logic flow for administrative authentication, prioritizing session tokens over basic credentials.
Sources: ground-control/internal/server/middleware.go:17-56
SPIFFE/SPIRE Zero-Trust Identity
For production environments, Harbor Satellite implements SPIFFE (Secure Production Identity Framework for Everyone). This mechanism uses mTLS with X.509 SVIDs (SPIFFE Verifiable Identity Documents). The AuthMiddleware in the SPIFFE package extracts the SPIFFE ID from the TLS connection and populates the request context with the satellite's identity, name, and region.
| Context Key | Type | Description |
|---|---|---|
spiffe_id | spiffeid.ID | The full SPIFFE identity of the caller |
satellite_name | string | Extracted name of the specific satellite |
region | string | Extracted geographic region of the satellite |
Sources: ground-control/internal/spiffe/middleware.go:21-33, deploy/quickstart/README.md:12-18
Token-based Satellite Authentication
In non-SPIFFE deployments, satellites authenticate using a one-time token. A dedicated TokenAuthMiddleware handles this by validating the Authorization header against a validator function. If valid, the satellite is assigned a generated name (e.g., satellite-1) within the request context.
Sources: ground-control/internal/spiffe/middleware.go:101-137
Authorization and RBAC
Authorization is enforced through role-based checks. The RequireRole middleware ensures that an authenticated user possesses the specific privileges required for an endpoint.
This sequence illustrates the verification of user roles before allowing access to protected API handlers.
Sources: ground-control/internal/server/middleware.go:68-83
Transport Security and Certificate Management
TLS Configuration
API security is further hardened through TLS. The system supports standard TLS and SPIFFE-controlled mTLS. Configuration validation ensures that certificates and keys exist and are provided in pairs.
- SkipVerify: An optional flag for development that bypasses certificate verification.
- CA Verification: Supports custom CA files for private PKI environments.
Sources: pkg/config/validate.go:182-218
Dynamic Certificate Reloading
To support high availability and certificate rotation, the CertWatcher component monitors certificate files on disk. It uses a background ticker to check modification times and reloads the tls.Certificate in-memory without requiring a process restart.
The CertWatcher ensures the server always serves the most recent certificates, critical for rotated SVIDs or expiring administrative certs.
Sources: ground-control/internal/middleware/certwatcher.go:48-69
Middleware Components Summary
| Middleware | Location | Purpose |
|---|---|---|
AuthMiddleware | server/middleware.go | Authenticates administrative users via Token or Basic Auth. |
RequireRole | server/middleware.go | Enforces RBAC for API endpoints. |
AuthMiddleware (SPIFFE) | spiffe/middleware.go | Extracts SPIFFE identity from mTLS connections. |
RequireSPIFFEAuth | spiffe/middleware.go | Rejects any request lacking a valid SPIFFE SVID. |
TokenAuthMiddleware | spiffe/middleware.go | Authenticates satellites in non-zero-trust environments. |
Sources: ground-control/internal/server/middleware.go, ground-control/internal/spiffe/middleware.go
Conclusion
The Middleware and API Security system provides the necessary flexibility to secure Harbor Satellite across diverse network topologies. By combining traditional session-based security for users with modern, cryptographic identities for edge devices, the project ensures that artifact distribution remains both accessible and secure against unauthorized access.