로그인 MFA 설정하기
로그인 MFA 설정하기
Vault의 기반 아이덴티티 시스템은 서로 다른 인증 유형을 사용해 인증 방식에 인증하는 다중 요소 인증(MFA)을 지원해요.
| MFA 구현 | 필요한 Vault 에디션 |
|---|---|
| 로그인 MFA (Login MFA) | Vault Community |
| Step-up MFA | Vault Enterprise |
출처: 문서
본문
로그인 MFA 유형 (Login MFA types)
Vault의 MFA에는 다음 로그인 유형이 포함돼요.
참고: Token 인증 방식은 Vault 내장 로그인 MFA 기능으로 구성할 수 없어요.
시간 기반 일회용 비밀번호 (TOTP)— 로그인 경로에 구성·활성화되면, API 로그인 요청을 호출할 때 Vault 토큰과 함께 TOTP 패스코드를 제시해야 해요. 패스코드는 호출자의 Vault 신원에 있는 TOTP 키에 대해 검증돼요. TOTP는 자체 등록(self-enrollment)을 지원해요.Okta— 로그인 경로에 Okta push가 구성·활성화되면, 사용자의 등록된 디바이스가 API 접근을 승인하거나 거부하는 푸시 알림을 받아요. Okta 사용자 이름은 호출자 신원의 별칭에서 파생돼요.Duo— 로그인 경로에 Duo push가 구성·활성화되면, 사용자의 등록된 디바이스가 API 접근을 승인하거나 거부하는 푸시 알림을 받아요. Duo 사용자 이름은 호출자 신원의 별칭에서 파생돼요. Duo는 인증에 패스코드를 사용하도록 구성될 수도 있다는 점을 기억하세요.PingID— 로그인 경로에 PingID push가 구성·활성화되면, 사용자의 등록된 디바이스가 API 접근을 승인하거나 거부하는 푸시 알림을 받아요. PingID 사용자 이름은 호출자 신원의 별칭에서 파생돼요.
로그인 MFA 절차 (Login MFA procedure)
참고: Vault 내장 로그인 MFA 기능은 기본적으로 TOTP 패스코드의 무차별 대입으로부터 보호하지 않아요. 관련 로그인 및/또는 mfa 경로(예:
/sys/mfa/validate)에 클라이언트별 비율 제한(rate limits)을 적용할 것을 권장해요. 외부 MFA 방식(Duo,Ping,Okta)은 이미 구성 가능한 비율 제한을 제공할 수 있어요. 로그인 MFA 경로의 비율 제한은 Vault 1.10.1부터 기본적으로 시행돼요.
로그인 MFA는 인증 방식에 대한 추가 인증을 보호하도록 구성할 수 있어요. 로그인 MFA를 활성화하려면 MFA 메서드를 구성해야 해요. MFA 메서드를 구성하는 방법은 로그인 MFA API를 참고하세요. MFA 메서드가 구성되면 운영자는 반환된 고유 MFA 메서드 ID를 사용해 MFA 시행(enforcement)을 구성할 수 있어요. MFA 시행 구성을 구성하는 방법은 로그인 MFA 시행 API를 참고하세요. MFA는 엔티티, 엔티티 그룹, 특정 인증 방식 accessor, 또는 인증 방식 유형에 대해 시행할 수 있어요. MFA 시행 제한과 일치하는 로그인 요청은 인증되기 전에 추가 MFA 검증(예: 일회용 패스코드)을 받게 돼요.
MFA 검증 대상인 로그인 요청을 검증하는 방법은 두 가지가 있어요.
단일 단계 로그인 (Single-Phase login)
단일 단계 로그인에서 필요한 MFA 정보는 X-Vault-MFA 헤더를 사용해 로그인 요청에 포함돼요. 이 경우 MFA 검증은 로그인 요청의 일부로 수행돼요.
MFA 크레덴셜은 X-Vault-MFA HTTP 헤더에서 가져와요. Vault 1.13.0 이전에는 헤더 형식이 TOTP, Okta, PingID의 경우 mfa_method_id[:passcode]였고, Duo의 경우 mfa_method_id[:passcode=<passcode>]였어요. [] 안의 항목은 선택이에요. Vault 1.13.0부터 형식은 모든 지원 MFA 방식에 일관되며, 위 두 형식 중 하나를 사용할 수 있어요. 검증해야 할 MFA 방식이 여러 개면 사용자는 여러 X-Vault-MFA HTTP 헤더를 전달할 수 있어요.
샘플 요청
$ curl \
--header "X-Vault-Token: ..." \
--header "X-Vault-MFA: d16fd3c2-50de-0b9b-eed3-0301dadeca10:695452" \
http://127.0.0.1:8200/v1/auth/userpass/login/alice
MFA 방식이 패스코드를 요구하지 않으면 로그인 요청 MFA 헤더는 메서드 ID만 포함해요.
$ curl \
--header "X-Vault-Token: ..." \
--header "X-Vault-MFA: d16fd3c2-50de-0b9b-eed3-0301dadeca10" \
http://127.0.0.1:8200/v1/auth/userpass/login/alice
Vault 1.13.0부터 운영자는 MFA 방식에 이름을 구성할 수 있어요. 이 이름은 MFA 방식이 구성된 네임스페이스에서 고유해야 해요. MFA 방식 이름은 MFA 헤더에 사용할 수 있어요.
$ curl \
--header "X-Vault-Token: ..." \
--header "X-Vault-MFA: sample_mfa_method_name:695452" \
http://127.0.0.1:8200/v1/auth/userpass/login/alice
MFA 방식이 특정 네임스페이스에 구성된 경우 MFA 방식 이름에 네임스페이스 경로를 접두사로 붙여야 해요. 아래는 MFA 방식이 ns1에 구성된 예시예요.
$ curl \
--header "X-Vault-Token: ..." \
--header "X-Vault-MFA: ns1/sample_mfa_method_name:695452" \
http://127.0.0.1:8200/v1/auth/userpass/login/alice
-mfa CLI 플래그 또는 VAULT_MFA 환경 변수를 사용해 MFA 크레덴셜을 전달해요. 예를 들어:
- CLI 플래그:
-mfa "d16fd3c2-50de-0b9b-eed3-0301dadeca10:695452" - 환경 변수:
export VAULT_MFA="d16fd3c2-50de-0b9b-eed3-0301dadeca10:695452"
2단계 로그인 (Two-Phase login)
더 전통적이고 널리 사용되는 MFA 방식은 두 요청 메커니즘으로, 2단계 로그인 MFA라고도 해요. 2단계 로그인에서 X-Vault-MFA 헤더는 요청에 제공되지 않아요. 이 경우 일반 로그인 요청을 보낸 후, 사용자는 MFA 요구 사항이 포함된 인증 응답을 받아요. MFA 요구 사항에는 검증이 필요한 로그인 요청을 식별하는 MFA 요청 ID가 포함돼요. 또한 MFA 요구 사항에는 요청을 검증하는 데 사용할 MFA 유형, 해당 메서드 ID, MFA 방식이 패스코드를 사용하는지 여부를 보여 주는 불리언 값이 포함된 MFA 제약이 포함돼요. MFA 제약은 MFA 요구 사항에서 중첩 맵을 형성하며 로그인 요청과 일치하는 모든 MFA 시행을 나타내요. 아래 예시는 userpass 로그인에 대한 것이지만, 이는 MFA 검증으로 보호되는 어떤 인증 마운트의 로그인 응답에도 영향을 줄 수 있다는 점을 기억하세요.
샘플 2단계 로그인 응답
{
"request_id": "1044c151-13ea-1cf5-f6ed-000c42efd477",
"lease_id": "",
"lease_duration": 0,
"renewable": false,
"data": null,
"warnings": [
"A login request was issued that is subject to MFA validation. Please make sure to validate the login by sending another request to mfa/validate endpoint."
],
"auth": {
"client_token": "",
"accessor": "",
"policies": null,
"token_policies": null,
"identity_policies": null,
"metadata": null,
"orphan": false,
"entity_id": "",
"lease_duration": 0,
"renewable": false,
"mfa_requirement": {
"mfa_request_id": "d0c9eec7-6921-8cc0-be62-202b289ef163",
"mfa_constraints": {
"enforcementConfigUserpass": {
"any": [
{
"type": "totp",
"id": "820997b3-110e-c251-7e8b-ff4aa428a6e1",
"uses_passcode": true,
"name": "sample_mfa_method_name",
}
]
}
}
}
}
}
uses_passcode 불리언 값은 TOTP의 경우 항상 true, Okta와 PingID의 경우 false로 표시된다는 점을 기억하세요. Duo 방식의 경우 use_passcode 파라미터를 사용해 메서드 구성의 일부로 값을 구성할 수 있어요. Duo의 불리언 값을 구성하는 방법은 Duo API를 참고하세요.
MFA 제한 로그인 요청을 검증하려면 사용자가 MFA 요청 ID와 MFA 페이로드를 포함한 두 번째 요청을 validate 엔드포인트로 보내요. MFA 페이로드는 메서드 ID와 관련 크레덴셜의 맵을 포함해요. PingID, Okta, Duo 같은 구성된 MFA 방식이 패스코드를 요구하지 않으면 관련 크레덴셜은 빈 문자열 하나가 있는 목록일 거예요.
샘플 페이로드
{
"mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
"mfa_payload": {
"d16fd3c2-50de-0b9b-eed3-0301dadeca10": ["910201"]
}
}
MFA 방식이 네임스페이스에 구성된 경우, 네임스페이스 경로가 접두사로 붙은 MFA 방식 이름을 검증 페이로드에 사용할 수 있어요.
{
"mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7",
"mfa_payload": {
"ns1/sample_mfa_method_name": ["910201"]
}
}
샘플 요청
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/sys/mfa/validate
샘플 CLI 요청
사용자는 CLI write 명령으로도 로그인 요청을 검증할 수 있어요.
$ vault write sys/mfa/validate -format=json @payload.json
로그인 MFA용 대화형 CLI
Vault는 로그인 요청이 단일 MFA 방식 검증 대상일 때만 CLI로 인증 방식에 대화형으로 인증하는 것을 지원해요. 이 상황에서 MFA 방식이 패스코드를 사용하도록 구성되어 있으면, 일반 로그인 요청을 보낸 후 사용자에게 패스코드를 입력하라는 프롬프트가 표시돼요. MFA 검증에 성공하면 클라이언트 토큰이 반환돼요. PingID, Okta, Duo 같은 구성된 MFA 방식이 패스코드를 요구하지 않고 추가 요소를 검증하는 대역 외(out of band) 메커니즘이 있으면, 사용자에게 인증자 애플리케이션을 확인하라는 알림이 표시돼요. 이렇게 하면 사용자가 로그인 요청을 검증하기 위해 두 번째 요청을 별도로 보낼 필요가 없어요. 대화형 로그인 경험을 비활성화하려면 로그인 요청에 non-interactive 플래그를 전달해야 해요.
$ vault write -non-interactive sys/mfa/validate -format=json @payload.json
로그인 MFA를 시작하려면 로그인 MFA 튜토리얼을 참고하세요.
시간 기반 일회용 비밀번호 (TOTP)
LDAP 인증 방식에 TOTP를 시행하는 로그인 MFA 메서드를 활성화해요.
인증자 애플리케이션은 암호화 알고리즘 지원이 일관되지 않아요. 선호하는 인증자 앱이 지원하는 알고리즘을 조사해야 해요. TOTP MFA 메서드 구성 문서는 로그인 MFA TOTP 메서드가 지원하는 알고리즘을 나열해요.
다음 표는 알려진 인증자 애플리케이션과 암호화 알고리즘 호환성을 나열해요.
| 인증자 애플리케이션 | SHA256 | SHA1 |
|---|---|---|
| Google Authenticator Chrome 확장 | ❌ | ✅ |
| Google Authenticator 모바일 앱 | ✅ | ✅ |
| Yubico Authenticator for Desktop | ✅ | ✅ |
옵션 1: 자체 등록용 TOTP 구성하기
계정에 TOTP가 설정되지 않은 사용자에게 Vault GUI가 QR 코드를 프롬프트하게 하려면:
- TOTP 메서드 구성에서
enable_self_enrollment을true로 설정합니다.
$ vault write identity/mfa/method/totp \
generate=true \
issuer=Vault \
period=30 \
key_size=30 \
algorithm=SHA256 \
digits=6 \
enable_self_enrollment=true
- 활성화된 MFA 로그인 시행이 하나만 있는지 확인합니다. 시행 규칙에 여러 MFA 메서드를 연결할 수 있지만, 자체 등록을 허용하려면 한 번에 하나의 규칙만 활성화할 수 있어요.
옵션 2: 관리자 관리 등록용 TOTP 구성하기
로그인 MFA TOTP 메서드를 구성하고 결과 method_id를 기록합니다.
$ vault write identity/mfa/method/totp \
generate=true \
issuer=Vault \
period=30 \
key_size=30 \
algorithm=SHA256 \
digits=6
Vault는 성공적인 로그인 후 사용자에 대한 entity_id를 생성해요. TOTP method_id와 대상 사용자의 entity_id를 사용해 QR 코드를 생성해요.
$ vault write -field=barcode \
/identity/mfa/method/totp/admin-generate \
method_id=$TOTP_METHOD_ID entity_id=$ENTITY_ID \
| base64 -d > qr-code.png
로그인 MFA 시행 만들기
로그인 MFA 시행을 만들 때 사용할 LDAP 인증 방식 accessor를 캡처합니다.
$ vault auth list -format=json --detailed
이전 단계의 accessor와 method_id를 사용해 시행을 적용해요.
$ VAULT_TOKEN=root vault write /identity/mfa/login-enforcement/adtotp \
mfa_method_ids=$TOTP_METHOD_ID \
auth_method_accessors=$ACCESSOR
성공 출력 예시:
Success! Data written to: identity/mfa/login-enforcement/adtotp
LDAP 인증 방식으로 로그인하기
MFA 시행으로 로그인하면 다음과 같을 거예요.
$ vault login -method=ldap username=alice password='password!'
Enter the passphrase for methodID "01194a79-e2d9-c038-029d-79b0091cafd0" of type "totp":
TOTP 패스코드 검증 비율 제한
로그인 MFA 경로의 비율 제한은 Vault 1.10.1부터 기본적으로 시행돼요. 기본적으로 Vault는 5회의 연속 실패한 TOTP 패스코드 검증을 허용해요. 이 값은 TOTP 구성에 max_validation_attempts를 추가해 구성할 수도 있어요. 연속 실패한 TOTP 패스코드 검증 수가 구성된 값을 초과하면 사용자는 새 TOTP 패스코드를 사용할 수 있을 때까지 기다려야 해요.
더 알아보기 (Learn more)
- 로그인 MFA 설정에 대한 실습은 로그인 MFA 튜토리얼을 참고하세요.
- Vault 내장 로그인 MFA 전체 API는 MFA API 문서를 참고하세요.