Authentication & Policies
Relevant source files
The following files were used as context for generating this wiki page:
Authentication and policies in the Harbor Satellite project provide the security framework necessary to manage communication between the central Ground Control service and distributed Satellites. This system ensures that only authorized users can manage the fleet and only identified Satellites can synchronize artifact states. The project implements a multi-tiered authentication strategy including User authentication (Basic Auth and Bearer Tokens), Satellite authentication (One-time tokens or SPIFFE/SPIRE identity), and strict Password Policies for administrative security.
Sources: QUICKSTART.md:12-41, ground-control/internal/server/middleware.go:25-78
User Authentication & Authorization
Ground Control employs a middleware-based authentication system for administrative users. It supports dual authentication methods: session-based Bearer tokens and standard Basic Authentication. Once authenticated, users are assigned roles that determine their access levels to various API endpoints.
Authentication Middleware Logic
The AuthMiddleware processes incoming HTTP requests by first attempting to extract a Bearer token. If a valid session is found in the database, the user's ID, username, and role are injected into the request context. If no token is present or valid, it falls back to Basic Auth, verifying the provided credentials against hashed passwords stored in the database.
The flow ensures a secure fallback mechanism for API consumers and interactive users.
Sources: ground-control/internal/server/middleware.go:25-63
Role-Based Access Control (RBAC)
The system defines specific roles to restrict sensitive operations. Key roles identified include system_admin and admin.
| Role | Description |
|---|---|
system_admin | Highest privilege; can create/delete users and change any user's password. |
admin | Standard administrative access for managing satellites and groups. |
Sources: ground-control/internal/server/user_handlers.go:16-19, ground-control/internal/server/middleware.go:73-86
Satellite Authentication Methods
Satellites utilize distinct authentication mechanisms to register with Ground Control. The method is chosen based on the deployment environment's security requirements.
Token-based Zero-Touch Registration (ZTR)
In development or simple environments, an administrator generates a one-time token via the Ground Control API. The satellite uses this token to bootstrap its initial connection.
Sources: QUICKSTART.md:16-22, ground-control/internal/spiffe/middleware.go:107-142
SPIFFE/SPIRE Identity
For production, the project recommends SPIFFE (Secure Production Identity Framework for Everyone). This method provides zero-trust, certificate-based identity using X.509 SVIDs with automatic rotation.
SPIRE Agents run alongside the Satellite and Ground Control to handle the cryptographic heavy lifting.
Sources: deploy/quickstart/README.md:17-29, ground-control/internal/spiffe/middleware.go:30-55
Security Policies
Password Policy
Ground Control enforces a configurable password policy to ensure administrative account security. This policy is applied during user creation and password change operations.
| Parameter | Default Value | Environment Variable |
|---|---|---|
| Minimum Length | 8 | PASSWORD_MIN_LENGTH |
| Maximum Length | 128 | PASSWORD_MAX_LENGTH |
| Require Uppercase | True | PASSWORD_REQUIRE_UPPERCASE |
| Require Lowercase | True | PASSWORD_REQUIRE_LOWERCASE |
| Require Number | True | PASSWORD_REQUIRE_NUMBER |
| Require Special | False | PASSWORD_REQUIRE_SPECIAL |
Sources: ground-control/internal/auth/policy.go:21-70
Configuration Validation
The project includes a validation engine that enforces security defaults during startup. This includes verifying TLS certificate paths, ensuring required registry URLs are present, and enforcing secure defaults for log levels and cron schedules.
// ground-control/internal/auth/policy.go:72-106
func (p PasswordPolicy) Validate(password string) error {
var violations []string
if len(password) < p.MinLength {
violations = append(violations, fmt.Sprintf("at least %d characters", p.MinLength))
}
// ... logic for uppercase, lowercase, numbers, and special characters
if len(violations) == 0 {
return nil
}
return fmt.Errorf("password must contain: %s", strings.Join(violations, ", "))
}
Sources: ground-control/internal/auth/policy.go:72-106, pkg/config/validate.go:20-55
Summary
The Authentication & Policies system creates a secure perimeter around the Harbor Satellite ecosystem. By combining traditional RBAC for users with advanced SPIFFE-based identities for edge devices, the architecture supports both ease of use for developers and high-security requirements for production fleet management. Password policies and configuration validation further harden the system against misconfiguration and credential-based attacks.