Google Cloud Workload Identity Federation 및 IAM 정책

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

Google Artifact Management 통합과 같은 Google Cloud 통합을 사용하려면 워크로드 ID 풀 및 제공자를 생성하고 구성해야 합니다. Google Cloud 통합은 워크로드 ID 연합을 사용하여 JSON Web Token (JWT) 토큰을 통해 OpenID Connect (OIDC)를 통해 GitLab 워크로드에 Google Cloud 리소스 액세스를 부여합니다.

워크로드 ID 연합

워크로드 ID 연합을 사용하면 외부 ID를 통해 Identity and Access Management (IAM) 역할을 부여할 수 있습니다. IAM 역할.

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

ID 연합을 사용하면 서비스 계정을 필요로 하지 않고 직접 외부 ID에 IAM 역할을 부여할 수 있습니다. 이 접근 방식은 서비스 계정 및 해당 키와 관련된 유지 관리 및 보안 부담을 없애줍니다.

워크로드 ID 풀

_워크로드 ID 풀_은 Google Cloud에서 비-Google ID를 관리할 수 있도록 하는 엔터티입니다.

Google Cloud 상의 GitLab 통합은 워크로드 ID 풀을 설정하여 Google Cloud에 인증하도록 안내합니다. 이 설정에는 GitLab 역할 속성을 Google Cloud IAM 정책의 IAM 클레임에 매핑하는 것이 포함됩니다. GitLab Google Cloud 통합의 사용 가능한 GitLab 속성의 전체 목록은 OIDC 사용자 정의 클레임을 참조하세요.

워크로드 ID 풀 제공자

_워크로드 ID 풀 제공자_는 Google Cloud와 IdP(Identity provider) 간의 관계를 설명하는 엔터티입니다. GitLab이 GitLab on Google Cloud 통합을 위한 워크로드 ID 풀의 IdP(Identity provider)입니다.

외부 워크로드에 대한 ID 연합에 대한 자세한 내용은 워크로드 ID 연합을 참조하세요.

기본적으로 GitLab on Google Cloud 통합은 GitLab 조직 수준에서 Google Cloud로의 인증 설정을 원하는 것으로 가정합니다. Google Cloud에서 프로젝트별로 Google Cloud 액세스를 제어하려면 워크로드 ID 풀 제공자의 IAM 정책을 구성해야 합니다. GitLab 조직에서 Google Cloud에 누가 액세스할 수 있는지 제어하는 자세한 내용은 IAM을 사용한 액세스 제어를 참조하세요.

워크로드 ID 연합을 사용한 GitLab 인증

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

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

워크로드 ID 연합 생성 및 구성

워크로드 ID 연합을 설정하려면 다음 중 하나를 사용할 수 있습니다:

  • 안내 설정을 위해 GitLab UI 사용.
  • Google Cloud CLI를 사용하여 워크로드 ID 연합을 수동으로 설정.

GitLab UI를 사용하는 경우

워크로드 ID 연합을 설정하려면 GitLab UI를 사용하세요:

  1. 좌측 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 통합을 선택합니다.
  3. Google Cloud IAM 통합을 찾고 구성을 선택합니다.
  4. 안내 설정을 선택하고 지시 사항을 따릅니다.

참고: 알려진 문제로 인해 Google Cloud IAM 통합 페이지의 필드가 스크립트 실행 후에 비어있을 수 있습니다. 필드가 비어 있는 경우 페이지를 새로 고침하세요. 자세한 정보는 이슈 448831을 참조하세요.

Google Cloud CLI를 사용하는 경우

