배포 파이프라인으로 워크로드 아이덴티티 제휴 구성

이 가이드에서는 배포 파이프라인이 Google Cloud에 인증하도록 워크로드 아이덴티티 제휴를 사용하는 방법을 설명합니다.

사용 중인 CI/CD 시스템에 따라 배포 파이프라인에서 주변 환경별 사용자 인증 정보에 액세스할 수 있습니다. 예를 들면 다음과 같습니다.

Azure DevOps 파이프라인은 Microsoft Entra 워크로드 아이덴티티 제휴 서비스 연결을 사용하여 Azure DevOps 프로젝트를 고유하게 식별하는 ID 토큰을 가져올 수 있습니다.
GitHub Actions 워크플로는 워크플로와 저장소를 고유하게 식별하는 GitHub OIDC 토큰을 가져올 수 있습니다.
GitLab SaaS를 사용하면 CI/CD 작업이 작업 및 프로젝트, 환경, 저장소를 고유하게 식별하는 ID 토큰에 액세스할 수 있습니다.
Terraform Cloud은 작업공간과 환경을 고유하게 식별하는 OIDC 토큰을 Terraform 구성에 제공할 수 있습니다.

워크로드 아이덴티티 제휴를 사용하면 이러한 사용자 인증 정보를 사용하여 Google Cloud에 인증하도록 배포 파이프라인을 구성할 수 있습니다. 이 접근 방식을 사용하면 서비스 계정 키와 관련된 유지보수 및 보안 부담이 사라집니다.

시작하기 전에

인증 설정

Select the tab for how you plan to use the samples on this page:

Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Python

이 페이지의 Python 샘플을 로컬 개발 환경에서 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.

Install the Google Cloud CLI.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
If you're using a local shell, then create local authentication credentials for your user account:
```
gcloud auth application-default login
```
You don't need to do this if you're using Cloud Shell.

자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경 인증 설정을 참조하세요.

필요한 역할

