구글 클라우드 워크로드 아이덴티티 페더레이션 및 IAM 정책

Tier: Free, Premium, Ultimate Offering: GitLab.com

도입됨 GitLab 16.10에서 google_cloud_support_feature_flag라는 플래그와 함께

GitLab.com에서 사용 가능 GitLab 17.1에서. 기능 플래그 google_cloud_support_feature_flag 제거됨.

Google Cloud 통합, 예를 들어
Google 아티팩트 관리 통합을 사용하려면
워크로드 아이덴티티 풀 및 공급자를 생성하고 구성해야 합니다.
Google Cloud 통합은 워크로드 아이덴티티 페더레이션을 사용하여
GitLab 워크로드가 OpenID Connect(OIDC)를 통해 JSON 웹 토큰(JWT) 토큰을 사용하여
Google Cloud 리소스에 접근하도록 허용합니다.

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

워크로드 아이덴티티 페더레이션을 사용하면
Identity and Access Management(IAM)를 통해 외부 아이덴티티에
IAM 역할을 부여할 수 있습니다.

전통적으로 Google Cloud 외부에서 실행되는 애플리케이션은
서비스 계정 키를 사용하여
Google Cloud 리소스에 접근했습니다. 그러나 서비스 계정 키는 강력한 자격 증명으로,
올바르게 관리되지 않으면 보안 위험을 초래할 수 있습니다.

아이덴티티 페더레이션을 통해 서비스 계정을 요구하지 않고
Identity and Access Management(IAM)를 사용하여 외부 아이덴티티에
IAM 역할을 직접 부여할 수 있습니다. 이 접근 방식은
서비스 계정 및 키와 관련된 유지 관리 및 보안 부담을 제거합니다.

워크로드 아이덴티티 풀

_워크로드 아이덴티티 풀_은 Google Cloud에서
비-Google 아이덴티티를 관리할 수 있게 해주는 엔터티입니다.

GitLab on Google Cloud 통합은 Google Cloud에 인증하기 위해
워크로드 아이덴티티 풀을 설정하는 방법을 안내합니다.
이 설정에는 GitLab 역할 속성을 Google Cloud IAM 정책의 IAM 클레임에 매핑하는 것이 포함됩니다.
GitLab on Google Cloud 통합을 위한 사용 가능한 모든 GitLab 속성의
전체 목록은 OIDC 사용자 정의 클레임을 참조하세요.

워크로드 아이덴티티 풀 공급자

_워크로드 아이덴티티 풀 공급자_는 Google Cloud와
당신의 아이덴티티 공급자(IdP) 간의 관계를 설명하는 엔터티입니다.
GitLab은 GitLab on Google Cloud 통합을 위한
워크로드 아이덴티티 풀의 IdP입니다.

외부 워크로드를 위한 아이덴티티 페더레이션에 대한
자세한 내용은 워크로드 아이덴티티 페더레이션을 참조하세요.

기본 GitLab on Google Cloud 통합은
GitLab에서 Google Cloud로의 인증을 GitLab 조직 수준에서 설정하고자 하는 것으로 가정합니다.
Google Cloud에 대한 접근을 프로젝트 기준으로 제어하고자 하면,
워크로드 아이덴티티 풀 공급자의 IAM 정책을 구성해야 합니다.
GitLab 조직에서 Google Cloud에 접근할 수 있는 사람을 제어하는 방법에 대한 자세한 내용은
IAM으로 접근 제어를 참조하세요.

GitLab과 워크로드 아이덴티티 페더레이션을 통한 인증

귀하의 워크로드 아이덴티티 풀과 공급자가
GitLab 역할 및 권한을 IAM 역할에 매핑하도록 설정된 후,
GitLab에서 Google Cloud로 워크로드를 배포하기 위해
identity 키워드를
google_cloud로 설정하여 러너를 프로비저닝할 수 있습니다.

GitLab on Google Cloud 통합을 사용하여 러너를 프로비저닝하는 방법에 대한
자세한 내용은 튜토리얼 Google Cloud에서 러너 프로비저닝하기를 참조하세요.

워크로드 아이덴티티 연합 생성 및 구성

워크로드 아이덴티티 연합을 설정하려면 다음 방법 중 하나를 사용할 수 있습니다:

GitLab UI를 사용하여 가이드 설정을 진행합니다.
Google Cloud CLI를 사용하여 워크로드 아이덴티티 연합을 수동으로 설정합니다.

GitLab UI 사용하기

워크로드 아이덴티티 연합을 설정하기 위해 GitLab UI를 사용하려면:

왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > Integrations를 선택합니다.
Google Cloud IAM 통합을 찾고 Configure를 선택합니다.
Guided setup을 선택하고 지침을 따릅니다.

알려진 문제로 인해, 가이드 설정에서 스크립트를 실행한 후 Google Cloud IAM 통합 페이지의 필드가 채워지지 않을 수 있습니다. 필드가 비어 있으면 페이지를 새로 고치십시오. 자세한 내용은 이슈 448831을 참조하세요.

Google Cloud CLI 사용하기

사전 요구 사항:

Google Cloud CLI는 설치 및 인증되어야 합니다.
Google Cloud에서 워크로드 아이덴티티 연합을 관리할 수 있는 권한을 가져야 합니다.

다음 명령어로 워크로드 아이덴티티 풀을 생성합니다. 다음 값을 교체하십시오:
- <your_google_cloud_project_id>를 귀하의 Google Cloud 프로젝트 ID로 교체합니다. 보안을 높이기 위해 리소스 및 CI/CD 프로젝트와 분리된 아이덴티티 관리 전용 프로젝트를 사용합니다.
- <your_identity_pool_id>를 풀에 사용할 ID로 교체합니다. 이 ID는 4에서 32자의 소문자, 숫자 또는 하이픈이어야 합니다. 충돌을 피하기 위해서는 고유한 ID를 사용해야 합니다. GitLab 프로젝트 ID 또는 프로젝트 경로를 포함하는 것이 IAM 정책 관리를 용이하게 합니다. 예: gitlab-my-project-name.
```
gcloud iam workload-identity-pools create <your_identity_pool_id> \
         --project="<your_google_cloud_project_id>" \
         --location="global" \
         --display-name="GitLab 프로젝트 ID를 위한 워크로드 아이덴티티 풀"
```

다음 명령어로 워크로드 아이덴티티 풀에 OIDC 제공자를 추가합니다. 다음 값을 교체하십시오:

<your_identity_provider_id>를 제공자에 사용할 ID로 교체합니다. 이 ID는 4에서 32자의 소문자, 숫자 또는 하이픈이어야 합니다. 충돌을 피하기 위해 아이덴티티 풀 내에서 고유한 ID를 사용해야 합니다. 예: gitlab.
<your_google_cloud_project_id>를 귀하의 Google Cloud 프로젝트 ID로 교체합니다.
<your_identity_pool_id>를 이전 단계에서 생성한 워크로드 아이덴티티 풀의 ID로 교체합니다.
<your_issuer_uri>를 귀하의 아이덴티티 제공자 발급자 URI로 교체합니다. 이 값은 수동 설정을 선택할 때 IAM 통합 페이지에서 복사할 수 있으며, 정확히 일치해야 합니다. 이 매개변수는 루트 그룹의 경로를 포함해야 합니다. 예를 들어, 프로젝트가 my-root-group/my-sub-group/project-a에 있다면 issuer-uri는 https://auth.gcp.gitlab.com/oidc/my-root-group로 설정해야 합니다.

gcloud iam workload-identity-pools providers create-oidc "<your_identity_provider_id>" \
      --location="global" \
      --project="<your_google_cloud_project_id>" \
      --workload-identity-pool="<your_identity_pool_id>" \
      --issuer-uri="<your_issuer_uri>" \
      --display-name="GitLab OIDC 제공자" \
      --attribute-mapping="attribute.guest_access=assertion.guest_access,\
attribute.reporter_access=assertion.reporter_access,\
attribute.developer_access=assertion.developer_access,\
attribute.maintainer_access=assertion.maintainer_access,\
attribute.owner_access=assertion.owner_access,\
attribute.namespace_id=assertion.namespace_id,\
attribute.namespace_path=assertion.namespace_path,\
attribute.project_id=assertion.project_id,\
attribute.project_path=assertion.project_path,\
attribute.user_id=assertion.user_id,\
attribute.user_login=assertion.user_login,\
attribute.user_email=assertion.user_email,\
attribute.user_access_level=assertion.user_access_level,\
google.subject=assertion.sub"

attribute-mapping 매개변수는 OIDC 사용자 정의 클레임과 IAM 정책에서 액세스를 부여하는 데 사용하는 해당 아이덴티티 속성 간의 매핑을 포함해야 합니다. 자세한 내용은 지원되는 OIDC 사용자 정의 클레임 및 Google Cloud에 대한 액세스를 제어하는 방법을 참조하세요.

