SAML 인증 설정하기

적절한 Vault Enterprise 라이선스 또는 HCP Vault Dedicated 클러스터가 필요해요.

사용자 지정 GUI 로그인을 지원해요.

이 방식은 Vault Enterprise GUI 사용자의 기본 또는 백업 로그인 방식으로 선택될 수 있어요. 자세한 내용은 사용자 지정 로그인 옵션 관리 가이드를 참고하세요.

saml 인증 방식은 SAML V2.0 아이덴티티 프로바이더 내의 신원을 사용해 Vault에 인증할 수 있게 해요. 인증은 웹 브라우저와의 상호작용이 필요하므로 사람 사용자에게 적합해요.

출처: 문서

본문

인증 (Authentication)

CLI 로그인은 기본적으로 /saml 경로를 사용해요. 이 인증 방식이 다른 경로에 활성화되었다면 CLI에서 -path=/my-path를 지정하세요.

$ vault login -method=saml role=admin

Complete the login via your SAML provider. Launching browser to:

    https://company.okta.com/app/vault/abc123eb9xnIfzlaf697/sso/saml?SAMLRequest=fJI9b9swEIZ3%2FwqBu0SJ%2FpBDRAZce4iBtDViN0MX40Sda...

CLI는 생성된 URL로 기본 브라우저를 열며, 사용자는 구성된 SAML 아이덴티티 프로바이더로 인증해야 해요. URL이 자동으로 열리지 않으면 브라우저에 수동으로 입력할 수 있어요.

CLI 로그인 동작은 다음 선택적 파라미터로 사용자 지정할 수 있어요.

skip_browser (기본값: false) — true로 설정하면 기본 브라우저 자동 실행을 건너뛰어요. 인증 흐름을 완료하려면 SAML 아이덴티티 프로바이더 URL을 브라우저에 수동으로 입력해야 해요.
abort_on_error (기본값: false) — true로 설정하면 기본 브라우저를 실행할 수 없을 때 CLI가 오류를 반환하고 0이 아닌 값으로 종료해요.

구성 (Configuration)

인증 방식은 사용자나 머신이 인증하기 전에 미리 구성되어야 해요. 이 단계들은 보통 운영자나 설정 관리 도구가 수행해요.

1. auth enable CLI 명령으로 SAML 인증 방식을 활성화합니다.

$ vault auth enable saml

2. /config 엔드포인트를 사용해 SAML 아이덴티티 프로바이더 구성을 저장하고 기본 역할을 설정합니다. SAML IdP와의 신뢰 관계는 그 Metadata 문서의 URL을 제공하거나:

$ vault write auth/saml/config \
   default_role="admin" \
   idp_metadata_url="https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata" \
   entity_id="https://my.vault/v1/auth/saml" \
   acs_urls="https://my.vault/v1/auth/saml/callback"

구성 Metadata를 수동으로 설정해 구성할 수 있어요.

$ vault write auth/saml/config \
   default_role="admin" \
   idp_sso_url="https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml" \
   idp_entity_id="https://www.okta.com/abc123eb9xnIfzlaf697" \
   idp_cert="@path/to/cert.pem" \
   entity_id="https://my.vault/v1/auth/saml" \
   acs_urls="https://my.vault/v1/auth/saml/callback"

참고: 구성에는 validate_response_signature와 validate_assertion_signature처럼 SAML 응답 서명을 검증하는 불리언 옵션이 있어요. 기본적으로는 응답 또는 assertion 중 하나 이상이 서명되었는지 검증돼요. IdP가 둘 다 서명을 허용한다면 권장되는 안전한 접근은 두 옵션을 모두 활성화하는 것이에요.

3. 이름 있는 역할을 만듭니다.

$ vault write auth/saml/role/admin \
    bound_subjects="*@hashicorp.com" \
    bound_subjects_type="glob" \
    token_policies="writer" \
    bound_attributes=group="admin" \
    ttl="1h"

이 역할은 @hashicorp.com 접미사가 있는 주체를 가진 admin 그룹의 사용자가 인증하도록 승인해요. 또한 결과 Vault 토큰에 1시간의 time-to-live와 writer 정책을 줘요.

구성 옵션의 전체 목록은 SAML API 문서를 참고하세요.