워크로드 아이덴티티 제휴를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 워크로드 아이덴티티 풀 관리자(roles/iam.workloadIdentityPoolAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

또는 IAM 소유자(roles/owner) 기본 역할에는 ID 제휴를 구성하는 권한도 포함됩니다. 프로덕션 환경에서는 기본 역할을 부여하지 말아야 하지만 개발 환경 또는 테스트 환경에서는 부여해도 됩니다.

외부 IdP 준비

Azure Devops

Azure DevOps 파이프라인이 Google Cloud에 인증하도록 하려면 먼저 Azure Resource Manager에 대한 서비스 연결을 구성합니다. 이 연결을 통해 파이프라인은 ID 토큰을 획득한 후 Google Cloud 사용자 인증 정보로 교환할 수 있습니다.

Azure Resource Manager에 대해 서비스 연결을 만들려면 다음을 수행합니다.

Azure DevOps에서 프로젝트를 열고 프로젝트 설정으로 이동합니다.
파이프라인 > 서비스 연결로 이동합니다.
서비스 연결 만들기를 클릭합니다.
Azure Resource Manager를 선택합니다.
다음을 클릭합니다.
워크로드 아이덴티티 제휴(자동)를 선택합니다.
다음을 클릭합니다.
다음 설정을 구성합니다.
- 범위 수준: 구독을 선택합니다.
  
  서비스 연결을 사용하여 Azure 리소스에 액세스하지 않더라도 구독을 선택해야 합니다.
- 서비스 연결 이름: 이름(예: google-cloud)을 입력합니다.
저장을 클릭합니다.

이후 단계에서 서비스 연결의 발급기관 및 주체 식별자가 필요합니다. 이러한 세부정보를 조회하려면 다음 단계를 따르세요.

방금 만든 서비스 연결을 클릭합니다.
서비스 주 구성원 관리를 클릭합니다.
인증서 및 보안 비밀 > 제휴 사용자 인증 정보로 이동합니다.
제휴 사용자 인증 정보를 클릭합니다.
사용자 인증 정보 수정 페이지에서 다음 식별자를 찾습니다.
- 발급기관: Azure DevOps 조직을 고유하게 식별합니다.
- 제목 식별자: 서비스 연결을 고유하게 식별합니다.

Azure DevOps는 범위로 선택한 구독에 대한 액세스 권한을 새 서비스 연결과 연결된 서비스 주 구성원에 자동으로 부여합니다. 서비스 연결을 사용하여 Azure 리소스에 액세스할 계획이 없으므로 다음을 수행하여 이 액세스 권한을 취소할 수 있습니다.

Azure 포털에서 범위로 선택한 구독을 엽니다.
액세스 제어(IAM) > 역할 할당으로 이동합니다.
서비스 연결의 역할 할당을 찾아 삭제합니다.

GitHub Actions

GitHub 계정에서 구성을 변경할 필요가 없습니다.

GitHub 저장소를 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후에는 해당 저장소의 워크플로가 GitHub OIDC 토큰을 사용하여 단기 Google Cloud 사용자 인증 정보를 가져오도록 할 수 있습니다.

GitLab SaaS

GitLab 계정에서 구성을 변경할 필요가 없습니다.

GitLab 그룹을 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후 개별 CI/CD 작업에 워크로드 아이덴티티 제휴를 사용 설정할 수 있습니다.

Terraform Cloud

Terraform Cloud 계정에서 구성을 변경할 필요가 없습니다.

Terraform Cloud를 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후 개별 작업공간에 워크로드 아이덴티티 제휴를 사용 설정할 수 있습니다.

워크로드 아이덴티티 제휴 구성

각 GitHub 조직, GitLab 그룹, Terraform Cloud 조직에서 다음 단계를 수행해야 합니다.

워크로드 아이덴티티 제휴 구성을 시작하려면 다음을 수행합니다.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

전용 프로젝트를 사용하여 워크로드 아이덴티티 풀 및 공급업체를 관리

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

속성 매핑 정의

배포 파이프라인의 환경별 사용자 인증 정보는 여러 속성을 포함하며, Google Cloud에서 주체 식별자(google.subject)로 사용할 속성을 결정해야 합니다.

필요한 경우 추가 속성을 매핑할 수 있습니다. 그런 다음 리소스에 대한 액세스 권한을 부여할 때 이러한 추가 속성을 참조할 수 있습니다.

Azure Devops

Azure DevOps ID 토큰에는 서비스 연결의 주체 식별자가 포함된 sub 클레임이 포함되어 있습니다. 주체 식별자는 다음 형식을 사용합니다.

sc://ORGANIZATION/PROJECT/CONNECTION

다음 속성 매핑을 사용하여 이 식별자를 google.subject에 매핑합니다.

google.subject=assertion.sub

GitHub Actions

속성 매핑은 GitHub 작업 OIDC 토큰의 클레임을 사용할 수 있습니다. 이러한 토큰 클레임 키와 값은 GitHub에서 제어합니다. 최소한 GitHub 작업 OIDC 토큰 제목에 해당하는 google.subject를 assertion.sub에 매핑해야 합니다.

google.subject=assertion.sub

GitHub Actions OIDC 토큰 제목 값은 소스 이벤트에 따라 다를 수 있습니다. 다른 클레임 속성은 다음과 같습니다.

repository: 소유자 및 저장소 이름을 포함합니다(예: "google/guava").
repository_id: 고유 저장소 ID를 포함합니다(예: "20300177").
repository_owner: 사용자 이름이나 GitHub 조직의 이름일 수 있는 소유자를 포함합니다(예: "google").
repository_owner_id: 고유 소유자 ID를 포함합니다(예: "1342004").

이 목록은 가능한 클레임의 일부입니다. 전체 목록은 클레임 예시에 대한 GitHub 문서를 참조하세요. 속성 조건으로 또는 향후 principalSet 조건의 일부로 사용할 계획인 모든 클레임을 매핑해야 합니다.

GitLab SaaS

속성 매핑은 다음을 포함한 GitLab ID 토큰에 포함된 클레임을 소스 속성으로 사용할 수 있습니다.

sub: 프로젝트 이름 및 Git 참조(예: project_path:groupname/projectname:ref_type:branch:ref:main)
namespace_id: 고유 그룹 ID
project_id: 고유한 프로젝트 ID
user_id: 순 사용자 ID
environment: 작업이 적용되는 환경
ref_path: Git 참조(예: refs/heads/main)

다음 속성 매핑은 GitLab ID 토큰에서 google.subject를 sub 클레임으로 설정합니다. sub 클레임에는 프로젝트 이름과 Git 참조가 모두 포함되므로 이 매핑을 사용하면 저장소 및 브랜치별로 액세스를 제어할 수 있습니다.

google.subject=assertion.sub

저장소 및 브랜치별로 액세스를 제어하면 특정 브랜치(예: main)에서 다른 브랜치(예: 기능 브랜치)와 다른 리소스 액세스가 필요한 경우에 유용할 수 있습니다.

일부 경우에는 프로젝트 또는 그룹별로 액세스만 구별하면 충분할 수 있습니다. 따라서 다음 매핑에는 GitLab project_id 및 namespace_id가 포함된 두 가지 추가 속성이 포함됩니다.

google.subject=assertion.sub
attribute.project_id=assertion.project_id
attribute.namespace_id=assertion.namespace_id

Terraform Cloud

속성 매핑은 다음을 비롯하여 Terraform Cloud OIDC 토큰에 포함된 클레임을 사용할 수 있습니다.

terraform_organization_id: 조직의 고유 ID를 포함합니다(예: org-xxxxxxxxxxxxxxxx).
terraform_workspace_id: 작업공간의 고유 ID를 포함합니다(예: ws-xxxxxxxxxxxxxxxx).
terraform_workspace_name: 작업공간의 표시 이름을 포함합니다.
sub: 조직, 작업공간, 단계의 표시 이름을 포함합니다(예: organization:example-org:workspace:example-workspace:run_phase:apply).

다음 속성 매핑은 Terraform Cloud OIDC 토큰의 google.subject를 terraform_workspace_id 클레임으로 설정합니다.

google.subject=assertion.terraform_workspace_id

이 매핑을 사용하면 작업공간별로 Google Cloud 리소스에 대한 액세스를 제어할 수 있습니다.

속성 조건 정의

속성 조건은 어설션 속성 및 대상 속성을 확인할 수 있는 CEL 표현식입니다. 어설션 조건이 특정 사용자 인증 정보에 대해 true로 평가되면 해당 사용자 인증 정보가 수락됩니다. 그렇지 않으면 사용자 인증 정보가 거부됩니다. 모든 속성 조건 필드에 속성 매핑이 있어야 합니다.

Azure Devops

필요에 따라 속성 조건을 사용하여 특정 서비스 연결에 대한 액세스를 제한합니다. 예를 들어 다음 조건은 특정 Azure DevOps 프로젝트의 연결에 대한 액세스를 제한합니다.

assertion.sub.startsWith('sc://ORGANIZATION/PROJECT/')

다음을 바꿉니다.

ORGANIZATION: Azure DevOps 조직의 이름
PROJECT: Azure DevOps 프로젝트의 이름

GitHub Actions

다음 속성 조건을 사용하여 GitHub 조직에서 발급한 토큰에 대한 액세스를 제한합니다.

assertion.repository_owner=='ORGANIZATION'

ORGANIZATION을 GitHub 조직의 이름으로 바꿉니다.

필요에 따라 속성 조건을 확장하여 워크플로 또는 브랜치의 하위 집합에 대한 액세스를 제한합니다. 예를 들어 다음 조건은 Git 브랜치 main을 사용하는 워크플로에 대한 액세스를 제한합니다.

assertion.repository_owner=='ORGANIZATION' && assertion.ref=='refs/heads/main'

GitLab SaaS

다음 속성 조건을 사용하여 GitLab 그룹에서 발급한 토큰에 대한 액세스를 제한하세요.

assertion.namespace_id=='GROUP_ID'

GROUP_ID를 GitLab 그룹의 홈페이지에 표시되는 그룹 ID로 바꿉니다.

선택적으로 속성 조건을 확장하여 프로젝트, 분기 또는 환경의 하위 집합에 대한 액세스를 제한합니다. 예를 들어 다음 조건은 production 환경을 사용하는 작업에 대한 액세스를 제한합니다.

assertion.namespace_id=='GROUP_ID' && assertion.environment=='production'

Terraform Cloud

다음 속성 조건을 사용하여 Terraform Cloud 조직에서 발급한 토큰에 대한 액세스를 제한합니다.

assertion.terraform_organization_id=='ORGANIZATION_ID'

ORGANIZATION_ID를 조직의 고유 ID로 바꿉니다(예: org-xxxxxxxxxxxxxxxx). 필요에 따라 속성 조건을 확장하여 워크플로 또는 브랜치의 하위 집합에 대한 액세스를 제한합니다. 예를 들어 다음 속성 조건은 특정 작업공간에 대한 액세스를 제한합니다.

assertion.terraform_organization_id=='ORGANIZATION_ID' && terraform_workspace_id=='WORKSPACE_ID'

워크로드 아이덴티티 풀 및 공급업체 만들기

이제 워크로드 아이덴티티 풀과 공급업체를 만드는 데 필요한 모든 정보가 수집되었습니다.

콘솔

Google Cloud 콘솔에서 새 워크로드 공급업체 및 풀 페이지로 이동합니다.

새 워크로드 공급업체 및 풀로 이동
ID 풀 만들기에서 다음을 입력합니다.
- 이름: 풀의 이름입니다. 이 이름은 풀 ID로도 사용됩니다. 풀 ID는 나중에 변경할 수 없습니다.
- 설명: 풀의 목적을 설명하는 텍스트입니다.
계속을 클릭합니다.
공급업체 설정을 구성합니다.
Azure Devops
- 공급업체 선택: OpenID Connect(OIDC)
- 공급업체 이름: Azure DevOps 프로젝트의 이름 또는 커스텀 이름입니다.
- 공급업체 ID: Azure DevOps 프로젝트의 이름 또는 커스텀 ID입니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
- 발급기관 URL: 이전에 조회한 서비스 연결 발급기관입니다.
- 잠재고객: 허용된 잠재고객을 선택하고 다음 값을 붙여넣습니다.
```
api://AzureADTokenExchange
```
GitHub Actions
- 공급업체 선택: OpenID Connect(OIDC)
- 공급업체 이름: 공급업체의 이름입니다.
- 공급업체 ID: 공급업체의 ID입니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
- 발급기관 URL: https://token.actions.githubusercontent.com/
- 잠재고객: 기본 잠재고객입니다.
GitLab SaaS
- 공급업체 선택: OpenID Connect(OIDC)
- 공급업체 이름: 공급업체의 이름입니다.
- 공급업체 ID: 공급업체의 ID입니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
- 발급기관 URL: https://gitlab.com
- 잠재고객: 기본 잠재고객입니다.
Terraform Cloud
- 공급업체 선택: OpenID Connect(OIDC)
- 공급업체 이름: 공급업체의 이름입니다.
- 공급업체 ID: 공급업체의 ID입니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
- 발급기관 URL: https://app.terraform.io
- 잠재고객: 기본 잠재고객입니다.
계속을 클릭합니다.
공급업체 속성 구성에서 이전에 식별한 속성 매핑을 추가합니다.
속성 조건에서 이전에 식별한 속성 조건을 입력합니다.
저장을 클릭하여 워크로드 아이덴티티 풀과 공급업체를 만듭니다.

gcloud

새 워크로드 아이덴티티 풀을 만듭니다.
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
다음 값을 바꿉니다.
- POOL_ID: 풀의 고유 ID
- DISPLAY_NAME: 풀의 이름
- DESCRIPTION: 풀에 대한 설명. 이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.

워크로드 아이덴티티 풀 공급업체를 추가합니다.

Azure Devops

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

다음 값을 바꿉니다.

PROVIDER_ID: Azure DevOps 프로젝트의 이름 또는 공급업체의 커스텀 ID
POOL_ID: 풀의 ID
ISSUER: 이전에 조회한 서비스 연결 발급기관
MAPPINGS: 쉼표로 구분된 이전에 식별한 속성 매핑의 목록
CONDITIONS: 이전에 식별한 속성 조건

GitHub Actions

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://token.actions.githubusercontent.com/" \
    --allowed-audiences="api://AzureADTokenExchange" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

다음 값을 바꿉니다.

PROVIDER_ID: 공급업체의 고유 ID
POOL_ID: 풀의 ID
MAPPINGS: 쉼표로 구분된 이전에 식별한 속성 매핑의 목록
CONDITIONS: 이전에 식별한 속성 조건

GitLab SaaS

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://gitlab.com" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

다음 값을 바꿉니다.

PROVIDER_ID: 공급업체의 고유 ID
POOL_ID: 풀의 ID
MAPPINGS: 쉼표로 구분된 이전에 식별한 속성 매핑의 목록
CONDITIONS: 이전에 식별한 속성 조건

Terraform Cloud

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="https://app.terraform.io" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"

다음 값을 바꿉니다.

PROVIDER_ID: 공급업체의 고유 ID
POOL_ID: 풀의 ID
MAPPINGS: 이전에 식별한 속성 매핑의 쉼표로 구분된 목록
CONDITIONS: 이전에 식별한 속성 조건

워크로드 아이덴티티 공급업체에 대한 속성 조건 업데이트

이 섹션에서는 GitHub 조직, GitLab 그룹, Terraform 클라우드 조직에서 발행되는 토큰 액세스를 제한하도록 기존 워크로드 아이덴티티 풀 공급업체에서 속성 조건을 업데이트하는 방법을 설명합니다.

파이프라인의 권장 속성 조건을 찾으려면 속성 조건 정의를 참조하세요.

콘솔

Google Cloud 콘솔에서 워크로드 아이덴티티 풀 페이지로 이동합니다.

워크로드 아이덴티티 풀로 이동
공급업체가 포함된 워크로드 아이덴티티 풀을 찾은 후 풀의 노드 확장 아이콘을 클릭합니다.
수정하려는 워크로드 아이덴티티 풀 공급업체를 찾으려면 수정을 클릭합니다.
속성 조건에서 이전에 식별한 속성 조건을 입력합니다.
워크로드 아이덴티티 풀 및 공급업체를 업데이트하려면 저장을 클릭합니다.

gcloud

워크로드 아이덴티티 풀 공급업체를 업데이트하려면 다음 명령어를 실행합니다.

gcloud iam workload-identity-pools providers update-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --attribute-condition="CONDITIONS"

다음 값을 바꿉니다.

PROVIDER_ID: 공급업체의 고유 ID
POOL_ID: 풀의 ID
CONDITIONS: 이전에 식별한 속성 조건

배포 파이프라인 인증

각 GitHub Actions 워크플로 또는 Terraform Cloud 작업공간에서 다음 단계를 수행해야 합니다.

외부 워크로드가 Google Cloud 리소스에 액세스하도록 허용

이 가이드 뒷부분에 있는 안내를 완료하려면 이 섹션에 설명된 대로 서비스 계정 가장을 구성해야 합니다.

워크로드에 Google Cloud 리소스에 대한 액세스 권한을 제공하려면 주 구성원에게 직접 리소스에 대한 액세스 권한을 부여하는 것이 좋습니다. 이 경우 주 구성원은 제휴 사용자입니다. 일부 Google Cloud 제품에는 Google Cloud API 제한사항이 있습니다. 워크로드가 제한사항이 있는 API 엔드포인트를 호출하는 경우 대신 서비스 계정 가장을 사용할 수 있습니다. 이 경우 주 구성원은 ID 역할을 하는 Google Cloud 서비스 계정입니다. 서비스 계정에 리소스에 대한 액세스 권한을 부여합니다.

직접 리소스 액세스

Google Cloud 콘솔 또는 gcloud CLI를 사용하면 제휴 ID에 직접 리소스에 대한 액세스 권한을 부여할 수 있습니다.

콘솔

Google Cloud 콘솔을 사용하여 리소스에 대한 IAM 역할을 직접 부여하려면 리소스 페이지로 이동한 다음 역할을 부여해야 합니다. 다음 예시에서는 Cloud Storage 페이지로 이동하여 제휴 ID에 Cloud Storage 버킷에 대한 스토리지 객체 뷰어(roles/storage.objectViewer) 역할을 직접 부여하는 방법을 보여줍니다.

Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
버킷으로 이동
버킷 목록에서 역할을 부여하려는 버킷의 이름을 클릭합니다.
페이지 상단의 권한 탭을 선택합니다.
액세스 권한 부여 버튼을 클릭합니다.

주 구성원 추가 대화상자가 표시됩니다.
새 주 구성원 필드에 버킷에 액세스해야 하는 ID를 한 개 이상 입력합니다.
주체별
```
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
```
다음을 바꿉니다.
- PROJECT_NUMBER: 프로젝트 번호
- POOL_ID: 워크로드 풀 ID
- SUBJECT: IdP에서 매핑된 개별 주체(예: administrator@example.com)
그룹별
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
```
다음을 바꿉니다.
- PROJECT_NUMBER: 프로젝트 번호
- WORKLOAD_POOL_ID: 워크로드 풀 ID
- GROUP: IdP에서 매핑된 그룹(예: administrator-group@example.com)
속성별
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
```
다음을 바꿉니다.
- PROJECT_NUMBER: 프로젝트 번호
- WORKLOAD_POOL_ID: 워크로드 풀 ID
- ATTRIBUTE_NAME: IdP에서 매핑된 속성 중 하나
- ATTRIBUTE_VALUE: 속성의 값
역할 선택 드롭다운 메뉴에서 역할을 한 개 이상 선택합니다. 선택한 역할 및 부여되는 권한에 대한 간단한 설명이 창에 표시됩니다.
저장을 클릭합니다.

gcloud

gcloud CLI를 사용하여 프로젝트의 리소스에 대한 IAM 역할을 부여하려면 다음을 수행합니다.

리소스가 정의된 프로젝트의 프로젝트 번호를 가져옵니다.

gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)

