우분투 24.04에서 HashiCorp Vault SSH OTP를 설치하고 PAM을 연동하는 방법

우분투 24.04에서 HashiCorp Vault SSH OTP (vault-ssh-helper)를 설치하고 PAM을 연동하는 방법

HashiCorp Vault의 SSH OTP(One-Time Password) 기능을 활용하여 서버 SSH 로그인 시 일회용 비밀번호 기반 인증을 적용하는 방법입니다.

1. Vault 서버 설정 (Vault Cluster)

Vault 서버에서 SSH Secrets Engine을 활성화하고 권한을 설정합니다.

 

1.1 Vault 환경 변수 설정

export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN="hvs.WKz6o9e787ckjxVdOkPucQSs"

Vault 로그인(Root 토큰)

vault login "$VAULT_TOKEN"

1.2 SSH Secrets Engine 활성화 (경로: ssh-otp)

vault secrets enable -path=ssh-otp ssh

Success! Enabled the ssh secrets engine at: ssh-otp/

1.3 OTP 역할(Role) 생성

vault write ssh-otp/roles/otp-role \
    key_type=otp \
    default_user=ubuntu \
    cidr_list=0.0.0.0/0

Success! Data written to: ssh-otp/roles/otp-role

1.4 사용자 정책(Policy) 생성

일반 사용자가 자신의 권한으로 OTP를 발급받을 수 있도록 정책을 설정합니다.

tee ssh-policy.hcl <<EOF
path "ssh-otp/creds/otp-role" {
  capabilities = ["create", "read", "update"]
}
EOF

정책 업데이트

vault policy write ssh-user-policy ssh-policy.hcl

Success! Uploaded policy: ssh-user-policy

2. vault-ssh-helper 설치

2.1 의존성 패키지 설치

sudo apt update
sudo apt install -y unzip curl jq

2.2 바이너리 다운로드 및 설치

wget https://releases.hashicorp.com/vault-ssh-helper/0.2.1/vault-ssh-helper_0.2.1_linux_amd64.zip
unzip vault-ssh-helper_0.2.1_linux_amd64.zip
sudo mv vault-ssh-helper /usr/local/bin/
sudo chmod +x /usr/local/bin/vault-ssh-helper
vault-ssh-helper --version

rm -f vault-ssh-helper_0.2.1_linux_amd64.zip

2.3 설정 파일 생성

sudo mkdir -p /etc/vault-ssh-helper.d

sudo tee /etc/vault-ssh-helper.d/config.hcl <<EOF
vault_addr = "http://192.168.10.101:8200"
ssh_mount_point = "ssh-otp"

# TLS 환경에서는 ca_cert 설정 권장
ca_cert = ""
tls_skip_verify = true

allowed_roles = "*"
EOF

2.4 설정 검증

vault-ssh-helper -dev -verify-only -config=/etc/vault-ssh-helper.d/config.hcl

2026/04/09 21:18:03 ==> WARNING: Dev mode is enabled!
2026/04/09 21:18:03 [INFO] using SSH mount point: ssh-otp
2026/04/09 21:18:03 [INFO] using namespace:
2026/04/09 21:18:03 [INFO] vault-ssh-helper verification successful!

3. PAM 및 SSHD 연동

3.1 PAM(Pluggable Authentication Modules) 설정

백업

sudo cp /etc/pam.d/sshd /etc/pam.d/sshd_$(date '+%Y%m%d-%H%M%S')

기존 인증 비활성화

sudo sed -i.$(date '+%Y%m%d-%H%M%S') \
'/^[[:space:]]*#/! s/^[[:space:]]*@include[[:space:]]\+common-auth/#&/' \
/etc/pam.d/sshd

Vault OTP 인증 추가 (최상단)

sudo sed -i.$(date '+%Y%m%d-%H%M%S') '1i\
auth requisite pam_exec.so quiet expose_authtok log=/var/log/vault-ssh.log /usr/local/bin/vault-ssh-helper -config=/etc/vault-ssh-helper.d/config.hcl\
auth optional pam_unix.so not_set_pass use_first_pass nodelay
' /etc/pam.d/sshd

---

sudo vim /etc/pam.d/sshd

# @include common-auth  <-- 기존 라인 주석 처리
auth requisite pam_exec.so quiet expose_authtok log=/var/log/vault-ssh.log \
    /usr/local/bin/vault-ssh-helper -dev -config=/etc/vault-ssh-helper.d/config.hcl
auth optional pam_unix.so not_set_pass use_first_pass nodelay

---

3.2 SSHD 설정

백업

sudo cp /etc/ssh/sshd_config /etc/ssh/sshd_config_$(date '+%Y%m%d-%H%M%S')

SSHD 수정

sudo sed -i.$(date '+%Y%m%d-%H%M%S') \
-e 's/^#\?KbdInteractiveAuthentication.*/KbdInteractiveAuthentication yes/' \
-e 's/^#\?ChallengeResponseAuthentication.*/ChallengeResponseAuthentication yes/' \
-e 's/^#\?UsePAM.*/UsePAM yes/' \
-e 's/^#\?PasswordAuthentication.*/PasswordAuthentication no/' \
/etc/ssh/sshd_config

---

sudo vim /etc/ssh/sshd_config

KbdInteractiveAuthentication yes
ChallengeResponseAuthentication yes
UsePAM yes

# OTP만 사용할 경우
PasswordAuthentication no

# 병행 사용 시
# PasswordAuthentication yes

---

설정 검증

sudo sshd -t

3.3 SSH 재시작

sudo systemctl restart ssh

4. 사용자 접속 테스트(Client)

4-1. Vault 로그인

vault login -method=userpass username=vault_user

4.2 Role 확인

vault list ssh-otp/roles

vault read ssh-otp/roles/otp-role

4.3 OTP 발급

특정 서버 접속을 위한 일회용 비번 요청

vault write ssh-otp/creds/otp-role ip=192.168.10.201

Key                Value
---                -----
lease_id           ssh-otp/creds/otp-role/xC0aX3yCeQL2ZCUx3obMGMzK
lease_duration     768h
lease_renewable    false
ip                 192.168.10.201
key                9fd5a1d5-780e-d2bd-d8db-90b36ea35c7c
key_type           otp
port               22
username           ubuntu

4.4 SSH 접속

ssh ubuntu@192.168.10.201

비밀번호 입력 시 OTP(key) 입력

5. 로그 확인

tail -f /var/log/vault-ssh.log

참고

네트워크 제한

• cidr_list를 내부망으로 제한

TLS 적용 권장

tls_skip_verify = false
ca_cert = "/etc/ssl/certs/ca.pem"