SAML에 Active Directory Federation Services 사용하기

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

Active Directory Federation Services(AD FS)와 함께 동작하도록 Vault 인스턴스를 구성하고, SAML 인증에 AD FS 계정을 사용해요.

출처: 문서

본문

시작하기 전에 (Before you start)

Vault Enterprise 또는 HCP Vault v1.15.5+가 있어야 해요.
Windows Server에서 AD FS를 실행 중이어야 해요.
SAML 플러그인이 활성화되어 있어야 해요.
Vault 관리자 토큰이 있어야 해요. 유효한 관리자 토큰이 없다면 Vault GUI에서 또는 Vault CLI로 vault token create를 사용해 새 토큰을 생성할 수 있어요.

1단계: Vault에 SAML 인증 방식 활성화하기

VAULT_ADDR 환경 변수를 Vault 인스턴스 URL로 설정해요. 예:

$ export VAULT_ADDR="https://myvault.example.com:8200"

VAULT_TOKEN 환경 변수를 관리자 토큰으로 설정해요:

$ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

SAML 플러그인을 활성화해요. 특정 네임스페이스 아래에 활성화하려면 -namespace 플래그를 사용해요. 예:

$ vault -namespace=ns_admin auth enable saml

2단계: AD에 새 신뢰 당사자 트러스트(Relying Party Trust) 만들기

Windows Server UI를 엽니다.
Server Manager 화면으로 갑니다.
Tools를 클릭하고 AD FS Management를 선택합니다.
Relying Party Trusts를 우클릭하고 **Add Relying Party Trust...**를 선택합니다.
프롬프트에 따라 다음 설정으로 새 파티 트러스트를 만듭니다:

옵션	설정
Claims aware	체크
Enter data about relying party manually	체크
Display name	`"Vault"`
Certificates	None
Enable support for the SAML 2.0 WebSSO protocol	체크
SAML callback URL	SAML 플러그인의 콜백 엔드포인트
Relying party trust identifier	의미 있는 고유 문자열. 예: `"VaultIdentifier"`
Access control policy	유효한 정책 또는 `Permit everyone`
Configure claims issuance policy for this application	체크

팁: SAML 플러그인의 콜백 엔드포인트는 다음과 같아요.

https://${VAULT_ADDRESS}/v1/<NAMESPACE>/<MOUNT_PATH>/auth/<PLUGIN_NAME>/callback

예를 들어 ns_admin 네임스페이스의 org/security 경로에 플러그인을 마운트했다면 콜백 엔드포인트 URL은:

https://${VAULT_ADDRESS}/v1/ns_admin/auth/org/security/saml/callback

3단계: AD에서 클레임 발급 정책 구성하기

Windows Server UI를 엽니다.
Server Manager 화면으로 갑니다.
Tools를 클릭하고 AD FS Management를 선택합니다.
새 Relying Party Trust 항목을 우클릭하고 **Edit Claim Issuance Policy...**를 선택합니다.
**Add Rule...**을 클릭하고 프롬프트에 따라 다음 설정으로 새 Transform Claim Rule을 만듭니다:

옵션	설정
Send LDAP Attributes as Claims	선택
Rule name	의미 있는 문자열 (예: `"Vault SAML Claims"`)
Attribute store	`Active Directory`

LDAP 속성 배열을 다음 설정으로 완성합니다:

LDAP 속성	나가는 클레임 유형
`E-Mail-Addresses`	`Name ID`
`E-Mail-Addresses`	`E-Mail Address`
`Token-Groups - Unqualified Names`	`groups` 또는 `Group`

4단계: AD에서 SAML 서명 업데이트하기

Windows 서버에서 PowerShell 터미널을 엽니다.
신뢰 당사자 트러스트 식별자의 SAML 서명을 false로 설정합니다:

Set-ADFSRelyingPartyTrust `
 -TargetName "<RELYING_PARTY_TRUST_IDENTIFIER>" `
 -SignedSamlRequestsRequired $false