리소스에 대한 액세스 권한을 부여합니다.

gcloud CLI를 사용하여 특정 기준을 충족하는 외부 ID에 워크로드 아이덴티티 사용자(roles/iam.workloadIdentityUser) 역할을 부여하려면 다음 명령어를 실행합니다.
주체별
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
```
그룹별
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
```
속성별
```
gcloud storage buckets add-iam-policy-binding BUCKET_ID \
    --role=roles/storage.objectViewer \
    --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
```
다음을 바꿉니다.
- BUCKET_ID: 액세스 권한을 부여할 버킷
- PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
- POOL_ID: 워크로드 아이덴티티 풀의 ID
- SUBJECT: google.subject에 매핑한 속성의 예상 값
- GROUP: google.groups에 매핑한 속성의 예상 값
- ATTRIBUTE_NAME: 속성 매핑의 커스텀 속성 이름
- ATTRIBUTE_VALUE: 속성 매핑의 커스텀 속성 값
IAM 허용 정책을 지원하는 모든 Google Cloud 리소스에 대한 역할을 부여할 수 있습니다.

참고: 구성원 식별자에 프로젝트 ID가 아닌 프로젝트 번호를 사용해야 합니다.

서비스 계정 가장

외부 워크로드의 서비스 계정을 만들려면 다음을 수행합니다.
1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
  Enable the APIs
