GCP와 워크로드 아이덴티티 페더레이션

GCP와 워크로드 아이덴티티 페더레이션 (Federate workload identity with GCP)

GCP 워크로드에서 인증하도록 워크로드 아이덴티티 페더레이션을 설정하는 방법을 설명해 드릴게요. 인증된 워크로드는 HCP 서비스 주체 키를 전혀 저장하지 않고 HCP 서비스와 상호작용할 수 있어요.

출처: 문서

본문

사전 요구 사항

GCP용 워크로드 아이덴티티 제공자를 구성하기 전에 다음 단계를 완료해야 해요.

• HCP 프로젝트에 대한 Admin 역할이 있어야 해요.
• 원하는 프로젝트에 서비스 주체를 만들고 워크로드가 필요로 하는 HCP 리소스에 대한 접근 권한을 부여해요.
• HCP로의 접근을 페더레이션할 GCP 계정에 대한 접근 권한이 있어야 해요.
• 원하는 구성 워크플로에 따라 HCP CLI를 설치하거나 HCP Terraform Provider를 사용해요.

GCP 구성 사전 요구 사항

GCP 워크로드와 아이덴티티 페더레이션하려면 GCP 프로젝트에 Service Account를 만들고 만든 VM이나 Cloud Run Service 같은 워크로드에 연결해야 해요. 워크로드 아이덴티티 제공자가 Service Account를 신뢰하도록 구성하면 GCP 워크로드는 GCP 액세스 토큰을 가져와 HCP 액세스 토큰으로 교환할 수 있어요.

워크로드 아이덴티티 페더레이션을 위해 GCP 환경을 준비하려면 다음 단계를 완료해요.

1. GCP Service Account 생성. 만든 뒤 "Service account details" 페이지로 이동해 Service Account의 Unique ID를 기록해 두세요. 워크로드 아이덴티티 제공자를 구성할 때 이 값이 필요해요.
2. 관리 아이덴티티를 애플리케이션이 실행되는 가상 머신이나 다른 리소스에 할당해요.

GCP용 외부 워크로드 아이덴티티 제공자 구성

GCP용 HCP 워크로드 아이덴티티 제공자를 만들려면 다음 구성 값을 제공해야 해요.

• 만든 Service Account의 Unique ID.
• 조건부 접근 문.

조건부 접근 문 (Conditional access statement)

워크로드 아이덴티티를 페더레이션할 때 요구 사항 중 하나가 조건부 접근 문이에요. 이 문은 아이덴티티 클레임에 접근할 수 있고 어떤 외부 아이덴티티가 허용되는지 제한하는 불리언 표현식이에요.

GCP 토큰을 HCP 접근 권한으로 교환할 때, 조건부 접근 문은 jwt_claims. 접두어로 토큰의 모든 클레임에 접근할 수 있어요. 대부분의 시나리오에서는 워크로드에 연결된 Service Account의 Unique ID와 일치하는 sub 클레임을 사용하는 것을 권장해요. 자세한 내용은 GCP 문서의 access token 클레임 레퍼런스를 참고하세요.

다음 예시 조건부 접근 문은 Unique ID가 106356042740441904560인 Service Account가 할당된 GCP 워크로드에 대해서만 HCP 서비스 접근을 제한해요.

`jwt_claims.sub == "106356042740441904560"`

참조할 수 있는 클레임 전체 목록을 보려면 다음 단계를 완료해요.

1. Service Account가 할당된 VM 생성.
2. VM에 SSH 접속.
3. 메타데이터 서버를 사용해 아이덴티티 토큰 획득. 다음 예시는 AUD 클레임에 hcp를, format에 full을 지정해요.

curl -H "Metadata-Flavor: Google" \
'http://metadata/computeMetadata/v1/instance/service-accounts/default/identity?audience=hcp&format=full'

클레임을 보려면 액세스 토큰을 복사해 브라우저 기반 토큰 디코더에 붙여 넣으세요. 나열된 클레임은 조건부 접근 문을 만들 때 사용할 수 있는 값이에요.

워크로드 아이덴티티 제공자 만들기

필요한 정보를 정리한 뒤 GCP용 워크로드 아이덴티티 제공자를 만들어요.

HCP CLI / Terraform

hcp iam workload-identity-providers create-oidc 명령을 사용해요.

$ hcp iam workload-identity-providers create-oidc <PROVIDER_NAME> \
  --service-principal=<SP_RESOURCE_NAME> \
  --issuer=https://accounts.google.com \
  --conditional-access=<CONDITION> \
  --description=<DESCRIPTION>

이 명령에는 HCP와 GCP 계정에 특정한 다음 정보가 필요해요.

• <PROVIDER_NAME>: 만들 워크로드 아이덴티티 제공자의 이름.
• <SP_RESOURCE_NAME>: iam/project/<PROJECT_ID>/service-principal/<NAME> 형식의 서비스 주체 리소스 이름.
• <CONDITION>: 지정된 GCP 워크로드에 대한 접근을 제한하는 조건부 접근 문.
• <DESCRIPTION>: 프로바이더에 대한 선택적인 설명.

