Vault setup

AI 요청 프롬프트

https://docs.axelabs.ai/onboard/vault-setup 따라 내 vault 본인 setup 진행해줘.

진행:
1. 내 머신 OS + 기존 환경 진단 (macOS Touch ID 유무, Chrome 설치, mobile 종류)
2. 페이지의 Prereq 확인 — 내가 KDF rotation 대상인지 (axe.2 적용 전 가입 user 만), 아니면 Phase 1 skip
3. 페이지의 각 Phase 명령 + 검증 매 step 결과 받고 다음
4. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
5. 모든 Phase 완료 후 운영자 ai 에게 Teams 회신 "vault setup 완료"

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

Prereq

• AXE 임직원 (@axellc.com) — Entra ID SSO 등록 완료
• 본인 macmini / 노트북 (macOS Touch ID 또는 Windows Hello 권장) + iPhone 또는 Android
• 본인 vault master password 기억 (변경 시 current MP 확인 + 새 MP 입력 필수)
• Microsoft Authenticator 가 phone 에 이미 설치되어 Entra MFA 등록 완료 상태

Phase 별 강제도 (skip 가능성 판단):

Phase 1 (KDF rotation) 대상 = “옛” user:

• ✅ 본인이 axe.2 release (2026-05-26) 이전 가입자 이면 KDF rotation 필요 (client_kdf_type=0, PBKDF2)
• ❌ axe.2 release 이후 신규 가입자 (realchoice 측 등) 는 새 schema 로 가입돼 KDF rotation 불필요 → Phase 1 skip
• 헷갈리면 일단 Phase 1 시도 — 옛 schema 면 효과, 새 schema 면 no-op (안전)

Phase 1: KDF rotation (옛 user 만, ~5분)

vault 의 SSO→MP unlock 정상화 (D-ops-40). 옛 KDF (PBKDF2) 로 wrap 된 user.akey 를 새 schema 로 재wrap.

1. https://axe.axelabs.ai/vault  — 새 incognito (Chrome 시크릿) 창 에서 접속
2. 본인 email ([email protected]) → Continue
3. ★ SSO 누르지 말고 Master password 단독 로그인 (본인 현재 MP)
4. 우상단 본인 이름 → Account settings → 좌측 사이드바 Security → 상단 Master password 탭
5. 입력:
   • Current master password: 본인 현재 MP
   • New master password: 같은 값으로 OK (또는 더 강한 12자 이상 새 값)
   • Confirm new master password: new 와 동일
   • ☑ Also rotate my account’s encryption key — 반드시 체크
6. Change master password 클릭 → 수십 초 대기 (client-side 가 모든 vault item 재암호)
7. 자동 logout

검증 (같은 incognito 창에서):

8. https://axe.axelabs.ai/vault  → 본인 email → Continue
9. 이번엔 Enterprise single sign-on 클릭
10. Microsoft 로그인 + MFA → vault redirect → MP 입력 → unlock 정상이면 ✅

axe.2 까지는 10번 단계에서 “Cannot read properties of null (reading toWrappedAccountCryptographicState)” 에러로 막혔음. KDF rotation 후 정상.

Phase 2: Bitwarden 데스크톱 앱 (~5분)

본인 OS 에 맞는 sub-section 따라가기.

Phase 2a — macOS

1. https://bitwarden.com/download/  → macOS Desktop (Universal) 다운로드 → /Applications 설치
2. 첫 실행 → 좌측 아래 gear (Settings) → Self-hosted environment
3. Server URL: https://axe.axelabs.ai/vault → Save
4. Log in with SSO (Enterprise single sign-on) → Entra ID + MFA → MP 입력 → Unlock
5. 메뉴 → Settings (⌘+,) → Preferences:
   • Vault timeout: Never
   • Vault timeout action: Lock
   • Unlock with Touch ID: ☑ (Touch Bar 또는 Magic Keyboard Touch ID)
   • Lock with master password on browser restart: ☑
6. Save

→ 이후 일상 unlock = Touch ID (1-2 초). MP 입력 = 앱 완전 재시작 + paranoia 옵션 시만.

Phase 2b — Windows