특정 GitLab 프로젝트 또는 그룹에 대한 아이덴티티 토큰 액세스를 제한하려면 속성 조건을 사용합니다. 프로젝트의 경우 assertion.project_id 속성을 사용하고, 그룹의 경우 assertion.namespace_id 속성을 사용하십시오. 자세한 내용은 속성 조건 정의 방법에 대한 Google Cloud 문서를 참조하세요. 속성 조건을 정의한 후, 워크로드 아이덴티티 제공자 업데이트 방법에 대한 Google Cloud 문서를 참조하십시오.

워크로드 아이덴티티 풀과 제공자를 생성한 후, GitLab에서 설정을 완료하려면:

왼쪽 사이드바에서 Search or go to를 선택하고 프로젝트를 찾습니다.
Settings > Integrations를 선택합니다.
Google Cloud IAM 통합을 찾고 Configure를 선택합니다.
Manual setup을 선택합니다.
필드를 완성합니다.
- Project ID: 워크로드 아이덴티티를 생성한 Google Cloud 프로젝트의 ID입니다. 예: my-sample-project-191923.
- Project number: 동일한 Google Cloud 프로젝트의 번호입니다. 예: 314053285323.
- 이 통합을 위해 생성한 워크로드 아이덴티티 풀의 Pool ID.
- 이 통합을 위해 생성한 워크로드 아이덴티티 제공자의 Provider ID.

OIDC 사용자 정의 클레임

ID 토큰에는 다음과 같은 사용자 정의 클레임이 포함됩니다:

클레임 이름	시기	설명
`namespace_id`	프로젝트 이벤트 시	그룹 또는 사용자 수준 네임스페이스의 ID.
`namespace_path`	프로젝트 이벤트 시	그룹 또는 사용자 수준 네임스페이스의 경로.
`project_id`	프로젝트 이벤트 시	프로젝트의 ID.
`project_path`	프로젝트 이벤트 시	프로젝트의 경로.
`root_namespace_id`	그룹 이벤트 시	루트 그룹 또는 사용자 수준 네임스페이스의 ID.
`root_namespace_path`	그룹 이벤트 시	루트 그룹 또는 사용자 수준 네임스페이스의 경로.
`user_id`	사용자 트리거 이벤트 시	사용자의 ID.
`user_login`	사용자 트리거 이벤트 시	사용자의 사용자 이름.
`user_email`	사용자 트리거 이벤트 시	사용자의 이메일.
`ci_config_ref_uri`	CI/CD 파이프라인 실행 중	상위 CI 파이프라인 정의에 대한 참조 경로.
`ci_config_sha`	CI/CD 파이프라인 실행 중	`ci_config_ref_uri`에 대한 Git 커밋 SHA.
`job_id`	CI/CD 파이프라인 실행 중	CI 작업의 ID.
`pipeline_id`	CI/CD 파이프라인 실행 중	CI 파이프라인의 ID.
`pipeline_source`	CI/CD 파이프라인 실행 중	CI 파이프라인 출처.
`project_visibility`	CI/CD 파이프라인 실행 중	파이프라인이 실행되는 프로젝트의 가시성.
`ref`	CI/CD 파이프라인 실행 중	CI 작업에 대한 Git 참조.
`ref_path`	CI/CD 파이프라인 실행 중	CI 작업에 대한 완전한 자격이 있는 참조.
`ref_protected`	CI/CD 파이프라인 실행 중	Git 참조가 보호되는지 여부.
`ref_type`	CI/CD 파이프라인 실행 중	Git 참조 유형.
`runner_environment`	CI/CD 파이프라인 실행 중	CI 작업에 사용되는 러너의 유형.
`runner_id`	CI/CD 파이프라인 실행 중	CI 작업을 실행하는 러너의 ID.
`sha`	CI/CD 파이프라인 실행 중	CI 작업에 대한 커밋 SHA.
`environment`	CI/CD 파이프라인 실행 중	CI 작업이 배포되는 환경.
`environment_protected`	CI/CD 파이프라인 실행 중	배포된 환경이 보호되는지 여부.
`environment_action`	CI/CD 파이프라인 실행 중	CI 작업에 지정된 환경 작업.
`deployment_tier`	CI/CD 파이프라인 실행 중	CI 작업이 지정하는 환경의 배포 계층.
`user_access_level`	사용자 트리거 이벤트 시	사용자의 역할로, 값은 `guest`, `reporter`, `developer`, `maintainer`, `owner`입니다.
`guest_access`	사용자 트리거 이벤트 시	사용자가 최소한 `guest` 역할을 가지고 있는지 여부를 나타내며, 값은 문자열 “true” 또는 “false”입니다.
`reporter_access`	사용자 트리거 이벤트 시	사용자가 최소한 `reporter` 역할을 가지고 있는지 여부를 나타내며, 값은 문자열 “true” 또는 “false”입니다.
`developer_access`	사용자 트리거 이벤트 시	사용자가 최소한 `developer` 역할을 가지고 있는지 여부를 나타내며, 값은 문자열 “true” 또는 “false”입니다.
`maintainer_access`	사용자 트리거 이벤트 시	사용자가 최소한 `maintainer` 역할을 가지고 있는지 여부를 나타내며, 값은 문자열 “true” 또는 “false”입니다.
`owner_access`	사용자 트리거 이벤트 시	사용자가 최소한 `owner` 역할을 가지고 있는지 여부를 나타내며, 값은 문자열 “true” 또는 “false”입니다.

