GCP 워크로드 아이덴티티 연합과 OpenID Connect 구성

Tier: Free, Premium, Ultimate
Offering: GitLab.com, Self-managed, GitLab Dedicated

CI_JOB_JWT_V2는 GitLab 15.9에서 더 이상 사용되지 않음
과 GitLab 17.0에서 제거될 예정입니다. 대신 ID 토큰을 사용하세요.

이 튜토리얼은 JSON 웹 토큰(JWT) 토큰과 워크로드 아이덴티티 연합을 사용하여
GitLab CI/CD 작업에서 Google Cloud에 인증하는 방법을 보여줍니다.
이 구성은 비밀을 저장할 필요 없이 즉시 생성되는 단기 자격 증명을 생성합니다.

시작하기 위해 GitLab과 Google Cloud 간의 아이덴티티 연합을 위해
OpenID Connect(OIDC)를 구성합니다. GitLab과 OIDC를 사용하는 방법에 대한 더 많은 정보는
클라우드 서비스에 연결을 읽어보세요.

이 튜토리얼은 Google Cloud 계정과 Google Cloud 프로젝트가 있다고 가정합니다.
귀하의 계정은 Google Cloud 프로젝트에서 워크로드 아이덴티티 풀 관리자 권한이 있어야 합니다.

이 튜토리얼 대신 Terraform 모듈과 CI/CD 템플릿을 사용하려면
GitLab CI/CD 파이프라인의 인증을 단순화하는 방법을 참조하세요.

이 튜토리얼을 완료하려면:

Google Cloud 워크로드 아이덴티티 풀 만들기.
워크로드 아이덴티티 공급자 만들기.
서비스 계정 위임을 위한 권한 부여.
임시 자격 증명 가져오기.

Google Cloud 워크로드 아이덴티티 풀 만들기

새 Google Cloud 워크로드 아이덴티티 풀 생성하기다음 옵션을 사용합니다:

이름: GitLab과 같은 워크로드 아이덴티티 풀의 사람 친화적인 이름.
풀 ID: 워크로드 아이덴티티 풀에 대한 Google Cloud 프로젝트의 고유 ID,
gitlab과 같은 이름. 이 값은 풀을 참조하는 데 사용되며 URL에 표시됩니다.
설명: 선택 사항입니다. 풀에 대한 설명.
활성 풀: 이 옵션이 true인지 확인합니다.

Google Cloud 프로젝트당 GitLab 설치마다 단일 _풀_을 생성하는 것을 권장합니다.
같은 GitLab 인스턴스에서 여러 GitLab 리포지토리와 CI/CD 작업이 있는 경우
다른 _공급자_를 사용하여 동일한 _풀_에 대해 인증할 수 있습니다.

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

새 Google Cloud 워크로드 아이덴티티 공급자 생성하기
이전 단계에서 생성한 워크로드 아이덴티티 풀 내에서 다음 옵션을 사용합니다:

공급자 유형: OpenID Connect (OIDC).
공급자 이름: gitlab/gitlab과 같은 워크로드 아이덴티티 공급자의 사람 친화적인 이름.
공급자 ID: 공급자에 대한 풀 내의 고유 ID,
gitlab-gitlab과 같은 이름. 이 값은 공급자를 참조하는 데 사용되며 URL에 표시됩니다.
발급자(URL): https://gitlab.com/ 또는
https://gitlab.example.com/과 같은 GitLab 인스턴스의 주소.
- 주소는 https:// 프로토콜을 사용해야 합니다.
- 주소는 끝에 슬래시가 있어야 합니다.
대상: 허용된 대상 목록을 수동으로 설정하여 GitLab 인스턴스의 주소,
https://gitlab.com 또는 https://gitlab.example.com과 같이 설정합니다.
- 주소는 https:// 프로토콜을 사용해야 합니다.
- 주소는 끝에 슬래시가 없어야 합니다.

공급자 속성 매핑: 다음 매핑을 작성합니다. 여기서 attribute.X는
Google의 클레임에 존재하도록 원하는 속성의 이름이며, assertion.X는
GitLab 클레임에서 추출할 값을 의미합니다.

Google의 속성	GitLab의 주장을 기준으로 한 속성
`google.subject`	`assertion.sub`
`attribute.X`	`assertion.X`

복잡한 속성을 구축할 수도 있습니다
Common Expression Language (CEL)를 사용합니다.

사용 허가 부여를 위해 사용하고자 하는 모든 속성을 매핑해야 합니다. 예를 들어,
사용자의 이메일 주소를 기반으로 다음 단계에서 권한을 매핑하려는 경우
attribute.user_email을 assertion.user_email에 매핑해야 합니다.

서비스 계정 임직 허가

워크로드 ID 풀 및 워크로드 ID 공급자를 만들면 Google Cloud에 대한 _인증_이 정의됩니다. 이 시점에서 GitLab CI/CD 작업에서 Google Cloud에 인증할 수 있습니다.

그러나 Google Cloud에 대한 권한이 없습니다 (인가).

GitLab CI/CD 작업에 Google Cloud 권한을 부여하려면 다음을 수행해야 합니다:

Google Cloud 서비스 계정을 생성합니다.

원하는 이름과 ID를 사용할 수 있습니다.
IAM 권한을 부여합니다 Google Cloud 리소스에 대한 서비스 계정에.