설치 경로 2 가지 — Microsoft Store vs .exe installer. 결과물 + 동작 같음, 자동 업데이트 채널만 다름.

설치 후:

1. 첫 실행 → 좌측 아래 gear (Settings) → Self-hosted environment
2. Server URL: https://axe.axelabs.ai/vault → Save
3. Log in with SSO → Entra ID + MFA → MP 입력 → Unlock
4. 메뉴 → Settings → Preferences:
   • Vault timeout: Never
   • Vault timeout action: Lock
   • Unlock with Windows Hello: ☑ (Windows Hello 사전 설정 PC 만 — 아래 분기 참조)
   • Lock with master password on browser restart: ☑
5. Save

Windows Hello 미설정 PC 의 fallback = PIN unlock:

• 설정에서 Unlock with Windows Hello 옵션이 회색 비활성 = OS 단에서 Hello 미등록 (PIN / 얼굴 / 지문 어느 것도 없음)
• 두 선택지:
  • (a) Windows Settings → Accounts → Sign-in options → Windows Hello PIN 등록 → Bitwarden 재시작 → Hello unlock 활성화
  • (b) Hello 등록 거부 시 → Unlock with PIN code ☑ + PIN 6자리 이상 (Chrome ext 와 동일 방식, Phase 3 참조)
• 권장 = (a). Hello = OS biometric / PIN 통합 채널이라 Bitwarden + 회사 다른 앱 동일 채널 사용 가능

→ 이후 일상 unlock = Windows Hello (또는 PIN). MP 입력 = 앱 완전 재시작 + paranoia 옵션 시만.

Phase 3: Chrome extension (~3분)

1. Chrome 에서 다운로드:

   https://chromewebstore.google.com/detail/bitwarden-free-password-m/nngceckbapebfimnlniiiahkandclblb

2. extension 아이콘 클릭 → ⚙ Settings → Self-hosted environment
3. Server URL: https://axe.axelabs.ai/vault → Save
4. Log in with SSO → 첫 MP unlock
5. ⚙ Settings → Account security:
   • Vault timeout: Never
   • Vault timeout action: Lock
   • Unlock with PIN code: ☑ + PIN 6자리 이상 (숫자보다 word 권장, 예: axe-2026)
   • Lock with master password on browser restart: ☑

→ 이후 unlock = PIN. Chrome 완전 재시작 시 MP 1회 (paranoia 옵션이면).

Phase 4: Mobile (iOS / Android, ~5분, 권장)

권장 (필수 아님). 데스크톱-only 워크플로 (외근 / 외출 중 vault 조회 불필요) 사용자는 skip 가능. skip 시 영향 = mobile 자동 채우기 / 외출 vault 조회 불가. 대부분 직원은 SMS / KB / 홈택스 등 mobile 2FA 도착 시 vault TOTP 조회가 필요해 설치 권장.

1. App Store / Play Store → “Bitwarden” 검색 → 노란 방패 아이콘 (Password Manager — Authenticator 와 다른 앱)
2. 설치 → 첫 실행 → Settings → Self-hosted environment:
   • Server URL: https://axe.axelabs.ai/vault → Save
3. Log in with SSO → Entra MFA → MP 입력 → Unlock
4. Settings → Account security:
   • Unlock with Face ID / Touch ID: ☑
   • Vault timeout: 1 month
   • Vault timeout action: Lock

→ Safari/Chrome 모바일 자동 채우기, 앱 안 자동 채우기 다 됨.

Phase 5: Bitwarden Authenticator (TOTP, ~3분, 선택)

외부 service (KB / 홈택스 / GitHub / 등) 의 2FA 코드를 vault 와 분리 저장 (D-ops-38 보조).

선택 (필수 아님). 기존 Google Authenticator / Microsoft Authenticator 앱에 등록된 TOTP 는 그대로 유지 OK — 새 2FA 등록 시점부터 본 표준 (vault item TOTP 필드) 적용을 권장하는 것. 기존 item 일괄 수정 SOP 아님.

”vault item TOTP 필드 저장” 의 의미

vault item TOTP 필드 UI 동작 (Bitwarden 공통)

데스크톱 / Chrome ext / mobile 어디서나 동일:

