bitwarden-credential-management

name	bitwarden-credential-management
description	Secure credential management for AI agents via official Bitwarden MCP server and bw CLI. Agents can store and retrieve secrets without exposing the entire vault. All access is audited.
triggers	["bitwarden","vault","credential","password manager","mcp bitwarden","bw cli","agent credentials"]
confidence	high

Bitwarden — AI Agent Credential Management

Provides secure, audited credential management for AI agents. Two access methods: Bitwarden MCP server (preferred) and bw CLI (fallback).

CRITICAL: Security Rules

1. NO DELETE — Agents may NEVER delete vault items. Only the vault owner (human) can delete.
2. NO EXPORT — Never export the entire vault or dump all passwords.
3. NO MASTER PASSWORD — Never request, store, or log the master password.
4. AUDIT ALL ACCESS — Every credential access must be logged.
5. LEAST PRIVILEGE — Only retrieve the specific credential needed for the current task.
6. NO PLAINTEXT LOGGING — Never log actual password values. Log only item name/ID + action + timestamp.

Architecture

┌─────────────────────────────────────────────────┐
│  Agent Process (Copilot CLI, CI runner, etc.)    │
│                                                   │
│  ┌──────────────┐    ┌─────────────────────────┐ │
│  │ MCP tools     │    │ bw CLI (fallback)       │ │
│  │ (preferred)   │    │ inherits BW_SESSION     │ │
│  └──────┬───────┘    └────────────┬────────────┘ │
│         │                         │               │
│  ┌──────▼─────────────────────────▼──────────┐   │
│  │ @bitwarden/mcp-server (stdio)             │   │
│  │ Inherits BW_SESSION from User env var      │   │
│  └──────────────────┬────────────────────────┘   │
│                      │                             │
└──────────────────────┼─────────────────────────────┘
                       │
               ┌───────▼───────┐
               │ Bitwarden     │
               │ Vault (cloud) │
               └───────────────┘

Prerequisites

• Bitwarden CLI: npm install -g @bitwarden/cli
• Bitwarden MCP server: npm install -g @bitwarden/mcp-server
• BW_SESSION: Set as a persistent environment variable (see below)
• MCP config: Entry in your Copilot MCP config for the "bitwarden" server

BW_SESSION — Persistent Session Key

BW_SESSION is an encryption key derived from the master password. It is NOT a JWT and does NOT expire on its own. This is the key insight that makes persistent agent access work.

How it's stored: As a User-level environment variable (Windows) or in shell profile (macOS/Linux). All new processes inherit it automatically — including background agents, watch processes, and new terminal sessions.

It only breaks if:

• Master password is changed
• Account is reset
• Explicit bw lock or bw logout is run

Setting it (one-time, done by vault owner):

Windows (PowerShell)

# Login (first time only)
bw login [e-mail]

# Unlock and persist as User-level env var
$session = bw unlock --raw
[System.Environment]::SetEnvironmentVariable("BW_SESSION", $session, "User")
$env:BW_SESSION = $session

macOS / Linux

# Login (first time only)
bw login [e-mail]

# Unlock and persist in shell profile
export BW_SESSION=$(bw unlock --raw)
echo "export BW_SESSION=$BW_SESSION" >> ~/.bashrc  # or ~/.zshrc

Agent Auto-Detection Pattern

Before using Bitwarden, every agent MUST run this check:

1. Is the Bitwarden MCP server available? (check tool list for bitwarden tools)
   → YES: Use MCP tools (preferred path)
2. Is BW_SESSION set?
   → YES: Use bw CLI as fallback
3. Neither available?
   → Report: "Bitwarden not available — BW_SESSION not set and MCP server not configured."
   → Do NOT fail silently. Do NOT attempt to unlock.

Access Method 1: MCP Tools (Preferred)

When the Bitwarden MCP server is configured, agents get native tools for vault operations. No CLI invocation needed.

MCP config entry (add to your MCP config file):

{
  "servers": {
    "bitwarden": {
      "type": "stdio",
      "command": "npx",
      "args": ["@bitwarden/mcp-server"]
    }
  }
}

The MCP server runs via stdio, inherits env vars (including BW_SESSION), and exposes tools directly. Agents don't need to do anything special — the tools appear automatically.

Key MCP tools available:

