Skip to content

012. Secret Management Strategy

  • Status: Proposed
  • Date: 2025-09-17

Context

Following the decision in ADR-009, all sensitive data is managed via environment variables. However, that ADR does not specify the underlying process for storing, managing, accessing, and rotating these secrets. The current workflow, which relies on developers manually managing environment variables (e.g., for GOOGLE_CLIENT_ID in docker-compose.yml), presents several risks: 1. Secret Sprawl: Without a centralized secret management system, secrets might be stored in insecure locations (e.g., unencrypted .env files on developer machines, in private messages, or even accidentally committed to version control). 2. Lack of Auditing: It is difficult to track who accessed which secret and when. 3. No Centralized Rotation: There is no defined process or mechanism for rotating secrets, which is a critical security practice to limit the damage of a potential leak. 4. Inconsistent Access Control: Permissions for accessing secrets are not formally managed, leading to potential unauthorized access.

A formal strategy is required to address these issues and secure the application's lifecycle.

Decision

  1. Adopt a Centralized Secret Management Tool: The project will use Google Secret Manager as the central, single source of truth for storing all application secrets across all environments (development, staging, production). This choice aligns with the existing use of Google Cloud services (e.g., for SSO authentication).

  2. Define Strict Access Control: Access to secrets in Google Secret Manager will be controlled via IAM (Identity and Access Management) roles. Permissions will be granted on a "least privilege" basis, specific to environments and services.

  3. Standardize Local Development Workflow: For local development, developers will be granted limited access to read secrets from a dedicated development project in Google Cloud. A CLI helper script or integration with existing tooling will be used to fetch these secrets and populate local .env files. These .env files must remain in .gitignore. Production secrets will not be available for local development.

  4. Establish a Secret Rotation Policy: A formal policy for secret rotation will be implemented.

    • High-Impact Secrets (e.g., database credentials, service account keys) must be rotated every 90 days.
    • Low-Impact Secrets (e.g., API keys for non-critical third-party services) must be rotated every 180 days.
    • A Standard Operating Procedure (SOP) will be created to document the rotation process for each secret.

Consequences

Positive

  • Enhanced Security: Centralizes secrets in a secure, encrypted, and auditable environment, significantly reducing the risk of secret sprawl and leakage.
  • Improved Governance and Auditing: Provides clear audit trails of when and by whom secrets are accessed or modified.
  • Simplified Secret Rotation: Enables programmatic and scheduled rotation of secrets, improving the project's security posture.
  • Streamlined Developer Experience: Provides a clear and secure process for developers to obtain necessary credentials for local development without exposing production secrets.
  • Granular Access Control: Enforces the principle of least privilege for accessing sensitive information.

Negative

  • Increased Complexity: Introduces a new tool (Google Secret Manager) into the stack, which requires initial setup, configuration, and learning for the team.
  • Dependency on Google Cloud: Creates a tighter coupling with the Google Cloud ecosystem.
  • Operational Overhead: Requires ongoing management of IAM policies, rotation schedules, and the secret management infrastructure itself.
  • Potential for Latency: Fetching secrets at application startup might introduce a minor latency penalty, which needs to be managed.