OIDC 인증에 ADFS 사용하기

OIDC 인증에 ADFS 사용하기

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

출처: 문서

본문

시작하기 전에 (Before you start)

  1. Vault v1.15.0+가 있어야 해요.
  2. Windows Server에서 ADFS를 실행 중이어야 해요.
  3. ADFS 인스턴스의 OIDC 클라이언트 시크릿이 있어야 해요.
  4. Vault 관리자 토큰을 알아야 해요. 유효한 관리자 토큰이 없으면 Vault UI 또는 Vault CLI로 새 토큰을 생성할 수 있어요.

1단계: Vault용 OIDC 인증 방식 활성화하기

  1. Vault 인스턴스 URL을 VAULT_ADDR 환경 변수에 저장합니다.
$ export VAULT_ADDR="<URL_FOR_YOUR_VAULT_INSTALLATION>"

예:

$ export VAULT_ADDR="https://myvault.example.com:8200"
  1. Vault 인스턴스 URL을 VAULT_TOKEN 환경 변수에 저장합니다.
$ export VAULT_TOKEN="<YOUR_VAULT_ACCESS_TOKEN>"

예:

$ export VAULT_TOKEN="XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
  1. Vault Enterprise 또는 Vault HCP를 사용한다면, OIDC 플러그인이 마운트된 네임스페이스를 VAULT_NAMESPACE 환경 변수에 설정합니다.
$ export VAULT_NAMESPACE="<OIDC_NAMESPACE>"

예:

$ export VAULT_NAMESPACE="oidc-ns"
  1. OIDC 인증 플러그인을 활성화합니다.
$ vault auth enable -path=<YOUR_OIDC_MOUNT_PATH> oidc

예:

$ vault auth enable -path=/adfs oidc

2단계: ADFS에서 새 애플리케이션 그룹 만들기

클라이언트 ID 저장: 새 애플리케이션 그룹에 대해 ADFS가 제공하는 32자 클라이언트 식별자(예: d879d6fb-d2de-4596-b39c-191b2f83c03f)를 기록해 두세요. Vault용 OIDC 플러그인을 구성하려면 클라이언트 ID가 필요해요.

  1. Windows Server UI를 엽니다.
  2. Server Manager 화면으로 가서 Tools를 클릭합니다.
  3. AD FS Management를 선택합니다.
  4. Application Groups을 마우스 오른쪽 클릭하고 **Add Application Group...**을 선택합니다.
  5. 다음 정보로 새 애플리케이션 그룹을 만들라는 프롬프트를 따릅니다.
    • Name: Vault
    • Description: 애플리케이션 그룹의 목적을 설명하는 짧은 설명. 예: "Enable access to Vault"
    • Application type: Server application
    • Redirect URI: 웹 리다이렉트용 OIDC 플러그인의 콜백 URL과 Vault CLI 리다이렉트용 로컬 OIDC 콜백 URL을 추가합니다. 예: https://myvault.example.com:8200/ui/vault/auth/<YOUR_OIDC_MOUNT_PATH>/oidc/callback 및 http://localhost:8250/oidc/callback.
  6. Generate a shared secret 상자를 선택하고 시크릿 문자열을 저장합니다.
  7. 닫기 전에 애플리케이션 그룹 세부 사항과 정보가 올바른지 확인합니다.

3단계: ADFS에서 웹훅 구성하기

  1. ADFS 관리 화면에서 Vault 애플리케이션 그룹을 엽니다.
  2. **Add application...**을 클릭합니다.
  3. Web API를 선택합니다.
  4. 다음 정보로 새 웹훅을 구성하라는 프롬프트를 따릅니다.
    • Identifier: 애플리케이션 그룹의 클라이언트 ID
    • Access control policy: 기존 정책 또는 Permit everyone 선택
    • allatclaims, email, openid, profile 활성화
  5. Vault 애플리케이션 그룹의 속성 화면에서 새 웹훅(Vault - Web API)을 선택합니다.
  6. Issuance Transform Rules 탭을 엽니다.
  7. **Add Rule...**을 클릭하고 다음 정보로 새 인증 규칙을 만들라는 프롬프트를 따릅니다.
    • Send LDAP Attributes as Claims 선택
    • Rule name: LDAP Group
    • Attribute store: Active Directory
    • LDAP attribute: Token-Groups - Unqualified Names
    • Outgoing claim type: Group

4단계: Vault에서 기본 ADFS 역할 만들기

vault write CLI 명령으로 ADFS로 인증하는 사용자의 기본 역할을 만듭니다. 여기서:

  • ADFS_APPLICATION_GROUP_CLIENT_ID는 ADFS가 제공한 클라이언트 ID.
  • YOUR_OIDC_MOUNT_PATH는 OIDC 플러그인의 마운트 경로. 예: adfs.
  • ADFS_ROLE은 역할 이름. 예: adfs-default.