Tool	Purpose
list	List vault items (with search/filter)
get	Retrieve a specific item by ID or name
create_item	Create a new vault item
edit_item	Update an existing item
generate	Generate secure passwords/passphrases
get_totp	Get current TOTP code for an item

Access Method 2: bw CLI (Fallback)

When MCP is not available, use the standard bw CLI. The BW_SESSION env var is inherited automatically.

Store a Credential

$item = @{
  type = 1  # Login type
  name = "squad/service-name"
  notes = "Created by [agent-name] for [purpose]"
  login = @{
    username = "the-username"
    password = "the-password"
    uris = @(@{ uri = "https://service-url.com" })
  }
} | ConvertTo-Json -Depth 5

$encoded = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes($item))
bw create item $encoded --session $env:BW_SESSION

Naming Convention: Prefix item names with a namespace (e.g., squad/github-api-key, myproject/azure-storage-key).

Retrieve a Credential

bw get item "squad/service-name" --session $env:BW_SESSION
bw get password "squad/service-name" --session $env:BW_SESSION

List Credentials

bw list items --search "squad/" --session $env:BW_SESSION

Update a Credential

$item = bw get item "squad/service-name" --session $env:BW_SESSION | ConvertFrom-Json
$item.login.password = "new-password"
$encoded = [Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes(($item | ConvertTo-Json -Depth 5)))
bw edit item $item.id $encoded --session $env:BW_SESSION

Audit Logging

Every credential access MUST be logged. Example format:

[2026-03-26T18:20:00Z] GET    | agent=AgentName | item=squad/github-token | method=MCP
[2026-03-26T18:21:00Z] STORE  | agent=AgentName | item=squad/azure-key    | method=CLI
[2026-03-26T18:22:00Z] LIST   | agent=AgentName | search=squad/           | method=MCP  | count=5

Format: [ISO-timestamp] ACTION | agent=NAME | item=ITEM_NAME | method=MCP|CLI

Background Agent Integration

Background watch processes and autonomous agents inherit BW_SESSION from the User env var automatically — no special setup needed.

Startup health check: Agents SHOULD verify Bitwarden availability at startup:

# Check BW health at startup
$bwStatus = bw status --session $env:BW_SESSION 2>&1 | ConvertFrom-Json
if ($bwStatus.status -ne "unlocked") {
    Write-Warning "⚠️ Bitwarden vault is NOT unlocked. Status: $($bwStatus.status)"
    Write-Warning "Credential operations will fail. Notify vault owner."
} else {
    Write-Host "✅ Bitwarden vault unlocked. Last sync: $($bwStatus.lastSync)"
}

Cross-Machine Setup

Each machine needs a one-time setup:

# 1. Install tooling
npm install -g @bitwarden/cli
npm install -g @bitwarden/mcp-server

# 2. Login and unlock
bw login [e-mail]
$session = bw unlock --raw

# 3. Persist BW_SESSION (Windows)
[System.Environment]::SetEnvironmentVariable("BW_SESSION", $session, "User")
$env:BW_SESSION = $session

# 4. Configure MCP server in your Copilot MCP config
# Add the bitwarden server entry to your mcp-config.json

# 5. Verify
bw status --session $env:BW_SESSION

What's Next: Bitwarden Agent Access (aac)

Bitwarden is building an official Agent Access tool (aac) — an open protocol with E2E encrypted tunnels (Noise protocol) for agent credential access. Key differences from the BW_SESSION approach:

	BW_SESSION approach	Agent Access (aac)
Scope	Full vault accessible	Per-domain credential scoping
Security	Session key in env var	E2E encrypted tunnel
LLM exposure	Creds flow through tools	aac run injects via env vars only
Status	Production-ready	Early preview

Watch: github.com/bitwarden/agent-access

Troubleshooting

Symptom	Cause	Fix
You are not logged in	Never logged in on this machine	bw login [e-mail]
Vault is locked	BW_SESSION missing or invalid	Vault owner re-unlocks, sets env var
Item not found	Name mismatch or stale cache	Check namespace prefix; run bw sync
MCP tools not appearing	MCP server not configured	Add entry to your MCP config
MCP tools fail silently	BW_SESSION not inherited	Verify User-level env var is set (not just process-level)
bw status shows locked after reboot	User env var lost or password changed	Re-run unlock + persist steps