예:

Set-ADFSRelyingPartyTrust `
 -TargetName "MyVaultIdentifier" `
 -SignedSamlRequestsRequired $false

5단계: Vault에 기본 AD FS 역할 만들기

Vault CLI로 AD FS로 인증하는 사용자를 위한 기본 역할을 만듭니다. 여기서:

SAML_PLUGIN_PATH는 SAML 플러그인의 전체 경로(<NAMESPACE>/MOUNT_PATH/NAME)예요.
VAULT_ROLE은 새 AD FS 역할의 이름이에요. 예: adfs-default.
DOMAIN_LIST는 Active Directory의 대상 도메인 쉼표 구분 목록이에요. 예: *@example.com,*@ext.example.com.
GROUP_ATTRIBUTES_REF는:
- LDAP 토큰 그룹이 groups라면 groups- LDAP 토큰 그룹이 Group이라면 http://schemas.xmlsoap.org/claims/Group`
AD_GROUP_LIST는 SAML로 인증할 Active Directory 그룹의 쉼표 구분 목록이에요. 예: VaultAdmin,VaultUser.

$ vault write <SAML_PLUGIN_PATH>/role/<VAULT_ROLE>  \
    bound_subjects="<DOMAIN_LIST>"                  \
    bound_subjects_type="glob"                      \
    groups_attribute=<GROUP_ATTRIBUTES_REF>         \
    bound_attributes=groups="<AD_GROUP_LIST>"       \
    token_policies="default"                        \
    ttl="1h"

예:

$ vault write auth/saml/role/adfs-default             \
    bound_subjects="*@example.com,*@ext.example.com"  \
    bound_subjects_type="glob"                        \
    groups_attribute=groups                           \
    bound_attributes=groups="VaultAdmin,VaultUser"    \
    token_policies="default"                          \
    ttl="1h"

6단계: Vault에서 SAML 플러그인 구성하기

Vault CLI로 SAML 플러그인 구성을 마무리합니다. 여기서:

SAML_PLUGIN_PATH는 SAML 플러그인의 전체 경로예요: <NAMESPACE>/auth/<MOUNT_PATH>/<PLUGIN_NAME>.
VAULT_ROLE은 Vault의 새 AD FS 역할 이름이에요.
TRUST_IDENTIFIER는 AD FS의 새 신뢰 당사자 트러스트 ID예요.
SAML_CALLBACK_URL은 SAML 플러그인의 콜백 엔드포인트예요: http://${VAULT_ADDR}/<NAMESPACE>/auth/<MOUNT_PATH>/<PLUGIN_NAME>/callback.
ADFS_URL은 AD FS 인스턴스의 디스커버리 URL이에요.
METADATA_FILE_PATH는 AD FS 인스턴스의 페더레이션 메타데이터 파일 경로예요.

$ vault write <SAML_PLUGIN_PATH>/config \
    default_role="<VAULT_ROLE>"         \
    entity_id="<TRUST_IDENTIFIER>"      \
    acs_urls="<SAML_CALLBACK_URL>       \
    idp_metadata_url="<ADFS_URL>/<METADATA_FILE_PATH>"

예:

$ vault write ns_admin/auth/org/security/saml/config                    \
  default_role="adfs-default"                                           \
  entity_id="MyVaultIdentifier"                                         \
  acs_urls="${VAULT_ADDR}/v1/ns_admin/auth/org/security/saml/callback"  \
  idp_metadata_url="https://adfs.example.com/metadata/2007-06/federationmetadata.xml"

다음 단계 (Next steps)

더 알아보기 (Learn more)

SAML 인증 방식에 대한 일반 가이드는 SAML 인증 설정하기를 참고하세요.
AD 그룹을 Vault 정책에 연결하는 방법은 Active Directory SAML 그룹을 Vault에 연결하기를 참고하세요.
AD FS 문제 해결은 AD FS 문제 해결을 참고하세요.