$ vault write auth/<YOUR_OIDC_MOUNT_PATH>/role/<ADFS_ROLE> \
  bound_audiences="<ADFS_APPLICATION_GROUP_CLIENT_ID>" \
  allowed_redirect_uris="${VAULT_ADDR}/ui/vault/auth/<YOUR_OIDC_MOUNT_PATH>/oidc/callback" \
  allowed_redirect_uris="http://localhost:8250/oidc/callback" \
  user_claim="upn" groups_claim="group" token_policies="default"

팁: user_claim에 upn 값을 사용하면 Vault가 ADFS 인증 토큰과 연결된 사용자 이메일을 엔티티 별칭으로 간주해요.

5단계: OIDC 플러그인 구성하기

ADFS 애플리케이션 그룹의 클라이언트 ID와 공유 시크릿으로 OIDC 플러그인 구성을 마칩니다.

vault write CLI 명령으로 OIDC 플러그인의 구성 세부 사항을 저장합니다. 여기서:

  • ADFS_URL은 ADFS 인스턴스의 discovery URL. 예: https://adfs.example.com/adfs
  • ADFS_APPLICATION_GROUP_CLIENT_ID는 ADFS가 제공한 클라이언트 ID.
  • YOUR_OIDC_MOUNT_PATH는 OIDC 플러그인의 마운트 경로. 예: adfs.
  • ADFS_APPLICATION_GROUP_SECRET은 ADFS 애플리케이션 그룹의 공유 시크릿.
  • ADFS_ROLE은 역할 이름. 예: adfs-default.
$ vault write auth/<YOUR_OIDC_MOUNT_PATH>/config \
  oidc_discovery_url="<ADFS_URL>" \
  oidc_client_id="<ADFS_APPLICATION_GROUP_CLIENT_ID>" \
  oidc_client_secret="<ADFS_APPLICATION_GROUP_SECRET>" \
  default_role="<ADFS_ROLE>"

선택 사항: Active Directory 그룹을 Vault에 연결하기

  1. Vault에서 ADFS용 KV 시크릿 엔진을 활성화합니다.
$ vault secrets enable -path=<ADFS_KV_PLUGIN_PATH> kv-v2

예:

$ vault secrets enable -path=adfs-kv kv-v2
  1. ADFS용 KV 플러그인에 대한 읽기 전용 정책을 만듭니다.
$ vault policy write <RO_ADFS_POLICY_NAME> - << EOF
# Read and list policy for the ADFS KV mount
path "<ADFS_KV_PLUGIN_PATH>/*" {
  capabilities = ["read", "list"]
}
EOF

예:

$ vault policy write read-adfs-test - << EOF
# Read and list policy for the ADFS KV mount
path "adfs-kv/*" {
  capabilities = ["read", "list"]
}
EOF
  1. KV 플러그인에 테스트 값을 씁니다.
$ vault kv put <ADFS_KV_PLUGIN_PATH>/test test_key="test value"

예:

$ vault kv put adfs-kv/test test_key="test value"

이제 Vault 그룹을 만들고 AD 그룹에 연결할 수 있어요.

  1. Vault에서 외부 그룹을 만들고 그룹 ID를 group_id.txt 파일에 저장합니다.
$ vault write \
  -format=json \
  identity/group name="<YOUR_NEW_VAULT_GROUP_NAME>" \
  policies="<RO_ADFS_POLICY_NAME>" \
  type="external" | jq -r ".data.id" > group_id.txt
  1. ADFS 인증 방식의 마운트 accessor를 검색해 accessor_adfs.txt 파일에 저장합니다.
$ vault auth list -format=json | \
  jq -r '.["<YOUR_OIDC_MOUNT_PATH>/"].accessor' > \
  accessor_adfs.txt
  1. 그룹 별칭을 만듭니다.
$ vault write identity/group-alias \
  name="<YOUR_EXISTING_AD_GROUP>"  \
  mount_accessor=$(cat accessor_adfs.txt) \
  canonical_id="$(cat group_id.txt)"
  1. YOUR_EXISTING_AD_GROUP의 구성원인 AD 사용자로 Vault에 로그인합니다.
  2. KV 플러그인에서 테스트 값을 읽습니다.
$ vault kv list -mount=secret <ADFS_KV_PLUGIN_PATH>/test

더 알아보기 (Learn more)

  • Vault JWT/OIDC 인증 방식에 대한 자세한 내용은 JWT 인증 방식 문서를 참고하세요.
  • Active Directory Federation Services에 대한 자세한 내용은 Microsoft 문서를 참고하세요.