이 클레임은 ID 토큰 클레임의 상위 집합입니다.

모든 값은 문자열 유형입니다. 상세한 내용과 예시 값은 ID 토큰 클레임 문서를 참조하세요.

Google Cloud에 대한 접근 제어

Workload Identity Federation 설정하기 시,

많은 표준 GitLab 클레임(예: user_access_level)이 자동으로 Google Cloud 속성에 매핑됩니다.

Google Cloud에 접근할 수 있는 사용자에 대한 세부 설정을 GitLab 조직에서 추가로 할 수 있습니다.

이를 위해, Common Expression Language (CEL)를 사용하여 GitLab과 Google Cloud 통합을 위한 OIDC 사용자 정의 속성에 기반하여 주체를 설정합니다.

예를 들어, GitLab에서 maintainer 역할을 가진 사용자가 GitLab 프로젝트 gitlab-org/my-project에서 Google Artifact Registry로 아티팩트를 푸시할 수 있도록 허용하려면:

Google Cloud Console에 로그인하고 Workload Identity Federation 페이지로 이동합니다.
Display name 열에서 작업 로드 아이덴티티 풀을 선택합니다.
Providers 섹션에서 편집하려는 작업 로드 아이덴티티 공급자 옆에 있는 Edit ()을 선택하여 Provider details를 엽니다.
Attribute mapping 섹션에서 Add mapping을 선택합니다.
Google N 텍스트 상자에 다음을 입력합니다:
```
attribute.my_project_maintainer
```

OIDC N 텍스트 상자에 다음 CEL 표현식을 입력합니다:

assertion.maintainer_access=="true" && assertion.project_path=="gitlab-org/my-project"

Save를 선택합니다.

Google 속성 my_project_maintainer는 GitLab 클레임 maintainer_access==true와 project_path=="gitlab-org/my-project"에 매핑됩니다.
Google Cloud Console에서 IAM 페이지로 이동합니다.
Grant access를 선택합니다.
New principals 텍스트 상자에 다음 형식으로 attribute.my_project_maintainer/true를 포함한 주체 세트를 입력합니다:
```
principalSet://iam.googleapis.com/projects/<PROJECT_NUMBER>/locations/global/workloadIdentityPools/<POOL_ID>/attribute.my_project_maintainer/true
```
다음을 대체합니다:
- <PROJECT_NUMBER>는 귀하의 Google Cloud 프로젝트 번호로 대체합니다. 프로젝트 번호를 찾으려면 프로젝트 식별하기를 참조하세요.
- <POOL_ID>는 귀하의 작업 로드 아이덴티티 풀 ID로 대체합니다.
Select a role 드롭다운 목록에서 Google Artifact Registry Writer role (roles/artifactregistry.writer)을 선택합니다.
Save를 선택합니다.

역할이 gitlab-org/my-project 프로젝트에서 GitLab의 maintainer 역할을 가진 사용자를 포함하는 주체 세트에 부여됩니다.

다른 GitLab 프로젝트가 Google Artifact Registry로 아티팩트를 푸시하는 것을 방지하려면, Google Cloud Console에서 IAM 정책을 확인하고 필요에 따라 역할을 제거하거나 편집할 수 있습니다.

IAM 정책 보기

Google Cloud Console에 로그인하고 IAM 페이지로 이동합니다.

View by principals 또는 View by roles 중 하나를 선택할 수 있습니다.

구글 클라우드 워크로드 아이덴티티 페더레이션 및 IAM 정책

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

워크로드 아이덴티티 풀

워크로드 아이덴티티 풀 공급자

GitLab과 워크로드 아이덴티티 페더레이션을 통한 인증

워크로드 아이덴티티 연합 생성 및 구성

GitLab UI 사용하기

Google Cloud CLI 사용하기

OIDC 사용자 정의 클레임

Google Cloud에 대한 접근 제어

IAM 정책 보기

도움말

기능 사용 가능성과 제품 평가판

도움받기