AWS 또는 Azure와의 워크로드 아이덴티티 제휴 구성

이 가이드에서는 워크로드 아이덴티티 제휴를 사용하여 AWS 및 Azure 워크로드가 서비스 계정 키 없이 Google Cloud에 인증하도록 허용하는 방법을 설명합니다.

워크로드 아이덴티티 제휴를 사용해서 AWS EC2 및 Azure에서 실행되는 워크로드는 단기 Google Cloud 보안 토큰 서비스 토큰에 대한 환경별 사용자 인증 정보를 교환할 수 있습니다.

환경별 사용자 인증 정보는 다음을 포함합니다.

  • AWS EC2 인스턴스는 인스턴스 프로필을 사용하여 임시 사용자 인증 정보를 요청할 수 있습니다.
  • Azure VM은 관리형 ID를 사용하여 Azure 액세스 토큰을 얻을 수 있습니다.

워크로드 아이덴티티 제휴를 설정하면 이러한 워크로드에서 환경별 사용자 인증 정보를 단기 Google Cloud 사용자 인증 정보와 교환하도록 할 수 있습니다. 워크로드에서 이 단기 사용자 인증 정보를 사용하여 Google Cloud API에 액세스할 수 있습니다.

시작하기 전에

  • 인증을 설정합니다.

    이 페이지의 샘플 사용 방법에 대한 탭을 선택하세요.

    콘솔

    Google Cloud 콘솔을 사용하여 Google Cloud 서비스 및 API에 액세스할 때는 인증을 설정할 필요가 없습니다.

    gcloud

    다음 개발 환경 중 하나에서 이 페이지의 gcloud CLI 샘플을 사용할 수 있습니다.

    • Cloud Shell: gcloud CLI가 이미 설정된 온라인 터미널을 사용하려면 Cloud Shell을 활성화하세요.

      이 페이지 하단에서 Cloud Shell 세션이 시작되고 명령줄 프롬프트가 표시됩니다. 세션이 초기화되는 데 몇 초 정도 걸릴 수 있습니다.

    • 로컬 셸: 로컬 개발 환경에서 gcloud CLI를 사용하려면 gcloud CLI를 설치하고 초기화합니다.

    Python

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

    1. Google Cloud CLI를 설치합니다.
    2. gcloud CLI를 초기화하려면 다음 명령어를 실행합니다.

      gcloud init
    3. Google 계정의 로컬 인증 사용자 인증 정보를 만듭니다.

      gcloud auth application-default login

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

외부 ID 공급업체 준비

이 단계는 각 Azure AD 테넌트 또는 AWS 계정에 대해 한 번만 수행하면 됩니다.

AWS

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

AWS 계정을 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후에는 AWS 사용자AWS 역할이 영구 또는 임시 AWS 보안 사용자 인증 정보를 사용하여 단기 Google Cloud 사용자 인증 정보를 가져오도록 허용할 수 있습니다.

Azure

Azure AD 테넌트에서 새 Azure AD 애플리케이션을 만들고 워크로드 아이덴티티 제휴에 사용할 수 있도록 구성해야 합니다.

애플리케이션을 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후에는 Azure 사용자 및 서비스 주 구성원은 이 애플리케이션의 액세스 토큰을 요청하고 단기 Google Cloud 사용자 인증 정보와 이러한 액세스 토큰을 교환할 수 있습니다.

