Skip to main content

0056: Secure Credential Management for Adapters

Date: 2025-12-04

Status: Accepted

Context​

The notification-service relies on multiple third-party adapters (e.g., SendGrid, Twilio, AWS SES) to deliver messages. These adapters require sensitive credentials, such as API keys, SMTP passwords, and XOAUTH2 refresh tokens.

Hardcoding these credentials in the codebase or baking them into container images is a severe security risk. Relying solely on environment variables can also be risky in shared environments where environment inspection is possible. We need a unified, secure strategy for managing these secrets at runtime.

Decision​

We will manage all adapter credentials using the platform's central Secret Management System (e.g., Vault), accessed via the standard Configuration Service client.

  1. No Hardcoded Secrets: Credentials must never appear in source code or version control.
  2. Runtime Retrieval: The service will fetch its configuration and secrets at startup (or periodically) from the central configuration provider.
  3. Sender Profiles: Credentials will be organized by "Sender Profiles" (e.g., email.profiles.marketing, sms.profiles.alerts). This allows the service to manage multiple identities (and thus multiple sets of credentials) for a single channel type without code changes.
  4. XOAUTH2 Support: For email providers requiring modern authentication (like Gmail or Outlook), the service will store and use Refresh Tokens. The adapter will be responsible for exchanging the refresh token for a short-lived Access Token at runtime, ensuring long-term access without manual intervention.

Consequences​

Positive​

  • Enhanced Security: Secrets are stored encrypted at rest in a dedicated system (Vault), not in plain text config files.
  • Centralized Rotation: Operations teams can rotate API keys in the central store without redeploying the application.
  • Compliance: Meets standard compliance requirements for secret management.
  • Multi-Identity Support: The profile-based config structure allows easy management of distinct credentials for different business functions (Sales vs. Support).

Negative​

  • Runtime Dependency: The service cannot start if the Configuration/Secret service is unavailable.
  • Local Dev Complexity: Developers must set up a local secrets provider (or use a local .env file adapter supported by the config library) to run the service locally.