2. 워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 가장 좋습니다.
  
  서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없습니다.
3. 외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.
4. 서비스 계정에 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 부여합니다.
5. 워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 좋습니다.
  
  서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없지만 서비스 계정이 포함된 프로젝트를 참조해야 합니다.
Google Cloud 콘솔 또는 gcloud CLI를 사용하여 서비스 계정 가장으로 제휴 ID에 액세스 권한을 부여하려면 다음을 수행합니다.
콘솔
Google Cloud 콘솔을 사용하여 서비스 계정으로 제휴 ID에 IAM 역할을 부여하려면 다음을 수행합니다.
1. 다음을 수행하여 가장할 ID 역할을 하는 서비스 계정을 만듭니다.
  1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
    Enable the APIs
  2. 워크로드의 ID를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 좋습니다.
    
    서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없지만 IAM 액세스 권한을 부여할 때 서비스 계정이 포함된 프로젝트를 참조해야 합니다.
  3. 외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.
2. 서비스 계정 가장을 사용하여 액세스 권한을 부여하려면 다음을 수행합니다.
  1. 워크로드 아이덴티티 풀 페이지로 이동합니다.
    
    워크로드 아이덴티티 풀로 이동
  2. 액세스 권한 부여를 선택합니다.
  3. 서비스 계정에 액세스 권한 부여 대화상자에서 서비스 계정 가장을 사용하여 액세스 권한 부여를 선택합니다.
  4. 서비스 계정 목록에서 가장하려는 외부 ID의 서비스 계정을 선택하고 다음을 수행합니다.
  5. 풀에서 서비스 계정을 가장할 수 있는 ID를 선택하려면 다음 작업 중 하나를 수행합니다.
    
    워크로드 아이덴티티 풀의 특정 ID만 서비스 계정을 가장하도록 허용하려면 필터와 일치하는 ID만을 선택합니다.
    
    속성 이름 목록에서 필터링할 속성을 선택합니다.
    
    속성 값 필드에서 속성의 예상 값을 입력합니다. 예를 들어 속성 매핑 google.subject=assertion.sub를 사용하는 경우 속성 이름을 subject로, 속성 값을 외부 ID 공급업체에서 발급한 토큰의 sub 클레임 값으로 설정합니다.
  6. 구성을 저장하려면 저장을 클릭한 다음 닫기를 클릭합니다.
