Service Account Authentication

Service Account Authentication

Manage multiple Google Cloud identities securely without polluting your repository settings or environment.

Table of Contents

• Service Account Authentication
  • Table of Contents
  • Overview
  • Zero-Pollution Architecture
  • Managing Service Accounts
    • 1. Using Stored Secrets (Recommended)
    • 2. Using Local File Paths
  • Switching Between Accounts
  • Project ID Overrides
  • Security & Privacy

Overview

While Application Default Credentials (ADC) via gcloud auth are convenient for individual development, Service Accounts are better for:

• Ephemeral Environments: Codespaces or DevContainers where installing the gcloud SDK is bloat.
• Corporate Restrictions: Environments where browser-based login is blocked.
• Multi-Tenant Workflows: Seamlessly switching between different clients' GCP environments.

Zero-Pollution Architecture

The extension uses a "Zero-Pollution" strategy for authentication. Your authentication choices (which key you are using and the keys themselves) are never stored in settings.json or committed to your repository.

• Secrets: Stored in VS Code's encrypted storage.
• Selections: Stored in your local VS Code workspace database.
• Fallback: If a selected key is missing, the extension gracefully falls back to gcloud ADC.

Managing Service Accounts

1. Using Stored Secrets (Recommended)

This is the most secure method as it keeps the key content within VS Code's encrypted secret store.

1. Run the command: Vertex AI: Paste Service Account JSON Key
2. Paste the full content of your Google Cloud JSON key.
3. Provide a friendly name (e.g., Client-A).
4. The key is now saved globally and activated for the current workspace.

2. Using Local File Paths

If you prefer to keep your keys as files on your disk:

1. Run the command: Vertex AI: Select Service Account JSON File
2. Select your JSON key file using the native file picker.
3. The absolute path is saved locally for this workspace only.

Switching Between Accounts

You can switch between your stored secrets, file paths, or return to the default gcloud login at any time:

1. Run the command: Vertex AI: Select Authentication Method
2. Pick from the list of your named secrets or local files.
3. To stop using a service account and return to default ADC, run Vertex AI: Clear Authentication Method (Use ADC) or select Use Default Credentials (gcloud login) from the list.

The Status Bar will update its icon to reflect your current authentication method.

Project ID Overrides

The extension resolves the GCP Project ID in this order:

1. Settings: The value in vertexAiChat.projectId (Workspace or User settings).
2. JSON Key: The project_id field inside your active Service Account JSON.
3. System Default: The default project configured in your local gcloud context.

The active Project ID and its configuration source (e.g., "Workspace Setting", "Global Setting") are visible in the Status Bar tooltip.

This allows you to use one Service Account key to access multiple projects by simply changing the Project ID in your VS Code settings.

Security & Privacy

• No Settings Pollution: Abe and Bob can work on the same repo using different authentication methods (Abe uses a File Path, Bob uses a Secret) without ever seeing each other's configuration.
• Encrypted: Keys pasted into the extension are encrypted by the OS-level keychain via VS Code's SecretStorage.
• Offline Identity: When using a Service Account, the extension extracts your identity (client_email) locally, making the extension start up faster by avoiding external shell commands.