Assertion consumer service URLs

acs_urls 구성 파라미터는 사용자가 브라우저에서 구성된 SAML 아이덴티티 프로바이더로 인증한 후 SAML 응답이 전송될 위치를 결정해요.

Vault에 제공된 값은:

구성된 아이덴티티 프로바이더 내 SAML 애플리케이션의 구성된 값과 일치하거나 그 하위 집합이어야 해요.
인증 방식의 assertion consumer service callback API로 향해야 해요.

참고: assertion consumer service URL을 TLS로 보호하는 것이 강력히 권장되며 일부 아이덴티티 프로바이더에 의해 시행돼요. 구성된 assertion consumer service URL 중 하나라도 TLS로 보호되지 않으면 Vault에서 경고가 반환돼요.

복제를 위한 구성 (Configuration for replication)

단일 인증 방식 마운트가 Vault 복제 클러스터에서 사용되도록 지원하려면 acs_urls가 여러 값을 구성할 수 있어요. 예를 들어 프라이머리와 세컨더리 Vault 클러스터에서 SAML 인증을 지원하려면 다음 acs_urls 구성을 줄 수 있어요.

$ vault write auth/saml/config \
   acs_urls="https://primary.vault/v1/auth/saml/callback,https://secondary.vault/v1/auth/saml/callback"

Vault UI와 CLI는 통신하도록 구성된 클러스터에 적절한 assertion consumer service URL을 자동으로 요청해요. 즉 인증 흐름 전체가 대상 클러스터 안에 유지돼요.

네임스페이스를 위한 구성 (Configuration for namespaces)

SAML 인증 방식은 Vault 네임스페이스 안에서 사용할 수 있어요. Vault와 아이덴티티 프로바이더 양쪽에 구성된 assertion consumer service URL은 네임스페이스 경로 세그먼트를 포함해야 해요.

다음 표는 다른 네임스페이스 경로에 대해 assertion consumer service URL을 제공해요.

네임스페이스 경로	Assertion consumer service URL
`admin/`	`https://my.vault/v1/admin/auth/saml/callback`
`org/security/`	`https://my.vault/v1/org/security/auth/saml/callback`

바인딩 속성 (Bound attributes)

사용자가 인증된 후 인가 흐름은 bound_subjects와 bound_attributes가 역할에 구성된 기대 값과 일치하는지 검증해요. 이를 사용해 SAML 아이덴티티 프로바이더의 사용자 하위 집합으로 Vault 접근을 제한할 수 있어요.

예를 들어 bound_subjects=*@hashicorp.com과 bound_attributes=groups=support,engineering인 역할은 주체에 @hashicorp.com 접미사가 있고 support 또는 engineering 그룹 중 하나에 있는 사용자만 승인해요.

정확한 일치여야 하는지 *를 와일드카드로 해석할지 여부는 bound_subjects_type와 bound_attributes_type 파라미터로 제어할 수 있어요.

Microsoft 아이덴티티 플랫폼의 바인딩 속성

Microsoft 아이덴티티 플랫폼의 바인딩 속성은 그룹 멤버십 값과 함께 http://schemas.microsoft.com/ws/2008/06/identity/claims/groups를 속성 이름으로 요구해요. 예를 들어 bound_attributes=http://schemas.microsoft.com/ws/2008/06/identity/claims/groups="GROUP1_OBJECT_ID,GROUP2_OBJECT_ID"인 역할은 GROUP1_OBJECT_ID 또는 GROUP2_OBJECT_ID 그룹 중 하나에 있는 사용자만 승인해요.

Microsoft 아이덴티티 플랫폼의 SAML 토큰 클레임 참조에서 더 읽을 수 있어요.

API

SAML 인증 플러그인은 완전한 HTTP API를 제공해요. 자세한 내용은 SAML API 문서를 참고해 주세요.

Terraform

Vault Terraform 프로바이더로 SAML 인증 리소스를 프로그래밍 방식으로 관리할 수 있어요. 자세한 내용은 Terraform Registry 문서를 참고하세요.

더 알아보기 (Learn more)

SAML 인증 방식 전체 API는 SAML API 문서를 참고하세요.
SAML을 ADFS와 함께 구성하고 싶다면 SAML과 ADFS 문서를 참고하세요.