다음 예시는 gcp-example이라는 워크로드 아이덴티티 제공자를 만들어요. 이 제공자는 JWT 토큰이 106356042740441904560을 sub 클레임으로 갖도록 요구해 외부 워크로드 접근을 제한하도록 HCP를 구성해요. HCP 서비스에 대한 접근 권한을 부여받은 워크로드는 my-app-runtime 서비스 주체를 사용해요.

$ hcp iam workload-identity-providers create-oidc gcp-example \
  --service-principal=iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime \
  --issuer=https://accounts.google.com \
  --conditional-access='jwt_claims.sub == "106356042740441904560"' \
  --description="Allow my-app Service Account on GCP to act as my-app-runtime service principal"

hcp_iam_workload_identity_provider 리소스를 사용해요.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "workload_sp" {
  name = "my-app-runtime"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "gcp-example"
  service_principal = hcp_service_principal.workload_sp.resource_name
  description       = "Allow my-app Service Account on GCP to act as my-app-runtime service principal"

  oidc {
    issuer_uri = "https://accounts.google.com"
  }

  conditional_access = "<CONDITION>"
}

이 구성에는 GCP 계정에 특정한 다음 정보가 필요해요.

• <CONDITION>: 지정된 GCP 워크로드에 대한 접근을 제한하는 조건부 접근 문.

다음 예시는 gcp-example이라는 워크로드 아이덴티티 제공자를 만들어요. 이 제공자는 JWT 토큰이 106356042740441904560을 sub 클레임으로 갖도록 요구해 외부 워크로드 접근을 제한하도록 HCP를 구성해요. HCP 서비스에 대한 접근 권한을 부여받은 워크로드는 my-app-runtime 서비스 주체를 사용해요.

# Replace with an existing service principal if created ahead of time.
resource "hcp_service_principal" "workload_sp" {
  name = "my-app-runtime"
}

resource "hcp_iam_workload_identity_provider" "example" {
  name              = "gcp-example"
  service_principal = hcp_service_principal.workload_sp.resource_name
  description       = "Allow my-app Service Account on GCP to act as my-app-runtime service principal"

  oidc {
    issuer_uri = "https://accounts.google.com"
  }

  conditional_access = "jwt_claims.sub == `106356042740441904560`"
}

워크로드의 자격 증명 인증

HCP CLI, HCP Terraform Provider, HCP Go SDK를 사용해 외부 자격 증명을 자동으로 가져와 HCP 액세스 토큰으로 교환할 수 있어요. 이 과정은 외부 자격 증명을 얻는 데 필요한 정보와 교환할 워크로드 아이덴티티 제공자를 포함하는 자격 증명 파일을 사용해요.

자세한 내용은 credential files 문서를 참고하세요.

GCP용 자격 증명 파일 만들기

hcp iam workload-identity-providers create-cred-file 명령을 사용해요.

$ hcp iam workload-identity-providers create-cred-file <PROVIDER_NAME> \
  --gcp \
  --output-file=credentials.json

이 명령에는 HCP 계정에 특정한 다음 정보가 필요해요.

• <PROVIDER_NAME>: iam/project/<PROJECT_ID>/service-principal/<SP_NAME>/workload-identity-provider/<PROVIDER_NAME> 형식으로 자격 증명을 교환할 워크로드 아이덴티티 제공자의 이름.

다음 예시는 my-app-runtime 서비스 주체와 연결된 gcp-example 제공자를 사용해 credentials.json 파일을 만들어요.

$ hcp iam workload-identity-providers create-cred-file \
  iam/project/dcffbc8c-0873-4acc-bf96-4c79a4c3fd1a/service-principal/my-app-runtime/workload-identity-provider/gcp-example \
  --gcp \
  --output-file=credentials.json

자격 증명 파일이 런타임 환경에 존재하는지 확인해 주세요. 자격 증명 파일에는 시크릿 값이 없으므로 VM 이미지에 저장할 수 있어요. 또는 런타임에 생성할 수도 있어요.

자격 증명 파일로 인증하려면 HCP CLI, HCP Terraform Provider, 또는 HCP Go SDK를 사용할 수 있어요. 자세한 내용은 자격 증명 파일로 인증하기 문서를 참고하세요.

더 알아보기 (Learn more)

• 워크로드 아이덴티티 페더레이션 — 워크로드 아이덴티티 페더레이션의 개요와 동작 방식을 확인해 보세요.
• 조건부 접근 문 — 조건부 접근 문을 작성하고 형식화하는 방법을 알아보세요.
• Azure 제공자 구성 — Azure 워크로드를 연결하는 방법을 확인해 보세요.
• AWS 제공자 구성 — AWS 워크로드를 연결하는 방법을 알아보세요.