이러한 권한은 사용 사례에 따라 크게 다릅니다. 일반적으로 이 서비스 계정에 GitLab CI/CD 작업이 사용할 수 있는 Google Cloud 프로젝트와 리소스에 대한 권한을 부여합니다. 예를 들어, GitLab CI/CD 작업에서 Google Cloud Storage 버킷에 파일을 업로드해야 하는 경우 이 서비스 계정에 Cloud Storage 버킷에 대한 roles/storage.objectCreator 역할을 부여합니다.
이 서비스 계정을 임직할 수 있는 외부 ID 권한을 부여합니다.

이 단계는 GitLab CI/CD 작업이 서비스 계정 임직을 통해 Google Cloud에 _인가_하도록 합니다. 이 단계는 IAM 권한을 _서비스 계정 자체_에 부여하여 외부 ID가 해당 서비스 계정으로 행동할 수 있는 권한을 부여합니다. 외부 ID는 principalSet:// 프로토콜을 사용하여 표현됩니다.

이전 단계와 마찬가지로 이 단계는 원하는 구성에 크게 의존합니다.

예를 들어, my-service-account라는 서비스 계정을 GitLab 사용자인 chris가 시작한 GitLab CI/CD 작업에서 임직할 수 있도록 하려면 my-service-account에 외부 ID에 대해 roles/iam.workloadIdentityUser IAM 역할을 부여합니다. 외부 ID는 다음 형식을 취합니다:

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.user_login/chris

여기서 PROJECT_NUMBER는 Google Cloud 프로젝트 번호이며, POOL_ID는 첫 번째 섹션에서 생성된 워크로드 ID 풀의 ID(이름이 아님)입니다.

이 구성은 또한 이전 섹션의 주장에서 매핑된 속성으로 user_login을 추가했다고 가정합니다.

임시 자격 증명 검색

OIDC 및 역할을 구성한 후 GitLab CI/CD 작업은 Google Cloud 보안 토큰 서비스(STS)에서 임시 자격 증명을 검색할 수 있습니다.

CI/CD 작업에 id_tokens를 추가합니다:

job:
  id_tokens:
    GITLAB_OIDC_TOKEN:
      aud: https://gitlab.example.com

ID 토큰을 사용하여 임시 자격 증명을 가져옵니다:

PAYLOAD="$(cat <<EOF
{
  "audience": "//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID",
  "grantType": "urn:ietf:params:oauth:grant-type:token-exchange",
  "requestedTokenType": "urn:ietf:params:oauth:token-type:access_token",
  "scope": "https://www.googleapis.com/auth/cloud-platform",
  "subjectTokenType": "urn:ietf:params:oauth:token-type:jwt",
  "subjectToken": "${GITLAB_OIDC_TOKEN}"
}
EOF
)"

FEDERATED_TOKEN="$(curl --fail "https://sts.googleapis.com/v1/token" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data "${PAYLOAD}" \
  | jq -r '.access_token'
)"

여기서:

PROJECT_NUMBER는 Google Cloud 프로젝트 번호입니다(이름이 아님).
POOL_ID는 첫 번째 섹션에서 생성된 워크로드 ID 풀의 ID입니다.
PROVIDER_ID는 두 번째 섹션에서 생성된 워크로드 ID 공급자의 ID입니다.
GITLAB_OIDC_TOKEN은 OIDC ID 토큰입니다.

그런 다음 결과 페더레이티드 토큰을 사용하여 이전 섹션에서 생성된 서비스 계정을 임직할 수 있습니다:

ACCESS_TOKEN="$(curl --fail "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer FEDERATED_TOKEN" \
  --data '{"scope": ["https://www.googleapis.com/auth/cloud-platform"]}' \
  | jq -r '.accessToken'
)"

여기서:

SERVICE_ACCOUNT_EMAIL은 이전 섹션에서 생성된 임직할 서비스 계정의 전체 이메일 주소입니다.
FEDERATED_TOKEN은 이전 단계에서 검색된 페더레이티드 토큰입니다.

결과는 Google Cloud OAuth 2.0 액세스 토큰으로, 권한 부여 토큰으로 사용할 때 대부분의 Google Cloud API 및 서비스에 인증하는 데 사용할 수 있습니다. 이 값을 gcloud CLI에 전달하려면 환경 변수 CLOUDSDK_AUTH_ACCESS_TOKEN을 설정할 수도 있습니다.

작업 예제

OIDC를 GCP에서 프로비저닝하기 위해 Terraform과 임시 자격 증명을 검색하는 샘플 스크립트를 사용하여 이
참조 프로젝트를 검토하세요.

문제 해결

curl 응답을 디버깅할 때, 최신 버전의 curl을 설치하세요. -f 대신 --fail-with-body를 사용하세요.
이 명령은 유용한 오류 메시지를 포함할 수 있는 전체 바디를 출력합니다.
워크로드 아이덴티티 페더레이션 문제 해결에 대한
Google Cloud 문서를 검토하세요.

On this page

GCP 워크로드 아이덴티티 연합과 OpenID Connect 구성

Google Cloud 워크로드 아이덴티티 풀 만들기

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

서비스 계정 임직 허가

임시 자격 증명 검색

작업 예제

문제 해결

도움말

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

도움받기

On this page