macOS Bitwarden/Vaultwarden CLI: 보안과 편의성을 한 번에 잡기

Bitwarden/Vaultwarden을 CLI 환경에서 사용할 때 가장 큰 걸림돌은 “매번 비밀번호를 입력해야 하는 번거로움” 입니다.
보안을 위해 세션 타임아웃을 짧게 가져가고 싶지만, 그럴 때마다 긴 마스터 패스워드를 입력하는 것은 생산성을 크게 떨어뜨립니다.

Vaultwarden은 Bitwarden과 프로토콜 및 클라이언트가 완전히 호환되는 오픈소스 서버 구현체로, Rust로 작성되어 가볍고 자체 호스팅에 최적화된 비공식 Bitwarden 서버입니다.

이 글에서는 macOS + Bitwarden/Vaultwarden 환경에서 pass 와 Keychain 을 조합하여 보안과 편의성을 모두 잡는 최종 솔루션을 정리합니다.

핵심 전략:

  1. API Key 대신 일반 로그인 : 호환성 문제 없이 안정적인 세션 관리.
  2. Pass + GPG : 마스터 패스워드를 암호화하여 저장.
  3. macOS Keychain 연동 : 매번 GPG 비밀번호를 칠 필요 없이 생체 인증/로그인 암호로 해결.
  4. Alias 자동화 : 명령어 한 줄로 잠금 해제.

1. 필수 도구 설치 및 GPG 설정

먼저 필요한 패키지를 설치하고, 터미널이 아닌 macOS 네이티브 팝업(Pinentry) 으로 비밀번호를 입력받도록 설정합니다.

# 1. 패키지 설치
brew install pass gnupg pinentry-mac

# 2. GPG가 macOS 팝업을 쓰도록 설정
echo "pinentry-program $(which pinentry-mac)" > ~/.gnupg/gpg-agent.conf

# 3. 설정 적용을 위해 에이전트 재시작
gpgconf --kill gpg-agent

2. GPG 키 생성 및 Pass 초기화

pass 유틸리티가 사용할 암호화 키를 생성합니다. 여기서 설정하는 비밀번호는 “GPG 키 패스프레이즈” 입니다. (나중에 키체인에 저장하므로 딱 한 번만 입력하면 됩니다.)

# 1. 키 생성 (RSA/RSA, 4096bit 권장)
gpg --full-generate-key

# 2. pass 저장소 초기화 (생성한 키 ID 또는 이메일 사용)
pass init "email@example.com"

3. 마스터 패스워드 저장

이제 Bitwarden/Vaultwarden의 실제 접속 비밀번호(Master Password) 를 pass 저장소에 안전하게 보관합니다.

pass insert vault/master
# (비밀번호 두 번 입력)

4. [핵심] 키체인 연동 (최초 1회 인증)

pass가 비밀번호를 복호화할 때, macOS Keychain 이 대신 인증을 처리하도록 위임하는 과정입니다. 이 설정 덕분에 매번 패스프레이즈를 입력할 필요가 사라집니다.

  1. 터미널에 다음 명령어를 입력합니다.
pass show vault/master
  1. Pinentry 팝업창 이 뜨면,
  • 비밀번호: 2단계에서 설정한 GPG 키 패스프레이즈를 입력합니다.
  • 옵션: ✅ Save in Keychain (키체인에 저장) 체크박스를 반드시 선택합니다.
  1. 성공 시, 비밀번호가 터미널에 출력됩니다. 다시 명령어를 입력했을 때 팝업 없이 바로 출력되면 성공입니다.

5. 로그인 (API Key 대안)

일부 Vaultwarden 버전이나 설정에서 API Key(--apikey) 방식이 불안정한 경우가 있어, 가장 확실한 대화형 로그인(bw login) 방식을 사용합니다. 기기를 변경하지 않는 한 로그인은 한 번만 하면 됩니다.

# 1. 서버 주소 설정 (Self-hosted인 경우)
bw config server https://vault.example.com

# 2. 로그인 수행
bw login
# (이메일 & 마스터 패스워드 입력)

성공 확인: “You are logged in!” 메시지가 나타나면 됩니다. 환경변수 설정은 아직 필요 없습니다.

6. 자동화 설정 (.zshrc)

이제 매일 아침 터미널을 열 때마다 명령어 한 방 으로 세션을 잠금 해제(Unlock)하도록 쉘 설정을 추가합니다.

~/.zshrc (또는 사용하는 쉘의 설정 파일) 맨 아래에 다음 내용을 추가하세요.

# =========================================
# Vaultwarden CLI Configuration
# =========================================

# 1. GPG TTY 설정 (필수: 팝업 오류 방지)
export GPG_TTY=$(tty)

# 2. 원터치 잠금해제 Alias
#    - pass가 키체인을 통해 마스터 패스워드를 가져옴
#    - bw unlock --raw로 세션 키만 추출하여 환경변수(BW_SESSION)에 등록
alias bwunlock='export BW_SESSION=$(pass show vault/master | bw unlock --raw) && [ -n "$BW_SESSION" ] && echo "🔓 Vault Unlocked via Keychain!" || echo "❌ Failed to unlock."'

설정 후에는 source ~/.zshrc로 변경 사항을 적용합니다.

⚠️ 문제가 발생한다면

  • bw unlock 시 멈춘다면 → bw status 확인
  • GPG 팝업이 뜬다면 → Keychain 저장 여부 재확인
  • 터미널 재시작 후에도 안 되면 → gpgconf —kill gpg-agent

7. 사용 방법

이제 복잡한 과정은 잊으셔도 됩니다.

  1. 터미널 실행
  2. bwunlock 입력
    • (GPG 팝업 없이 즉시 해제)
    • 🔓 Vault Unlocked via Keychain! 출력
  3. 사용 : bw list items 등 자유롭게 사용

이 설정으로 보안성은 유지하면서도 CLI 도구의 활용성을 극대화할 수 있습니다.