gcloud

gcloud CLI를 사용하여 특정 기준을 충족하는 외부 ID에 워크로드 아이덴티티 사용자(roles/iam.workloadIdentityUser) 역할을 부여하려면 다음 명령어를 실행합니다.
주체별

gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
그룹별

gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
속성별

gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
다음을 바꿉니다.
- SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
- PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
- POOL_ID: 워크로드 아이덴티티 풀의 ID
- SUBJECT: google.subject에 매핑한 속성의 예상 값
- GROUP: google.groups에 매핑한 속성의 예상 값
- ATTRIBUTE_NAME: 속성 매핑의 커스텀 속성 이름
- ATTRIBUTE_VALUE: 속성 매핑의 커스텀 속성 값
참고: 구성원 식별자에 프로젝트 ID가 아닌 프로젝트 번호를 사용해야 합니다.

배포 파이프라인 구성

이 섹션에서는 배포 파이프라인에서 워크로드 아이덴티티 제휴를 사용하는 방법을 설명합니다. 이 섹션의 안내에서는 워크로드가 서비스 계정 가장을 사용하여 Google Cloud 리소스에 액세스한다고 가정합니다.

Azure Devops

azure-pipelines.yml 파일을 수정하고 작업 구성에 다음을 추가합니다.

variables:
- name: Azure.WorkloadIdentity.Connection
  value: CONNECTION