사전 준비 사항:

  • Google Cloud CLI는 설치 및 인증이 되어 있어야 합니다. Google Cloud와 인증됩니다.
  • Google Cloud의 워크로드 ID 연합을 관리하기 위한 권한이 있어야 합니다.

  1. 다음 명령어로 워크로드 ID 풀을 생성하세요. 다음 값을 바꿉니다:

    • <your_google_cloud_project_id> : Google Cloud 프로젝트 ID.
    • <your_identity_pool_id> : 풀에 사용할 ID로, 4~32자의 소문자, 숫자 또는 하이픈이어야 합니다. 충돌을 피하기 위해 고유한 ID를 사용하세요. IAM 정책 관리를 원활하게 하려면 GitLab 프로젝트 ID 또는 프로젝트 경로가 포함된 ID를 사용하세요. 예: 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용 워크로드 ID 풀"

  2. 다음 명령어로 워크로드 ID 풀에 OIDC 제공자를 추가하세요. 다음 값을 바꿉니다:

    • <your_identity_provider_id> : 제공자에 사용할 ID로, 4~32자의 소문자, 숫자 또는 하이픈이어야 합니다. 충돌을 피하기 위해 풀 내에서 고유한 ID를 사용하세요. 예: gitlab.
    • <your_google_cloud_project_id> : Google Cloud 프로젝트 ID.
    • <your_identity_pool_id> : 이전 단계에서 만든 워크로드 ID 풀의 ID.
    • <your_issuer_uri> : Identity 제공자 발행자 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 매개변수는 JWT ID 토큰에 포함된 OIDC 사용자 정의 클레임을 IAM 정책에서 액세스 부여에 사용되는 해당 ID 속성에 매핑해야 합니다. 자세한 내용은 사용 가능한 OIDC 사용자 정의 클레임 및 Google Cloud에 액세스 제어을 참조하세요.

특정 GitLab 프로젝트 또는 그룹에 대한 ID 토큰 액세스를 제한하려면 ID 속성 조건을 사용하세요. 프로젝트를 위해 assertion.project_id를 그룹을 위해 assertion.namespace_id를 사용합니다. 자세한 정보는 Google Cloud의 속성 조건 정의 및 워크로드 ID 제공자 업데이트를 참조하세요.

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

  1. 좌측 사이드바에서 검색 또는 이동을 선택하고 프로젝트를 찾습니다.
  2. 설정 > 통합을 선택합니다.
  3. Google Cloud IAM 통합을 찾고 구성을 선택합니다.
  4. 수동 설정을 선택합니다.
  5. 필드를 완료하세요.
    • Google Cloud에서 워크로드 ID를 만들고 제공자를 생성한 Google Cloud 프로젝트 ID를 입력하세요. 예: my-sample-project-191923.
    • 동일한 Google Cloud 프로젝트의 프로젝트 번호. 예: 314053285323.
    • 이 통합을 위해 만든 워크로드 ID 풀의 풀 ID.
    • 이 통합을 위해 만든 워크로드 ID 풀 제공자의 제공자 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 파이프라인 정의의 ref 경로입니다.
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입니다.
ref_path CI/CD 파이프라인 실행 중 CI 작업의 완전히 지정된 ref입니다.
ref_protected CI/CD 파이프라인 실행 중 Git ref가 보호되었는지 여부입니다.
ref_type CI/CD 파이프라인 실행 중 Git ref 유형입니다.
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 액세스 제어

워크로드 ID Federation 설정을 수행할 때, 표준 GitLab 클레임(예: user_access_level) 중 많은 클레임이 자동으로 Google Cloud 속성에 매핑됩니다.

GitLab 조직에서 Google Cloud에 액세스할 수 있는 사용자를 직접 설정할 수 있습니다. 이를 위해 공통 표현 언어 (CEL)를 사용하여 GitLab의 OIDC 사용자 정의 속성에 기반한 주체를 설정할 수 있습니다.

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

  1. Google Cloud Console에 로그인하고 워크로드 ID Federation 페이지로 이동합니다.

  2. Display name 열에서 워크로드 ID 풀을 선택합니다.

  3. Providers 섹션에서 편집하려는 워크로드 ID 공급자 옆에 있는 Edit ()을 선택하여 Provider details를 엽니다.

  4. Attribute mapping 섹션에서 Add mapping을 선택합니다.

  5. Google N 텍스트 상자에 다음을 입력합니다: 

    attribute.my_project_maintainer

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

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

  7. Save를 선택합니다.

    Google 속성 my_project_maintainer는 GitLab 클레임 maintainer_access==true 및 project_path=="gitlab-org/my-project"에 매핑됩니다.

  8. Google Cloud Console에서 IAM 페이지로 이동합니다.

  9. Grant access를 선택합니다.

  10. 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 풀 ID입니다.

  11. Select a role 드롭다운 목록에서 Google Artifact Registry Writer role (roles/artifactregistry.writer)를 선택합니다.

  12. Save를 선택합니다.

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

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

IAM 정책 보기

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

주체별로 보기 또는 역할별로 보기를 선택할 수 있습니다.