Google Cloud Platform에서 OpenID Connect 구성하기

워크플로우에서 OpenID Connect를 사용해 Google Cloud Platform에 인증해보세요.

출처: 문서

본문

워크플로우에서 OpenID Connect를 사용해 Google Cloud Platform에 인증할 수 있어요.

개요

OpenID Connect(OIDC)를 사용하면 GitHub Actions 워크플로우가 GCP 자격 증명을 장기 보존형 GitHub 시크릿으로 저장하지 않고도 Google Cloud Platform(GCP)의 리소스에 접근할 수 있어요.

이 가이드는 GCP가 GitHub의 OIDC를 페더레이션 ID로 신뢰하도록 구성하는 방법의 개요를 제공하고, 토큰을 사용해 GCP에 인증하고 리소스에 접근하는 google-github-actions/auth 액션용 워크플로우 예시를 포함합니다.

사전 요구 사항

GitHub가 OpenID Connect(OIDC)를 사용하는 방법, 그 아키텍처와 이점에 대한 기본 개념을 배우려면 OpenID Connect를 참고하세요.
진행하기 전에 보안 전략을 계획해 접근 토큰이 예측 가능한 방식으로만 할당되도록 해야 해요. 클라우드 공급자가 접근 토큰을 발급하는 방식을 제어하려면 신뢰할 수 없는 저장소가 클라우드 리소스에 대한 접근 토큰을 요청할 수 없도록 반드시 최소 하나 이상의 조건을 정의해야 합니다. 자세한 내용은 OpenID Connect reference를 참고하세요.
Dependabot 업데이트 작업을 위해 요청된 OIDC 토큰은 event_name 클레임이 dynamic입니다. 신뢰 정책이 GitHub Actions 워크플로우만 승인하도록 의도되었고 클라우드 공급자가 event_name에 대한 조건을 지원한다면, 워크플로우가 기대하는 이벤트 이름만 허용하세요. 자세한 내용은 OpenID Connect reference를 참고하세요.

2026년 7월 15일 이후에 생성된 저장소와 그 이후의 저장소 이름 변경 또는 이전의 경우, 소유자와 저장소 ID를 포함하는 불변 기본 OIDC sub 클레임을 사용하세요(GitHub Enterprise Server에서는 사용 불가). 기존 저장소는 옵트인하지 않는 한 이전 형식을 유지합니다. 자세한 내용은 OpenID Connect reference를 참고하세요.

Google Cloud Workload Identity Provider 추가하기

GCP에서 OIDC ID 공급자를 구성하려면 다음 구성을 수행해야 합니다. 이러한 변경을 만드는 방법에 대한 지침은 the GCP documentation을 참고하세요.

새 identity pool을 만드세요.
매핑을 구성하고 조건을 추가하세요.
새 풀을 서비스 계정에 연결하세요.

ID 공급자 구성에 대한 추가 지침:

보안 강화를 위해 OpenID Connect reference를 검토했는지 확인하세요. 예시는 OpenID Connect reference를 참고하세요.
서비스 계정을 구성에 사용할 수 있으려면 roles/iam.workloadIdentityUser 역할이 할당되어야 해요. 자세한 내용은 the GCP documentation을 참고하세요.
사용할 Issuer URL: https://token.actions.githubusercontent.com

GitHub Actions 워크플로우 업데이트하기

워크플로우를 OIDC용으로 업데이트하려면 YAML을 두 가지 변경해야 해요:

토큰에 대한 권한 설정을 추가하세요.
google-github-actions/auth 액션을 사용해 OIDC 토큰(JWT)을 클라우드 접근 토큰으로 교환하세요.

[!NOTE] 워크플로우나 OIDC 정책에서 환경을 사용할 때는 추가 보안을 위해 환경에 보호 규칙을 추가하는 것을 권장합니다. 예를 들어 환경에 배포 규칙을 구성해 어떤 브랜치와 태그가 환경에 배포하거나 환경 시크릿에 접근할 수 있는지 제한할 수 있어요. 자세한 내용은 Managing environments for deployment를 참고하세요.

권한 설정 추가하기

작업 또는 워크플로우 실행에는 GitHub의 OIDC 공급자가 매 실행마다 JSON Web Token을 만들 수 있도록 id-token: write가 있는 permissions 설정이 필요합니다.

[!NOTE] 워크플로우의 권한에 id-token: write를 설정해도 워크플로우가 리소스를 수정하거나 쓰기 권한을 얻는 것은 아닙니다. 대신 액션이나 단계를 위해 OIDC 토큰을 요청(가져오기)하고 사용(설정)할 수만 있게 해줍니다. 이 토큰은 이후 단기 접근 토큰으로 외부 서비스에 인증하는 데 사용됩니다.

필요한 권한, 구성 예시, 고급 시나리오에 대한 자세한 정보는 OpenID Connect reference를 참고하세요.

접근 토큰 요청하기

google-github-actions/auth 액션은 GitHub OIDC 공급자로부터 JWT를 받은 다음 GCP에 접근 토큰을 요청합니다. 자세한 내용은 GCP documentation을 참고하세요.

이 예시에는 GCP에서 서비스 목록을 요청하는 액션을 사용하는 Get_OIDC_ID_token이라는 작업이 있어요.

WORKLOAD-IDENTITY-PROVIDER: GCP의 ID 공급자 경로로 바꾸세요. 예: projects/example-project-id/locations/global/workloadIdentityPools/name-of-pool/providers/name-of-provider
SERVICE-ACCOUNT: GCP의 서비스 계정 이름으로 바꾸세요.

이 액션은 Workload Identity Federation을 사용해 GitHub OIDC 토큰을 Google Cloud 접근 토큰으로 교환합니다.

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.
name: List services in GCP
on:
  pull_request:
    branches:
      - main

permissions:
  id-token: write

jobs:
  Get_OIDC_ID_token:
    runs-on: ubuntu-latest
    steps:
    - id: 'auth'
      name: 'Authenticate to GCP'
      uses: 'google-github-actions/auth@f1e2d3c4b5a6f7e8d9c0b1a2c3d4e5f6a7b8c9d0'
      with:
          create_credentials_file: 'true'
          workload_identity_provider: 'WORKLOAD-IDENTITY-PROVIDER'
          service_account: 'SERVICE-ACCOUNT'
    - id: 'gcloud'
      name: 'gcloud'
      run: |-
        gcloud auth login --brief --cred-file="${{ steps.auth.outputs.credentials_file_path }}"
        gcloud services list

Google Cloud Platform에서 OpenID Connect 구성하기