- name: GoogleCloud.WorkloadIdentity.ProjectNumber
  value: PROJECT_NUMBER
- name: GoogleCloud.WorkloadIdentity.Pool
  value: POOL_ID
- name: GoogleCloud.WorkloadIdentity.Provider
  value: PROVIDER_ID
- name: GoogleCloud.WorkloadIdentity.ServiceAccount
  value: SERVICE_ACCOUNT_EMAIL
- name: GOOGLE_APPLICATION_CREDENTIALS
  value: $(Pipeline.Workspace)/.workload_identity.wlconfig

steps:
  - task: AzureCLI@2
    inputs:
      connectedServiceNameARM: $(Azure.WorkloadIdentity.Connection)
      addSpnToEnvironment: true
      scriptType: 'bash'
      scriptLocation: 'inlineScript'
      inlineScript: |
        echo $idToken > $(Pipeline.Workspace)/.workload_identity.jwt
        cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
        {
          "type": "external_account",
          "audience": "//iam.googleapis.com/projects/$(GoogleCloud.WorkloadIdentity.ProjectNumber)/locations/global/workloadIdentityPools/$(GoogleCloud.WorkloadIdentity.Pool)/providers/$(GoogleCloud.WorkloadIdentity.Provider)",
          "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
          "token_url": "https://sts.googleapis.com/v1/token",
          "credential_source": {
            "file": "$(Pipeline.Workspace)/.workload_identity.jwt"
          },
          "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$(GoogleCloud.WorkloadIdentity.ServiceAccount):generateAccessToken"
        }
        EOF