애플리케이션을 만들려면 다음을 수행합니다.

  1. Azure AD 애플리케이션 및 서비스 주 구성원을 만듭니다.

  2. 애플리케이션의 애플리케이션 ID URI를 설정합니다. 기본 애플리케이션 ID URI(api://APPID)를 사용하거나 커스텀 URI를 지정할 수 있습니다.

    나중에 워크로드 아이덴티티 풀 공급업체를 구성할 때 애플리케이션 ID URI가 필요합니다.

애플리케이션이 Azure AD 애플리케이션의 액세스 토큰을 가져오도록 하려면 관리형 ID를 사용하세요.

  1. 관리형 ID를 만듭니다. 관리형 ID의 객체 ID를 기록해 두세요. 나중에 가장을 구성할 때 필요합니다.

  2. 애플리케이션을 실행하는 가상 머신 또는 다른 리소스에 관리형 ID를 할당합니다.

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

이 단계는 AWS 계정 또는 Azure AD 테넌트당 한 번만 수행하면 됩니다. 그러면 여러 워크로드와 여러 Google Cloud 프로젝트에 동일한 워크로드 아이덴티티 풀과 공급업체를 사용할 수 있습니다.

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

  1. Google Cloud Console의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.

    프로젝트 선택기로 이동

  2. 가장 좋은 방법은 전용 프로젝트를 사용하여 워크로드 아이덴티티 풀 및 공급업체를 관리하는 것입니다.
  3. Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

  4. API IAM, Resource Manager, Service Account Credentials, and Security Token Service 사용 설정

    API 사용 설정

속성 매핑 및 조건 정의

AWS 또는 Azure 워크로드의 환경별 사용자 인증 정보는 여러 속성을 포함하며, Google Cloud에서 주체 식별자(google.subject)로 사용할 속성을 결정해야 합니다.

Google Cloud는 Cloud 감사 로그와 주 구성원 식별자에서 주체 식별자를 사용하여 AWS 또는 Azure 사용자 또는 역할을 고유하게 식별합니다.

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

AWS

속성 매핑은 GetCallerIdentity의 응답 필드를 소스 속성으로 사용할 수 있습니다. 이러한 필드에는 다음이 포함됩니다.

  • account: AWS 계정 번호
  • arn: 외부 항목의 AWS ARN
  • userid: 호출 항목의 고유 식별자

애플리케이션이 연결된 역할이 있는 Amazon Elastic Compute Cloud(EC2) 인스턴스에서 실행 중인 경우 다음 속성 매핑을 사용할 수 있습니다.

google.subject=assertion.arn
attribute.account=assertion.account
attribute.aws_role=assertion.arn.extract('assumed-role/{role}/')
attribute.aws_ec2_instance=assertion.arn.extract('assumed-role/{role_and_session}').extract('/{session}')

매핑은 다음을 수행합니다.

  • ARN을 주체 식별자로 사용(예: "arn:aws:sts::000000000000:assumed-role/ec2-my-role/i-00000000000000000)
  • 커스텀 속성 account를 도입하고 AWS 계정 ID를 할당
  • 커스텀 속성 aws_role을 도입하고 AWS 역할 이름을 할당(예: ec2-my-role)
  • 커스텀 속성 aws_ec2_instance을 도입하고 EC2 인스턴스 ID를 할당(예: i-00000000000000000)

이 매핑을 사용하면 다음에 대한 액세스 권한을 부여할 수 있습니다.

  • 특정 EC2 인스턴스:

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_ec2_instance/EC2_INSTANCE_ID
    

  • 역할의 모든 사용자 및 인스턴스:

    principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/ROLE_NAME
    

Azure

속성 매핑은 커스텀 클레임을 포함하여 Azure 액세스 토큰에 포함된 클레임을 소스 속성으로 사용할 수 있습니다. 대부분의 경우 sub 클레임을 제목 식별자로 사용하는 것이 가장 좋습니다.

google.subject=assertion.sub

관리형 ID에 발급된 액세스 토큰의 경우 sub 클레임에 관리형 ID의 객체 ID가 포함됩니다. 다른 클레임을 사용하는 경우 해당 클레임이 고유하고 다시 할당될 수 없는지 확인합니다.

참조할 수 있는 클레임 목록을 모르는 경우 다음을 수행합니다.

  1. 관리형 ID가 할당된 Azure VM에 연결합니다.

  2. Azure Instance Metadata Service(IMDS)에서 액세스 토큰을 받습니다.

    Bash

    curl \
      "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
      -H "Metadata: true" | jq -r .access_token
    

    이 명령어에는 jq 도구가 사용됩니다. jq는 기본적으로 Cloud Shell에서 사용할 수 있습니다.

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = (Invoke-RestMethod `
      -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
      -Headers @{Metadata="true"}).access_token
    Write-Host $SubjectToken
    

    APP_ID_URI워크로드 아이덴티티 제휴를 위해 구성한 애플리케이션의 애플리케이션 ID URI로 바꿉니다.

  3. 웹브라우저에서 https://jwt.ms/로 이동하고 액세스 토큰을 텍스트 상자에 붙여넣습니다.

  4. 클레임을 클릭하여 액세스 토큰에 포함된 클레임 목록을 확인합니다.

서비스 ID의 경우 일반적으로 google.groups 또는 커스텀 속성에 대한 매핑을 만들 필요가 없습니다.

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

AWS

속성 조건을 사용하면 워크로드 아이덴티티 제휴를 사용해서 단기 Google Cloud 토큰을 가져올 수 있는 IAM 사용자 및 역할을 제한할 수 있습니다.

예를 들어 다음 조건은 AWS 역할에 대한 액세스를 제한하고 다른 IAM 식별자를 허용하지 않습니다.

assertion.arn.startsWith('arn:aws:sts::AWS_ACCOUNT_ID:assumed-role/')

Azure

속성 조건을 사용하면 워크로드 아이덴티티 제휴를 사용해서 단기 Google Cloud 토큰을 가져올 수 있는 사용자 및 서비스 주 구성원을 제한할 수 있습니다. 또는 앱 역할 할당을 사용하도록 Azure AD 애플리케이션을 구성할 수 있습니다.

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

필요한 역할

워크로드 아이덴티티 제휴를 구성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청합니다.

역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.

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

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

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

콘솔

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

    새 워크로드 공급업체 및 풀로 이동

  2. ID 풀 만들기 섹션에서 다음을 입력합니다.

    • 이름: 풀의 이름. 이 이름은 풀 ID로도 사용됩니다. 풀 ID는 나중에 변경할 수 없습니다.
    • 설명: 풀의 목적을 설명하는 텍스트.
  3. 계속을 클릭합니다.

  4. 공급업체 설정 구성:

    AWS

    다음 공급업체 설정을 구성합니다.

    • 공급업체 선택: AWS
    • 공급업체 이름: 공급업체의 이름. 이 이름은 공급업체 ID로도 사용됩니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.

    Azure

    다음 공급업체 설정을 구성합니다.

    • 공급업체 선택: OpenID Connect(OIDC)
    • 공급업체 이름: 공급업체의 이름. 이 이름은 공급업체 ID로도 사용됩니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
    • 발급자 URL: https://sts.windows.net/TENANT_ID. TENANT_ID를 Azure AD 테넌트의 테넌트 ID(GUID)로 바꿉니다.
    • 허용된 잠재고객: Azure AD에서 애플리케이션을 등록할 때 사용한 애플리케이션 ID URI입니다.
  5. 계속을 클릭합니다.

  6. 공급업체 속성 구성 섹션에서 이전에 식별한 속성 매핑을 추가합니다.

  7. 속성 조건 섹션에서 이전에 식별한 속성 조건을 입력합니다. 속성 조건이 없으면 필드를 비워둡니다.

  8. 저장을 클릭하여 워크로드 아이덴티티 풀과 공급업체를 만듭니다.

gcloud

  1. 새 워크로드 아이덴티티 풀을 만듭니다.

    gcloud iam workload-identity-pools create POOL_ID \
        --location="global" \
        --description="DESCRIPTION" \
        --display-name="DISPLAY_NAME"
    

    다음을 바꿉니다.

    • POOL_ID: 풀의 고유 ID
    • DISPLAY_NAME: 풀의 이름
    • DESCRIPTION: 풀에 대한 설명. 이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.
  2. 워크로드 아이덴티티 풀 공급업체를 추가합니다.

    AWS

    AWS의 워크로드 아이덴티티 풀 공급업체를 만들려면 다음 명령어를 실행합니다.

    gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
      --location="global"  \
      --workload-identity-pool="POOL_ID" \
      --account-id="ACCOUNT_ID" \
      --attribute-mapping="MAPPINGS" \
      --attribute-condition="CONDITIONS"
    

    다음을 바꿉니다.

    예시:

    gcloud iam workload-identity-pools providers create-aws example-provider \
      --location="global"  \
      --workload-identity-pool="pool-1" \
      --account-id="123456789000" \
      --attribute-mapping="google.subject=assertion.arn"
    

    Azure

    Azure용 워크로드 아이덴티티 풀 공급업체를 만들려면 다음 명령어를 실행합니다.

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

    다음을 바꿉니다.

    • PROVIDER_ID: 공급업체의 고유 ID
    • POOL_ID: 풀의 ID
    • ISSUER_URI: Azure AD 테넌트의 테넌트 ID(GUID)(경우에 따라 https://sts.windows.net/TENANT_ID 형식) 발급기관 URI는 다양할 수 있으며, 발급기관 URI를 찾으려면 JWT.io를 사용하여 JWT를 디버깅하면 됩니다.
    • APPLICATION_ID_URI: Azure AD에 애플리케이션을 등록할 때 사용한 애플리케이션 ID URI
    • MAPPINGS: 이전에 식별한 쉼표로 구분된 속성 매핑 목록
    • CONDITIONS: (선택사항) 이전에 식별한 속성 조건.

    예시:

    gcloud iam workload-identity-pools providers create-oidc example-provider \
        --location="global" \
        --workload-identity-pool="pool-1" \
        --issuer-uri="https://sts.windows.net/00000000-1111-2222-3333-444444444444" \
        --allowed-audiences="api://my-app" \
        --attribute-mapping="google.subject=assertion.sub,google.groups=assertion.groups"
    

워크로드 인증

이 단계는 워크로드당 한 번 수행해야 합니다.

외부 워크로드의 서비스 계정 만들기

  1. API IAM, Security Token Service, and Service Account Credentials 사용 설정

    API 사용 설정

  2. 워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 가장 좋습니다.

    서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없습니다.

  3. 외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.

외부 워크로드가 서비스 계정을 가장하도록 허용

외부 ID가 서비스 계정을 가장하도록 허용하려면 서비스 계정에 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 부여합니다. 특정 외부 ID나 여러 외부 ID에 역할을 부여할 수 있습니다.

  • 특정 외부 ID의 경우 google.subject 속성을 확인하는 속성 조건을 작성합니다.
  • 여러 외부 ID의 경우 google.groups 속성 또는 커스텀 속성 attribute.NAME를 확인하는 속성 조건을 작성합니다.

콘솔

Google Cloud 콘솔을 사용하여 외부 ID가 서비스 계정을 가장하도록 허용하려면 다음을 수행합니다.

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

    워크로드 아이덴티티 풀로 이동

  2. 업데이트할 워크로드 아이덴티티 풀을 찾아 선택합니다.

  3. 선택한 워크로드 아이덴티티 풀에 액세스 권한을 부여하려면 액세스 권한 부여를 클릭합니다.

  4. 서비스 계정 목록에서 가장하려는 외부 ID의 서비스 계정을 선택합니다.

  5. 풀에서 서비스 계정을 가장할 수 있는 ID를 선택하려면 다음 작업 중 하나를 수행합니다.

    • 워크로드 아이덴티티 풀의 특정 ID만 서비스 계정을 가장하도록 허용하려면 필터와 일치하는 ID만을 선택합니다.

      속성 이름 목록에서 필터링할 속성을 선택합니다.

      속성값 필드에서 예상되는 속성값을 입력합니다. 예를 들어 속성 매핑 google.subject=assertion.sub을 사용하는 경우 속성 이름을 subject로, 속성 값을 외부 ID 공급업체에서 발급한 토큰의 sub 클레임 값으로 설정합니다.

  6. 구성을 저장하려면 저장을 클릭한 다음 닫기를 클릭합니다.

gcloud

gcloud CLI를 사용하여 외부 ID가 서비스 계정을 가장하도록 허용하려면 다음을 수행합니다.

  1. 현재 프로젝트의 프로젝트 번호를 가져오려면 다음 명령어를 실행합니다.

    gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
    
  2. 특정 기준을 충족하는 외부 ID에 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 부여하려면 다음 안내를 따르세요.

    주체별

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
        --role=roles/iam.workloadIdentityUser \
        --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
    

    그룹별

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
        --role=roles/iam.workloadIdentityUser \
        --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
    

    속성별

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
        --role=roles/iam.workloadIdentityUser \
        --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: 속성 매핑의 커스텀 속성 이름

사용자 인증 정보 구성 만들기

Cloud 클라이언트 라이브러리, gcloud CLI, Terraform은 외부 사용자 인증 정보를 자동으로 가져오고 이러한 사용자 인증 정보를 사용하여 서비스 계정을 가장할 수 있습니다. 라이브러리 및 도구가 이 프로세스를 완료하도록 하려면 사용자 인증 정보 구성 파일을 제공해야 합니다. 이 파일은 다음을 정의합니다.

  • 외부 사용자 인증 정보를 가져올 위치
  • 사용할 워크로드 아이덴티티 풀 및 공급업체
  • 가장할 서비스 계정

사용자 인증 정보 구성 파일을 만들려면 다음을 수행합니다.

콘솔

Google Cloud 콘솔에서 사용자 인증 정보 구성 파일을 다운로드합니다.

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

    워크로드 아이덴티티 풀로 이동

  2. 사용할 IdP가 포함된 워크로드 아이덴티티 풀을 찾아 클릭합니다.

  3. 연결된 서비스 계정을 선택합니다.

  4. 사용하려는 서비스 계정을 찾은 후 다운로드를 클릭합니다.

  5. 애플리케이션 구성 대화상자에서 서비스 계정을 가장할 외부 ID가 포함된 공급업체를 선택합니다.

  6. 다음 추가 설정을 제공하세요.

    AWS

    추가 설정이 필요하지 않습니다.

    Azure

    애플리케이션 ID URL: Azure 애플리케이션의 애플리케이션 ID URI

  7. 구성 다운로드를 선택하여 사용자 인증 정보 구성 파일을 다운로드한 후 닫기를 클릭합니다.

gcloud

gcloud iam workload-identity-pools create-cred-config를 사용하여 사용자 인증 정보 구성 파일을 만들려면 다음을 수행합니다.

AWS

라이브러리가 EC2 인스턴스 메타데이터에서 액세스 토큰을 얻을 수 있게 해주는 사용자 인증 정보 구성 파일을 만들려면 다음을 수행합니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --aws \
    --output-file=FILEPATH.json

다음을 바꿉니다.

  • PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
  • POOL_ID: 워크로드 아이덴티티 풀의 ID
  • PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
  • SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
  • SERVICE_ACCOUNT_TOKEN_LIFETIME: 서비스 계정 액세스 토큰의 원하는 수명 기간(초). 제공되지 않은 경우 기본값은 1시간입니다. 1시간보다 긴 수명 기간을 지정하려면 constraints/iam.allowServiceAccountCredentialLifetimeExtension 조직 정책 제약조건을 구성해야 합니다.
  • FILEPATH: 구성을 저장할 파일

AWS IMDSv2를 사용하는 경우 플래그 --enable-imdsv2gcloud iam workload-identity-pools create-cred-config 명령어에 추가해야 합니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --aws \
    --enable-imdsv2 \
    --output-file=FILEPATH.json

AWS 메타데이터 서버를 사용할 수 없으면 다음 AWS 환경 변수를 통해 AWS 보안 사용자 인증 정보를 제공할 수 있습니다.

  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_REGION 또는 AWS_DEFAULT_REGION
  • 선택사항: AWS_SESSION_TOKEN

gcloud CLI 및 라이브러리는 AWS 메타데이터 서버를 사용할 수 없는 경우 이러한 AWS 환경 변수를 사용합니다.

Azure

라이브러리가 Azure 인스턴스 메타데이터 서비스(IMDS)에서 액세스 토큰을 얻을 수 있게 해주는 사용자 인증 정보 구성 파일을 만듭니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --service-account-token-lifetime-seconds=SERVICE_ACCOUNT_TOKEN_LIFETIME \
    --azure \
    --app-id-uri APPLICATION_ID_URI \
    --output-file=FILEPATH.json

다음을 바꿉니다.

  • PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
  • POOL_ID: 워크로드 아이덴티티 풀의 ID
  • PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
  • SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
  • APPLICATION_ID_URI: Azure 애플리케이션의 애플리케이션 ID URI
  • SERVICE_ACCOUNT_TOKEN_LIFETIME: 서비스 계정 액세스 토큰의 원하는 수명 기간(초). 제공되지 않은 경우 기본값은 1시간입니다. 1시간보다 긴 수명 기간을 지정하려면 constraints/iam.allowServiceAccountCredentialLifetimeExtension 조직 정책 제약조건을 구성해야 합니다.
  • FILEPATH: 구성을 저장할 파일

사용자 인증 정보 구성을 사용하여 Google Cloud에 액세스

도구 및 클라이언트 라이브러리가 사용자 인증 정보 구성을 사용하도록 하려면 AWS 또는 Azure 환경에서 다음을 수행합니다.

  1. 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 초기화하고 사용자 인증 정보 구성 파일을 가리키도록 합니다.

    Bash

      export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
      
    여기서 FILEPATH는 사용자 인증 정보 구성 파일의 상대 파일 경로입니다.

    PowerShell

      $env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
      
    여기서 FILEPATH는 사용자 인증 정보 구성 파일의 상대 파일 경로입니다.
  2. 워크로드 아이덴티티 제휴를 지원하고 사용자 인증 정보를 자동으로 찾을 수 있는 클라이언트 라이브러리 또는 도구를 사용합니다.

    C++

    C++용 Google Cloud 클라이언트 라이브러리는 버전 v2.6.0부터 워크로드 아이덴티티 제휴를 지원합니다. 워크로드 아이덴티티 제휴를 사용하려면 gRPC 버전 1.36.0 이상을 사용하여 클라이언트 라이브러리를 빌드해야 합니다.

    Go

    Go용 클라이언트 라이브러리에서 golang.org/x/oauth2 모듈 버전 v0.0.0-20210218202405-ba52d332ba99 이상을 사용하면 ID 제휴가 지원됩니다.

    클라이언트 라이브러리에서 사용하는 이 모듈 버전을 확인하려면 다음 명령어를 실행합니다.

    cd $GOPATH/src/cloud.google.com/go
    go list -m golang.org/x/oauth2
    

    Java

    Java용 클라이언트 라이브러리에서 com.google.auth:google-auth-library-oauth2-http 아티팩트 버전 0.24.0 이상을 사용하면 ID 제휴가 지원됩니다.

    클라이언트 라이브러리에서 사용하는 이 아티팩트의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 Maven 명령어를 실행합니다.

    mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
    

    Node.js

    Node.js용 클라이언트 라이브러리에서 google-auth-library 패키지 버전 7.0.2 이상을 사용하면 워크로드 아이덴티티 제휴가 지원됩니다.

    클라이언트 라이브러리에서 사용하는 이 패키지의 버전을 확인하려면 애플리케이션 디렉터리에서 다음 명령어를 실행합니다.

    npm list google-auth-library
    

    GoogleAuth 객체를 만들 때 프로젝트 ID를 지정하거나 GoogleAuth가 프로젝트 ID를 자동으로 찾도록 허용할 수 있습니다. 프로젝트 ID를 자동으로 찾으려면 구성 파일의 서비스 계정에 프로젝트에 대한 브라우저 역할(roles/browser) 또는 동등한 권한이 있는 역할이 있어야 합니다. 자세한 내용은 google-auth-library 패키지용 README를 참조하세요.

    Python

    Python용 클라이언트 라이브러리에서 google-auth 패키지 버전 1.27.0 이상을 사용하면 ID 제휴가 지원됩니다.

    클라이언트 라이브러리에서 사용하는 이 패키지의 버전을 확인하려면 패키지가 설치된 환경에서 다음 명령어를 실행합니다.

    pip show google-auth
    

    인증 클라이언트의 프로젝트 ID를 지정하려면 GOOGLE_CLOUD_PROJECT 환경 변수를 설정하거나 클라이언트가 프로젝트 ID를 자동으로 찾도록 허용할 수 있습니다. 프로젝트 ID를 자동으로 찾으려면 구성 파일의 서비스 계정에 프로젝트에 대한 브라우저 역할(roles/browser) 또는 동등한 권한이 있는 역할이 있어야 합니다. 자세한 내용은 google-auth 패키지 사용자 가이드를 참조하세요.

    gcloud

    워크로드 아이덴티티 제휴를 사용하여 인증하려면 gcloud auth login 명령어를 사용합니다.

    gcloud auth login --cred-file=FILEPATH.json
    

    FILEPATH를 사용자 인증 정보 구성 파일의 파일 경로로 바꿉니다.

    gcloud CLI에서 워크로드 아이덴티티 제휴는 gcloud CLI 버전 363.0.0 이상에서 지원됩니다.

    Terraform

    버전 3.61.0 이상을 사용하는 경우 Google Cloud 공급업체가 워크로드 아이덴티티 제휴를 지원합니다.

    terraform {
      required_providers {
        google = {
          source  = "hashicorp/google"
          version = "~> 3.61.0"
        }
      }
    }
    

    gsutil

    워크로드 아이덴티티 제휴를 사용하여 인증하려면 다음 방법 중 하나를 사용합니다.

    gcloud와 함께 gsutil을 사용하는 경우 평소처럼 로그인합니다.

    gcloud auth login --cred-file=FILEPATH.json
    

    gsutil을 독립형 명령줄 애플리케이션으로 사용하는 경우 다음 섹션을 포함하도록 .boto 파일을 수정합니다.

    [Credentials]
    gs_external_account_file = FILEPATH
    

    두 경우 모두 FILEPATH를 사용자 인증 정보 구성 파일의 파일 경로로 바꿉니다.

    gsutil에서 워크로드 아이덴티티 제휴는 gcloud CLI 버전 379.0.0 이상에서 지원됩니다.

    bq

    워크로드 아이덴티티 제휴를 사용하여 인증하려면 다음과 같이 gcloud auth login 명령어를 사용합니다.

    gcloud auth login --cred-file=FILEPATH.json
    

    FILEPATH를 사용자 인증 정보 구성 파일의 파일 경로로 바꿉니다.

    bq에서 워크로드 아이덴티티 제휴는 gcloud CLI 버전 390.0.0 이상에서 지원됩니다.

    워크로드 아이덴티티 제휴를 지원하는 클라이언트 라이브러리를 사용할 수 없는 경우 REST API를 사용하여 프로그래매틱 방식으로 인증할 수 있습니다.

고급 시나리오

REST API를 사용하여 워크로드 인증

클라이언트 라이브러리를 사용할 수 없는 경우 다음 단계에 따라 REST API를 사용하여 외부 워크로드가 단기 액세스 토큰을 가져오도록 할 수 있습니다.

  1. 외부 IdP에서 사용자 인증 정보를 가져옵니다.

    AWS

    유효한 요청 서명을 포함하여 보통 AWS GetCallerIdentity() 엔드포인트에 대한 요청에 포함할 정보가 들어 있는 JSON 문서를 만듭니다.

    워크로드 아이덴티티 제휴는 이 JSON 문서를 GetCallerIdentity 토큰으로 참조합니다. 토큰을 사용하면 워크로드 아이덴티티 제휴가 AWS 보안 비밀 액세스 키를 노출하지 않고 ID를 확인할 수 있습니다.

    GetCallerIdentity 토큰은 다음과 유사합니다.

    {
      "url": "https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15",
      "method": "POST",
      "headers": [
        {
          "key": "Authorization",
          "value" : "AWS4-HMAC-SHA256 Credential=AKIASOZTBDV4D7ABCDEDF/20200228/us-east-1/sts/aws4_request, SignedHeaders=host;x-amz-date,Signature=abcedefdfedfd"
        },
        {
          "key": "host",
          "value": "sts.amazonaws.com"
        },
        {
          "key": "x-amz-date",
          "value": "20200228T225005Z"
        },
        {
          "key": "x-goog-cloud-target-resource",
          "value": "//iam.googleapis.com/projects/12345678/locations/global/workloadIdentityPools/my-pool/providers/my-aws-provider"
        },
        {
          "key": "x-amz-security-token",
          "value": "GizFWJTqYX...xJ55YoJ8E9HNU="
        }
      ]
    }
    

    토큰에는 다음 필드가 포함됩니다.

    • url: GetCallerIdentity()에 대한 AWS STS 엔드포인트의 URL이며, 표준 GetCallerIdentity() 요청의 본문이 쿼리 매개변수로 추가됩니다. 예를 들면 https://sts.amazonaws.com?Action=GetCallerIdentity&Version=2011-06-15입니다. 리전 STS 엔드포인트를 사용하고 워크로드를 위해 안정적인 인프라를 설계하는 것이 좋습니다. 자세한 내용은 리전 AWS STS 엔드포인트를 참조하세요.
    • method: HTTP 요청 메서드: POST
    • headers: 다음을 포함하는 HTTP 요청 헤더입니다.
      • Authorization: 요청 서명입니다.
      • host: url 필드의 호스트 이름입니다(예: sts.amazonaws.com).
      • x-amz-date: 요청을 보내는 시간으로, ISO 8601 Basic 문자열로 형식이 지정됩니다. 이 값은 일반적으로 현재 시간으로 설정되며 재생 공격을 방지하는 데 사용됩니다.
      • x-goog-cloud-target-resource: https: 프리픽스가 없는 ID 공급업체의 전체 리소스 이름입니다. 예를 들면 다음과 같습니다.
        //iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
        
      • x-amz-security-token: 세션 토큰 임시 보안 사용자 인증 정보를 사용하는 경우에만 필요합니다.

    다음 예시에서는 URL로 인코딩된 GetCallerIdentity 토큰을 만듭니다. 나중에 사용할 수 있도록 URL로 인코딩 토큰을 추출합니다. 또한 참조를 위해 사람이 읽을 수 있는 토큰도 만듭니다.

    import json
    import urllib
    
    import boto3
    from botocore.auth import SigV4Auth
    from botocore.awsrequest import AWSRequest
    
    def create_token_aws(project_number: str, pool_id: str, provider_id: str) -> None:
        # Prepare a GetCallerIdentity request.
        request = AWSRequest(
            method="POST",
            url="https://sts.amazonaws.com/?Action=GetCallerIdentity&Version=2011-06-15",
            headers={
                "Host": "sts.amazonaws.com",
                "x-goog-cloud-target-resource": f"//iam.googleapis.com/projects/{project_number}/locations/global/workloadIdentityPools/{pool_id}/providers/{provider_id}",
            },
        )
    
        # Set the session credentials and Sign the request.
        # get_credentials loads the required credentials as environment variables.
        # Refer:
        # https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
        SigV4Auth(boto3.Session().get_credentials(), "sts", "us-east-1").add_auth(request)
    
        # Create token from signed request.
        token = {"url": request.url, "method": request.method, "headers": []}
        for key, value in request.headers.items():
            token["headers"].append({"key": key, "value": value})
    
        # The token lets workload identity federation verify the identity without revealing the AWS secret access key.
        print("Token:\n%s" % json.dumps(token, indent=2, sort_keys=True))
        print("URL encoded token:\n%s" % urllib.parse.quote(json.dumps(token)))
    
    def main() -> None:
        # TODO(Developer): Replace the below credentials.
        # project_number: Google Project number (not the project id)
        project_number = "my-project-number"
        pool_id = "my-pool-id"
        provider_id = "my-provider-id"
    
        create_token_aws(project_number, pool_id, provider_id)
    
    if __name__ == "__main__":
        main()

    다음 변수를 초기화합니다.

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:aws:token-type:aws4_request"
    SUBJECT_TOKEN=TOKEN
    

    PowerShell

    $SubjectTokenType = "urn:ietf:params:aws:token-type:aws4_request"
    $SubjectToken = "TOKEN"
    

    여기서 TOKEN은 위의 스크립트에서 생성된 URL로 인코딩된 GetCallerIdentity 토큰입니다.

    Azure

    Azure 인스턴스 메타데이터 서비스(IMDS)에서 할당된 관리형 ID가 있는 Azure VM에 연결하고 액세스 토큰을 가져옵니다.

    Bash

    SUBJECT_TOKEN_TYPE="urn:ietf:params:oauth:token-type:jwt"
    SUBJECT_TOKEN=$(curl \
      "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" \
      -H "Metadata: true" | jq -r .access_token)
    echo $SUBJECT_TOKEN
    

    이 명령어에는 jq 도구가 사용됩니다. jq는 기본적으로 Cloud Shell에서 사용할 수 있습니다.

    PowerShell

    $SubjectTokenType = "urn:ietf:params:oauth:token-type:jwt"
    $SubjectToken = (Invoke-RestMethod `
      -Uri "http://169.254.169.254/metadata/identity/oauth2/token?resource=APP_ID_URI&api-version=2018-02-01" `
      -Headers @{Metadata="true"}).access_token
    Write-Host $SubjectToken
    

    여기서 APP_ID_URI워크로드 아이덴티티 제휴를 위해 구성한 애플리케이션의 애플리케이션 ID URI입니다.

  2. Security Token Service API를 사용하여 사용자 인증 정보를 단기 액세스 토큰과 교환합니다.

    Bash

    STS_TOKEN=$(curl https://sts.googleapis.com/v1/token \
        --data-urlencode "audience=//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID" \
        --data-urlencode "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
        --data-urlencode "requested_token_type=urn:ietf:params:oauth:token-type:access_token" \
        --data-urlencode "scope=https://www.googleapis.com/auth/cloud-platform" \
        --data-urlencode "subject_token_type=$SUBJECT_TOKEN_TYPE" \
        --data-urlencode "subject_token=$SUBJECT_TOKEN" | jq -r .access_token)
    echo $STS_TOKEN
    

    PowerShell

    [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12
    $StsToken = (Invoke-RestMethod `
        -Method POST `
        -Uri "https://sts.googleapis.com/v1/token" `
        -ContentType "application/json" `
        -Body (@{
            "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"   = $SubjectTokenType
            "subjectToken"       = $SubjectToken
        } | ConvertTo-Json)).access_token
    Write-Host $StsToken
    

    다음 값을 바꿉니다.

    • PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
    • POOL_ID: 워크로드 아이덴티티 풀의 ID
    • PROVIDER_ID: 워크로드 아이덴티티 풀의 ID
  3. 보안 토큰 서비스의 토큰을 사용하여 IAM Service Account Credentials APIgenerateAccessToken 메서드를 호출하여 액세스 토근을 가져옵니다.

Bash

ACCESS_TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken \
    -H "Content-Type: text/json; charset=utf-8" \
    -H "Authorization: Bearer $STS_TOKEN" \
    -d @- <<EOF | jq -r .accessToken
    {
        "scope": [ "https://www.googleapis.com/auth/cloud-platform" ]
    }
EOF
)
echo $ACCESS_TOKEN

PowerShell

$AccessToken = (Invoke-RestMethod `
    -Method POST `
    -Uri "https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT_EMAIL:generateAccessToken" `
    -Headers @{ "Authorization" = "Bearer $StsToken" } `
    -ContentType "application/json" `
    -Body (@{
        "scope" = , "https://www.googleapis.com/auth/cloud-platform"
    } | ConvertTo-Json)).accessToken
Write-Host $AccessToken

SERVICE_ACCOUNT_EMAIL을 서비스 계정의 이메일 주소로 바꿉니다.

다음 단계