.env ファイルをやめて Bitwarden Secrets Manager に移行した話

この記事はなに？

私たちcoiaiはモックアップの作成業務がメインで今までの開発は１－２名程度でした。しかし、６名以上で開発を進めていく案件が増えてきたため、開発環境を見直す必要に迫られました。

今まで環境変数は .env ファイルで管理していました。しかしこれからは、平文として秘密情報が確認できない状態にすること、チームで環境変数の共有の際にセキュアな共有方法を確保することを目的とし、環境整備を行いました。

Bitwarden 導入の目的と意義

• 秘密情報(APIキー・OAuthクライアント等)を .env の平文で持つのをやめ、
  Bitwarden Secrets Manager に移する
• Bitwarden が推奨する bws run を使うと、秘密は実行の瞬間だけ
  環境変数としてプロセスに注入され、ディスクに平文が残らない
• 「環境変数 > .env ファイル」の優先順で設定を読む作りにしておけば、
  既存のスクリプトも docker-compose もコード変更ゼロで移行できる
• チーム共有は「読み取り専用のアクセストークンを渡すだけ」になる

背景: .env の何が問題か

ローカル開発の秘密情報は .env + .gitignore が定番だが、いくつか弱点がある。

1. 配布が手作業 — 新メンバーや新PCに .env をチャットやUSBで渡すことになりがち。
   渡した瞬間にコピーが増え、ローテーションも「全員に再配布」になる
2. ディスクに平文で残る — バックアップ・ファイル共有・誤コミットに紛れ込むリスク
3. AIコーディングエージェントに読まれる — Claude Code や Cursor のように
   シェル/ファイルアクセスを持つエージェントは、悪意がなくても問題解決の過程で
   cat .env や printenv を実行する。Bitwarden 自身がこの点をブログで指摘している
   (Your coding agent can read your .env file)

1 と 2 を解決するのがシークレット管理サービスで、Bitwarden Secrets Manager は
その中でも安価(Password Manager とは別契約)かつ CLI が単体バイナリで導入が軽い。

Bitwarden Secrets Manager で抑えて起きたい概念

注意点としてPassword Manager(個人のパスワード保管)とは別プロダクトです！Password Manager は弊社でも利用していますが、今回Secret Manager を追加で契約した形になります。

概念は3つだけです。

概念	役割
プロジェクト	シークレットの入れ物。今回は 1 リポジトリ = 1 プロジェクト
シークレット	KEY / VALUE / メモ の3つ組。.env の 1 行 = 1 シークレット にする
マシンアカウント	人間ではなくプログラム用のアカウント。プロジェクト単位で読み取り/読み書き権限を付与し、アクセストークンを発行する

Secrets Manager プロジェクト「MyProject」
  ├─ GOOGLE_CLIENT_ID     = xxxx.apps.googleusercontent.com
  ├─ GOOGLE_CLIENT_SECRET = GOCSPX-xxxx
  ├─ POSTGRES_PASSWORD    = xxxx
  └─ ...
        ▲ 読み書き: 管理者用マシンアカウント(自分)
        ▲ 読み取りのみ: メンバー用マシンアカウント(チーム配布)

セットアップ手順(Windows)

1. Web Vault 側

1. Secrets Manager でプロジェクト(例: MyProject)を作成
2. マシンアカウントを作成 → 「プロジェクト」タブでプロジェクトを追加し、
   権限を 「読み取り可、書き込み可」 にする(メンバー配布用は別アカウントで「読み取り可」)
3. 「アクセストークン」タブでトークンを発行(0.xxxxxxxx... 形式)

2. bws CLI の導入

bws は Rust 製の単体バイナリ。winget には無いので
GitHub リリースから
bws-x86_64-pc-windows-msvc-<version>.zip を取得し、
%LOCALAPPDATA%\Programs\bws あたりに展開して PATH に追加する。

$dir = "$env:LOCALAPPDATA\Programs\bws"
New-Item -ItemType Directory -Force $dir | Out-Null
Invoke-WebRequest "https://github.com/bitwarden/sdk-sm/releases/download/bws-v2.1.0/bws-x86_64-pc-windows-msvc-2.1.0.zip" -OutFile "$env:TEMP\bws.zip"
Expand-Archive "$env:TEMP\bws.zip" $dir -Force
# PATH への追加(ユーザー環境変数)
[Environment]::SetEnvironmentVariable("Path",
  [Environment]::GetEnvironmentVariable("Path","User") + ";$dir", "User")

3. アクセストークンの保存

トークンはファイルに書かず、ユーザー環境変数として保存する。

setx BWS_ACCESS_TOKEN "0.xxxxxxxx-xxxx-...."

EU サーバー契約の場合はサーバー URL の設定も必要:
bws config server-base https://vault.bitwarden.eu

4. 既存 .env の一括登録