다음 값을 바꿉니다.

CONNECTION: 서비스 연결의 이름
PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
POOL_ID: 워크로드 아이덴티티 풀의 ID
PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소

이 구성은 다음을 수행합니다.

AzureCLI 태스크를 사용하여 서비스 연결의 ID 토큰을 가져오고 idToken이라는 변수에 사용할 수 있도록 합니다.
ID 토큰을 .workload_identity.jwt라는 임시 파일에 저장합니다.
클라이언트 라이브러리가 .workload_identity.jwt에서 ID 토큰을 읽도록 지시하고 이를 사용해서 서비스 계정을 가장하는 사용자 인증 정보 구성 파일을 만듭니다.
사용자 인증 정보 구성 파일을 가리키도록 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 설정합니다.

GitHub Actions

google-github-actions/auth 작업을 사용하면 워크플로 실행 중에 사용자 인증 정보 구성 파일을 자동으로 생성할 수 있습니다. 그런 다음 terraform과 같은 클라이언트 라이브러리 및 도구는 이 사용자 인증 정보 구성 파일을 사용하여 Google 사용자 인증 정보를 자동으로 가져올 수 있습니다.

GitHub Actions YAML 파일을 수정하고 다음을 추가합니다.

다음 구성을 추가하여 GitHub ID 토큰을 가져오도록 작업을 허용합니다.
```
permissions:
  id-token: write
  contents: read
```

사용자 인증 정보 구성 파일을 만드는 단계를 추가합니다.

- id: 'auth'
  name: 'Authenticate to Google Cloud'
  uses: 'google-github-actions/auth@v1'
  with:
    create_credentials_file: true
    workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
    service_account: 'SERVICE_ACCOUNT_EMAIL'

다음 값을 바꿉니다.

PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
POOL_ID: 워크로드 아이덴티티 풀의 ID
PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소

다음 예시에서는 GitHub 작업을 구성합니다.

jobs:
  build:
    # Allow the job to fetch a GitHub ID token
    permissions:
      id-token: write
      contents: read

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - id: 'auth'
        name: 'Authenticate to Google Cloud'
        uses: 'google-github-actions/auth@v1'
        with:
          create_credentials_file: true
          workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID'
          service_account: 'SERVICE_ACCOUNT_EMAIL'

google-github-actions/auth 작업 사용에 대한 자세한 내용은 워크로드 아이덴티티 제휴 설정을 참조하세요.

GitLab SaaS

.gitlab-ci.yml 파일을 수정하고 작업 구성에 다음을 추가합니다.

job:
  variables:
    WORKLOAD_IDENTITY_PROJECT_NUMBER: PROJECT_NUMBER
    WORKLOAD_IDENTITY_POOL: POOL_ID
    WORKLOAD_IDENTITY_PROVIDER: PROVIDER_ID
    SERVICE_ACCOUNT: SERVICE_ACCOUNT_EMAIL
    GOOGLE_APPLICATION_CREDENTIALS: $CI_BUILDS_DIR/.workload_identity.wlconfig

  id_tokens:
    WORKLOAD_IDENTITY_TOKEN:
      aud: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

  script:
    - |-
      echo $WORKLOAD_IDENTITY_TOKEN > $CI_BUILDS_DIR/.workload_identity.jwt
      cat << EOF > $GOOGLE_APPLICATION_CREDENTIALS
      {
        "type": "external_account",
        "audience": "//iam.googleapis.com/projects/$WORKLOAD_IDENTITY_PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_IDENTITY_POOL/providers/$WORKLOAD_IDENTITY_PROVIDER",
        "subject_token_type": "urn:ietf:params:oauth:token-type:jwt",
        "token_url": "https://sts.googleapis.com/v1/token",
        "credential_source": {
          "file": "$CI_BUILDS_DIR/.workload_identity.jwt"
        },
        "service_account_impersonation_url": "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/$SERVICE_ACCOUNT:generateAccessToken"
      }
      EOF

