Secure ADK agents with Secret Manager

Key Concepts

• API Key Security: Methods and best practices for protecting sensitive API keys from unauthorized access.
• Agent Development Kit (ADK): A framework or set of tools used to build agents, which often require API keys for external service integration.
• Environment Variables: A method of storing configuration data, including API keys, outside of the main codebase, accessible by the application at runtime.
• Google Cloud Secret Manager: A fully managed service in Google Cloud for storing, managing, and accessing sensitive data like API keys, passwords, and certificates.
• Hardcoding: Embedding sensitive data directly into the source code, which is highly discouraged due to security risks.
• Centralized Management: The ability to manage all secrets from a single, unified platform.
• Fine-grain Access Control: The ability to define precise permissions for who can access specific secrets, often using Identity and Access Management (IAM).
• Audit Logging: The capability to record and review all access attempts and modifications to secrets, providing accountability and security insights.
• Google Cloud Console: The web-based user interface for managing Google Cloud resources.
• Secret Manager Secret Accessor Role: A specific IAM role that grants permission to read the value of a secret but not to modify or delete it.
• Service Account: A special type of Google account used by applications or virtual machines to make authorized API calls.
• Application Default Credentials (ADC): A strategy used by Google Cloud client libraries to automatically find credentials based on the environment (e.g., user account for local development, service account for production).
• IAM (Identity and Access Management): Google Cloud's system for managing who has what access to which resources.
• Cloud Audit Logs: Google Cloud's service for recording administrative activities and data access events across Google Cloud resources.
• access_secret_version: A specific API call within the Secret Manager client library used to retrieve the value of a secret version.

---

Securing API Keys in ADK Agents with Google Cloud Secret Manager

This video demonstrates a critical security improvement for agents built with the Agent Development Kit (ADK): moving API key management from environment variables to Google Cloud Secret Manager. The process enhances security, management, and auditability for sensitive credentials.

Initial Approach and Its Limitations

The starting point involves an agent that retrieves a Google Maps API key from an environment variable. While this method is an improvement over hardcoding keys directly into the source code (which makes keys visible in version control history and complicates key rotation), it still presents security vulnerabilities. Keys stored in environment variables exist in plain text on the machine, making them susceptible to exposure through logs, debugging output, or system inspection.

Advantages of Google Cloud Secret Manager

Google Cloud Secret Manager addresses the shortcomings of previous methods by offering:

• Centralized management: A single platform to manage all secrets.
• Encrypted storage: Keys are stored and encrypted by Google.
• Fine-grain access control: Permissions are managed through IAM, allowing precise control over who can access secrets.
• Audit logging: All access and modification attempts are recorded via Cloud Audit Logs, providing a clear audit trail. These features are particularly valuable for production systems.

Step-by-Step Process for Integration

The integration of Secret Manager involves three main steps:

1. Creating the Secret in Google Cloud Secret Manager:

   • Navigate to the Google Cloud Console and select Secret Manager.
   • Create a new secret, naming it specifically ADK-maps-API-key.
   • Paste the actual API key value into the secret.
   • Leave other settings as defaults and create the secret. The key is then stored and encrypted by Google.

2. Setting Permissions for Secret Access:

   • The application's identity (the "principal") needs explicit permission to access the newly created secret.
   • For local development, this principal is typically the user account.
   • For a production deployment, a service account would be used.
   • Grant the principal the Secret Manager Secret Accessor role. This specific IAM role allows the principal to read the secret's value but explicitly does not grant permissions to modify or delete it, adhering to the principle of least privilege.

3. Updating the Application Code (Python Example):

   • Install the client library: The necessary Google Cloud Secret Manager client library must be installed in the application's environment.
   • Import the client: In the Python script, import the Secret Manager client.
   • Implement get_secret function: A function named get_secret is created. This function takes a project ID and secret name as arguments.
     • It constructs the full resource name for the secret version.
     • It then calls the access_secret_version method of the Secret Manager client to retrieve the secret's payload.
     • Finally, it decodes the response to get the plain text secret value.
   • Integrate into main script: In the main part of the agent's script, this get_secret function is called. The retrieved API key is then passed to the MCP tool set within a dictionary, ensuring the agent fetches the key at runtime.

Conclusion and Main Takeaways

By adopting Google Cloud Secret Manager, the API key is moved from a less secure environment variable to a robust, managed service. The application authenticates using Application Default Credentials (ADC), which automatically handles credential discovery, and fetches the secret dynamically when it runs. This method provides significant security benefits:

• Centralized management of all secrets.
• Encrypted storage of sensitive credentials.
• Fine-grain access control through IAM.
• Comprehensive auditability via Cloud Audit Logs.

This pattern significantly improves the overall security posture of applications that handle sensitive credentials, making them more resilient against exposure and easier to manage in production environments.