bws secret create KEY VALUE <プロジェクトID> を繰り返せばよい。
手元の .env から一括登録するならこんなワンライナーでも足りる
(本プロジェクトでは push/pull/diff できる補助スクリプトにした):

$pid_ = (bws project list | ConvertFrom-Json)[0].id
Get-Content .env | Where-Object { $_ -match "^\s*[^#].*=" } | ForEach-Object {
  $k, $v = $_ -split "=", 2
  bws secret create $k.Trim() $v.Trim() $pid_
}

登録が終わったら .env は削除する。ここがこの移行のゴール。

日常の使い方: bws run

秘密が必要なコマンドに bws run -- を前置するだけ。プロジェクト内の全シークレットが
KEY 名の環境変数としてそのプロセス(とその子プロセス)にだけ注入される。

bws run -- py scripts/drive_sync.py       # Google API を使うスクリプト
bws run -- docker compose up -d db        # compose の ${VAR} 展開にも効く

値の確認・変更は Web Vault の GUI か CLI で:

bws secret list <プロジェクトID>          # 一覧(値も表示されるので注意)
bws secret edit --value "新しい値" <シークレットID>

既存プロジェクトを無変更で移行できる条件

bws run は「環境変数を注入する」だけなので、アプリ側が環境変数を読めれば動く。

• 自作スクリプト: 設定読み込みを「環境変数があれば優先、なければ .env」の順に
  しておく(dotenv 系ライブラリの標準挙動もこれ)。こうすると Bitwarden を使わない
  メンバーは従来どおり .env でも動く、という逃げ道が残る
• docker-compose: ${POSTGRES_USER:-default} 形式の変数展開は、.env ファイルが
  無ければプロセスの環境変数にフォールバックするので bws run -- docker compose up で
  そのまま動く。全キーにデフォルト値を書いておくと Bitwarden なしでも起動できて便利
• シークレットの KEY 名: 環境変数名として使うので英数字とアンダースコアに
  限定しておく(POSIX 制約)。日本語などマルチバイトの値は問題なく通る(実測)

ハマりどころ(実際に踏んだもの)

setx した環境変数が見えない

setx は「これから新しく開くシェル」にしか効かない。設定後に同じウィンドウで
実行して「未設定です」と言われたら、ターミナルを開き直すか、現在のシェルに手で読み込む:

$env:BWS_ACCESS_TOKEN = [Environment]::GetEnvironmentVariable("BWS_ACCESS_TOKEN","User")

書き込みで 404 Not Found

bws secret create が [404 Not Found] Resource not found. で失敗する場合、
シークレットやプロジェクトが無いのではなく、マシンアカウントに書き込み権限が無い
のが原因のことが多い。Bitwarden は権限不足を(リソースの存在を隠すため)404 で返す。
bws project list が通るのに create が 404 なら、まず権限を疑う。

bws run の引用符問題(Windows)

bws run は受け取ったコマンドをシェル経由で再実行するため、
bws run -- py -c "import os; ..." のような複雑な引用符は途中で剥がれて壊れる。
ワンライナーではなくスクリプトファイルにしてから bws run -- py script.py とするのが確実。

セキュリティ上の限界も理解しておく

この構成で無くなるのは「秘密のディスク上の平文コピー」と「配布の属人化」。
一方で残るものもある:

• BWS_ACCESS_TOKEN 自体はユーザー環境変数(レジストリ)に平文で残る。
  同一マシン内の攻撃者には結局シークレットを取得されうる。ただし漏洩時の対処が
  「該当トークンを失効して再発行」だけで済むのが .env との決定的な違い
• OAuth のトークンキャッシュ(token_drive.json 等)のように、
  アプリが自前でディスクに書く認証情報は別途残る
• bws run は実行のたびに API へ取りに行くためオフラインでは動かない。
  オフライン作業が必要なら一時的に .env を生成して、済んだら消す運用にする

公式のベストプラクティスとしては、さらに
「マシンアカウントは用途(人・エージェント・CI)ごとに分ける」
「短命な用途のトークンには有効期限を付ける」が挙げられている。

まとめ

• .env の役割は「シークレット管理サービス + 実行時注入」で置き換えられる
• Bitwarden Secrets Manager なら bws run -- を前置するだけで、
  既存コードほぼ無変更・チーム配布はトークン1本で済む
• 移行の実作業は Web Vault での 3 クリックと、CLI の zip 展開、setx 1回だけ

参考リンク

• Secrets Manager CLI | Bitwarden — bws run の仕様・認証方法
• Developer Quick Start | Bitwarden — 開発ワークフローの推奨手順
• Your coding agent can read your .env file | Bitwarden Blog — .env 廃止を推す背景とベストプラクティス
• bitwarden/sdk-sm Releases — bws CLI のバイナリ配布