다음 값을 바꿉니다.

PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
POOL_ID: 워크로드 아이덴티티 풀의 ID
PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소

이 구성은 다음을 수행합니다.

GitLab에 ID 토큰을 발급하도록 안내하고 WORKLOAD_IDENTITY_TOKEN이라는 환경 변수에서 사용할 수 있도록 합니다. ID 토큰은 워크로드 아이덴티티 풀 공급업체를 대상으로 사용합니다.
ID 토큰을 .workload_identity.jwt라는 임시 파일에 저장합니다.
클라이언트 라이브러리에 .workload_identity.jwt에서 ID 토큰을 읽도록 지시하고 이를 사용해서 서비스 계정을 가장하는 사용자 인증 정보 구성 파일을 만듭니다.
사용자 인증 정보 구성 파일을 가리키도록 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 설정합니다.

Terraform Cloud

서비스 계정 가장을 사용하여 Google Cloud에 인증하기 위해 워크로드 아이덴티티 제휴를 사용하도록 Terraform Cloud 작업공간을 구성합니다.

Terraform Cloud에서 작업공간을 열고 변수로 이동합니다.

다음 변수를 추가합니다.

변수 카테고리	키	값
환경 변수	`TFC_GCP_PROVIDER_AUTH`	`true`
환경 변수	`TFC_GCP_RUN_SERVICE_ACCOUNT_EMAIL`	서비스 계정의 이메일 주소(예: `terraform@my-project-123.iam.gserviceaccount.com`)
환경 변수	`TFC_GCP_PROJECT_NUMBER`	워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
환경 변수	`TFC_GCP_WORKLOAD_POOL_ID`	워크로드 아이덴티티 풀의 ID
환경 변수	`TFC_GCP_WORKLOAD_PROVIDER_ID`	워크로드 아이덴티티 풀 공급업체의 ID

원하는 경우 Terrform에서 plan 및 apply 단계에 다른 서비스 계정을 사용할 수 있도록 추가 환경 변수를 추가할 수 있습니다. 자세한 내용은 선택적 환경 변수를 참조하세요.

변수 목록에서 이전 단계에서 추가한 5개 변수에 대해 카테고리가 env로 설정되어 있는지 확인합니다.
Terraform 구성이 4.48.0 이상의 Google Cloud 제공업체 버전을 사용하는지 확인하고 필요한 경우 다음과 같이 업데이트하세요.
```
terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "~> 4.48.0"
    }
  }
}
```
소스 코드 저장소에 변경사항을 제출합니다.

다음 단계

워크로드 아이덴티티 제휴 자세히 알아보기
배포 파이프라인에서 워크로드 아이덴티티 제휴를 사용하기 위한 권장사항 알아보기
워크로드 아이덴티티 풀 및 공급업체 관리 방법 알아보기

배포 파이프라인으로 워크로드 아이덴티티 제휴 구성

시작하기 전에

인증 설정

Console

gcloud

Python

필요한 역할

외부 IdP 준비

Azure Devops

GitHub Actions

GitLab SaaS

Terraform Cloud

워크로드 아이덴티티 제휴 구성

속성 매핑 정의

Azure Devops

GitHub Actions

GitLab SaaS

Terraform Cloud

속성 조건 정의

Azure Devops

GitHub Actions

GitLab SaaS

Terraform Cloud

워크로드 아이덴티티 풀 및 공급업체 만들기

콘솔

Azure Devops

GitHub Actions

GitLab SaaS

Terraform Cloud

gcloud

Azure Devops

GitHub Actions

GitLab SaaS

Terraform Cloud

워크로드 아이덴티티 공급업체에 대한 속성 조건 업데이트

콘솔

gcloud

배포 파이프라인 인증

외부 워크로드가 Google Cloud 리소스에 액세스하도록 허용

직접 리소스 액세스

콘솔

주체별

그룹별

속성별

gcloud

주체별

그룹별

속성별

서비스 계정 가장

콘솔

gcloud

주체별

그룹별

속성별

배포 파이프라인 구성

Azure Devops

GitHub Actions

GitLab SaaS

Terraform Cloud

다음 단계