→ “복사 버튼 무반응” 이면 = 본인 item 에 secret 없음 = 편집 모드 진입 후 secret 입력 (또는 phone authenticator 에 그대로 두기).

Mobile (권장)

1. App Store / Play Store → “Bitwarden Authenticator” 검색
   • ★ Phase 4 의 Password Manager 와 별도 앱 — 회색 방패 + 시계 아이콘
2. 설치 → 첫 실행 → Bitwarden 계정 (axe.axelabs.ai/vault SSO 동일) 로그인 → sync 활성화
3. 끝 — Password Manager 의 TOTP 필드와 양방향 동기화

기존 Google / MS Authenticator 와 병행 OK. 신규 TOTP 만 Bitwarden 쪽에 등록해도 됨.

Desktop

Bitwarden Authenticator 는 mobile-only (2026-05 기준 macOS / Windows 공식 앱 없음).

대안 = Phase 2 의 Bitwarden Password Manager 데스크톱 앱이 TOTP 내장:

• vault item 의 Authenticator key (TOTP) 필드에 secret 저장 → 데스크톱에서 6-digit 자동 회전 (30초)
• D-ops-38 표준: 새 외부 service 2FA 등록 시 phone Authenticator 앱 대신 vault item TOTP 필드 사용 → mobile + desktop 양쪽 동일 코드

검증 + 완료 신호

자동 채우기 검증 — 워크플로 분기

vault item 접근 방식은 사용자별로 다름. 본인 워크플로에 맞는 검증만 통과하면 OK.

SSO 위주 사용자 (대다수 AXE 개발자 / taehun 같은 패턴) 는 웹 자동 채우기 거의 안 씀 = 자동 채우기 검증 skip OK. 검색 + 필드 복사가 정상 작동하면 통과.

전부 통과하면 운영자 ai ([email protected]) 에게 Teams 1:1 채팅으로 “vault setup 완료” 회신.

함정 정리

Phase 별 시간

표준 setup vs valid 변형

본 페이지의 표준 setup 외 valid 변형도 인정. 본인 워크플로에 맞으면 변형 사용 OK — 운영자 ai 에게 “valid 변형 X 사용 중” 명시만.

둘 다 D-ops-37 + D-ops-38 + D-ops-40 정합 — secret 이 vault SoT 에 있고 user master password 가 단일 unlock factor 면 valid.

일상 운영 (setup 완료 후)

• daily unlock = Touch ID (macOS) / Windows Hello (Windows) / Face ID (mobile) / PIN (Chrome ext) — 1-2 초
• MP 입력 빈도 = 데스크톱 / mobile 완전 재시작 시 + paranoia 옵션 켰을 때만 (월 1-2회)
• vault item 추가 = 데스크톱 앱이 가장 편함 (form 더 큼 + TOTP 필드 명시)
• service 2FA 코드 조회 = Bitwarden Authenticator (모바일) 또는 Password Manager 의 TOTP 필드 (데스크톱). Google/MS Authenticator 병행 사용자는 기존 앱 그대로
• 자동 채우기 안 뜨면 = Chrome ext 의 Self-hosted environment 확인 + extension 권한 (해당 사이트에서 contents 접근 허용). SSO 위주 사용자는 자동 채우기 미사용이 정상 — 검색 + 단축키 복사로 대체

참조

• D-ops-40 — vault axe.3 release plan + Progress (본 setup 의 배경)
• /architecture/vault-policies — 3 layer 정책 모델 (server env + Org Policies + per-client preferences). Phase 2-5 의 “Vault timeout / Unlock with X” 권장값의 근거
• D-ops-38 — 외부 service 2FA = vault TOTP 필드 (Phase 5 본질)
• D-ops-37 — axelabs-ai/vault Timshel fork build
• D-ops-26 + D-ops-27 — SSO_ONLY=false + MP fallback 보존
• B-vault-axe.2-sso-mp-incomplete — KDF rotation 진행 status (4명 완료 후 ✅)
• /ops/runbook/vault-recovery — vault 복구 (Phase 1 step 6 중단 등 비상 시)
• /ops/runbook/operator-broadcast — 본 setup 안내 broadcast 채널 (운영자가 신규 직원에게 본 페이지 URL 발송)