이 가이드에서는 AWS 및 Azure 워크로드에서 서비스 계정 키 없이 Google Cloud에 인증하도록 워크로드 아이덴티티 제휴를 사용하는 방법을 설명합니다.
워크로드 아이덴티티 제휴를 사용하면 AWS EC2 및 Azure에서 실행되는 워크로드에서 환경별 사용자 인증 정보를 단기 Google Cloud 보안 토큰 서비스 토큰으로 교환할 수 있습니다.
환경별 사용자 인증 정보에는 다음이 포함됩니다.
- AWS EC2 인스턴스는 인스턴스 프로필을 사용하여 임시 사용자 인증 정보를 요청할 수 있습니다.
- Azure VM은 관리형 ID를 사용해서 Azure 액세스 토큰을 가져올 수 있습니다.
워크로드 아이덴티티 제휴를 설정하면 이러한 워크로드에서 환경별 사용자 인증 정보를 단기 Google Cloud 사용자 인증 정보와 교환하도록 할 수 있습니다. 워크로드에서 이 단기 사용자 인증 정보를 사용하여 Google Cloud API에 액세스할 수 있습니다.
시작하기 전에
인증을 설정합니다.
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Python
이 페이지의 Python 샘플을 로컬 개발 환경에서 사용하려면 gcloud CLI를 설치 및 초기화한 다음 사용자 인증 정보로 애플리케이션 기본 사용자 인증 정보를 설정하세요.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
자세한 내용은 Google Cloud 인증 문서의 로컬 개발 환경 인증 설정을 참조하세요.
외부 ID 공급업체 준비
각 Azure AD 테넌트 또는 AWS 계정에 대해 다음 단계를 한 번만 수행하면 됩니다.
AWS
AWS 계정에서 구성을 변경할 필요가 없습니다.
AWS 계정을 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후에는 AWS 사용자 및 AWS 역할이 영구 또는 임시 AWS 보안 사용자 인증 정보를 사용하여 단기 Google Cloud 사용자 인증 정보를 가져오도록 허용할 수 있습니다.
Azure
Azure AD 테넌트에서 새 Azure AD 애플리케이션을 만들고 워크로드 아이덴티티 제휴에 사용할 수 있도록 구성해야 합니다.
애플리케이션을 신뢰하도록 워크로드 아이덴티티 풀을 구성한 후에는 Azure 사용자 및 서비스 주 구성원이 이 애플리케이션의 액세스 토큰을 요청하고 이 액세스 토큰을 단기 Google Cloud 사용자 인증 정보와 교환할 수 있습니다.
애플리케이션을 만들려면 다음 단계를 따르세요.
애플리케이션의 애플리케이션 ID URI를 설정합니다. 기본 애플리케이션 ID URI(
APPID
)를 사용하거나 커스텀 URI를 지정할 수 있습니다.나중에 워크로드 아이덴티티 풀 공급업체를 구성할 때 애플리케이션 ID URI가 필요합니다.
애플리케이션이 Azure AD 애플리케이션의 액세스 토큰을 가져오도록 하려면 관리형 ID를 사용합니다.
관리형 ID를 만듭니다. 관리형 ID의 객체 ID를 기록해 두세요. 나중에 가장을 구성할 때 필요합니다.
애플리케이션을 실행하는 가상 머신 또는 다른 리소스에 관리형 ID를 할당합니다.
워크로드 아이덴티티 제휴 구성
AWS 계정 또는 Azure AD 테넌트마다 다음 단계를 한 번만 수행하면 됩니다. 그러면 여러 워크로드와 여러 Google Cloud 프로젝트에 동일한 워크로드 아이덴티티 풀과 공급업체를 사용할 수 있습니다.
워크로드 아이덴티티 제휴 구성을 시작하려면 다음을 수행합니다.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
가장 좋은 방법은 전용 프로젝트를 사용하여 워크로드 아이덴티티 풀 및 공급업체를 관리하는 것입니다.
Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.
속성 매핑 및 조건 정의
AWS 또는 Azure 워크로드의 환경별 사용자 인증 정보는 여러 속성을 포함하며, Google Cloud에서 주체 식별자(
google.subject
)로 사용할 속성을 결정해야 합니다.Google Cloud는 Cloud 감사 로그 및 주 구성원 식별자에서 주체 식별자를 사용하여 AWS 또는 Azure 사용자 또는 역할을 고유하게 식별합니다.
필요한 경우 추가 속성을 매핑할 수 있습니다. 그런 다음 리소스에 대한 액세스 권한을 부여할 때 이러한 추가 속성을 참조할 수 있습니다.
AWS
속성 매핑은
GetCallerIdentity
의 응답 필드를 소스 속성으로 사용할 수 있습니다. 이러한 필드에는 다음이 포함됩니다.account
: AWS 계정 번호arn
: 외부 항목의 AWS ARNuserid
: 호출 항목의 고유 식별자
애플리케이션이 연결된 역할이 있는 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가 포함됩니다. 다른 클레임을 사용하는 경우 해당 클레임이 고유하고 다시 할당될 수 없는지 확인합니다.참조할 수 있는 클레임 목록이 확실하지 않은 경우 다음 단계를 따르세요.
관리형 ID가 할당된 Azure VM에 연결합니다.
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로 바꿉니다.웹브라우저에서
https://jwt.ms/
로 이동하고 액세스 토큰을 필드에 붙여넣습니다.클레임을 클릭하여 액세스 토큰에 포함된 클레임 목록을 확인합니다.
서비스 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 역할을 부여해 달라고 요청합니다.
-
워크로드 아이덴티티 풀 관리자(
roles/iam.workloadIdentityPoolAdmin
) -
서비스 계정 관리자(
roles/iam.serviceAccountAdmin
)
역할 부여에 대한 자세한 내용은 액세스 관리를 참조하세요.
커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.
또는 IAM 소유자(roles/owner
) 기본 역할에는 ID 제휴를 구성하는 권한도 포함됩니다. 프로덕션 환경에서는 기본 역할을 부여하지 말아야 하지만 개발 환경 또는 테스트 환경에서는 부여해도 됩니다.이제 워크로드 아이덴티티 풀과 공급업체를 만드는 데 필요한 모든 정보가 수집되었습니다.
콘솔
Google Cloud 콘솔에서 새 워크로드 공급업체 및 풀 페이지로 이동합니다.
ID 풀 만들기 섹션에서 다음을 입력합니다.
- 이름: 풀의 이름입니다. 이 이름은 풀 ID로도 사용됩니다. 풀 ID는 나중에 변경할 수 없습니다.
- 설명: 풀의 목적을 설명하는 텍스트입니다.
계속을 클릭합니다.
공급업체 설정을 구성합니다.
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입니다.
계속을 클릭합니다.
공급업체 속성 구성 섹션에서 이전에 식별한 속성 매핑을 추가합니다.
속성 조건 섹션에서 이전에 식별한 속성 조건을 입력합니다. 속성 조건이 없으면 필드를 비워둡니다.
저장을 클릭하여 워크로드 아이덴티티 풀과 공급업체를 만듭니다.
gcloud
새 워크로드 아이덴티티 풀을 만듭니다.
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --description="DESCRIPTION" \ --display-name="DISPLAY_NAME"
다음을 바꿉니다.
POOL_ID
: 풀의 고유 IDDISPLAY_NAME
: 풀의 이름DESCRIPTION
: 풀에 대한 설명. 이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.
워크로드 아이덴티티 풀 공급업체를 추가합니다.
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"
다음을 바꿉니다.
PROVIDER_ID
: 공급업체의 고유 IDPOOL_ID
: 풀의 IDACCOUNT_ID
: AWS 계정을 식별하는 12자리 숫자MAPPINGS
: 이전에 식별한 속성 매핑의 쉼표로 구분된 목록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
: 공급업체의 고유 IDPOOL_ID
: 풀의 IDISSUER_URI
: Azure AD 테넌트의 테넌트 ID(GUID)(경우에 따라https://sts.windows.net/TENANT_ID
형식) 발급기관 URI는 다양할 수 있으며, 발급기관 URI를 찾으려면 JWT.io를 사용하여 JWT를 디버깅하면 됩니다.APPLICATION_ID_URI
: Azure AD에 애플리케이션을 등록할 때 사용한 애플리케이션 ID URIMAPPINGS
: 이전에 식별한 쉼표로 구분된 속성 매핑 목록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"
워크로드 인증
워크로드마다 한 번씩 다음 단계를 수행해야 합니다.
외부 워크로드가 Google Cloud 리소스에 액세스하도록 허용
워크로드에 Google Cloud 리소스에 대한 액세스 권한을 제공하려면 주 구성원에게 직접 리소스에 대한 액세스 권한을 부여하는 것이 좋습니다. 이 경우 주 구성원은 제휴 사용자입니다. 일부 Google Cloud 제품에는 Google Cloud API 제한사항이 있습니다. 워크로드가 제한사항이 있는 API 엔드포인트를 호출하는 경우 대신 서비스 계정 가장을 사용할 수 있습니다. 이 경우 주 구성원은 ID 역할을 하는 Google Cloud 서비스 계정입니다. 서비스 계정에 리소스에 대한 액세스 권한을 부여합니다.
직접 리소스 액세스
Google Cloud 콘솔 또는 gcloud CLI를 사용하면 제휴 ID에 직접 리소스에 대한 액세스 권한을 부여할 수 있습니다.
콘솔
Google Cloud 콘솔을 사용하여 리소스에 대한 IAM 역할을 직접 부여하려면 리소스 페이지로 이동한 다음 역할을 부여해야 합니다. 다음 예시에서는 Cloud Storage 페이지로 이동하여 제휴 ID에 Cloud Storage 버킷에 대한 스토리지 객체 뷰어(
roles/storage.objectViewer
) 역할을 직접 부여하는 방법을 보여줍니다.- Google Cloud 콘솔에서 Cloud Storage 버킷 페이지로 이동합니다.
버킷 목록에서 역할을 부여하려는 버킷의 이름을 클릭합니다.
페이지 상단의 권한 탭을 선택합니다.
add_box 액세스 권한 부여 버튼을 클릭합니다.
주 구성원 추가 대화상자가 표시됩니다.
새 주 구성원 필드에 버킷에 액세스해야 하는 ID를 한 개 이상 입력합니다.
주체별
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
다음을 바꿉니다.
PROJECT_NUMBER
: 프로젝트 번호POOL_ID
: 워크로드 풀 IDSUBJECT
: IdP에서 매핑된 개별 주체(예:[email protected]
)
그룹별
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
다음을 바꿉니다.
PROJECT_NUMBER
: 프로젝트 번호WORKLOAD_POOL_ID
: 워크로드 풀 IDGROUP
: IdP에서 매핑된 그룹(예:[email protected]
)
속성별
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
다음을 바꿉니다.
PROJECT_NUMBER
: 프로젝트 번호WORKLOAD_POOL_ID
: 워크로드 풀 IDATTRIBUTE_NAME
: IdP에서 매핑된 속성 중 하나ATTRIBUTE_VALUE
: 속성의 값
역할 선택 드롭다운 메뉴에서 역할을 한 개 이상 선택합니다. 선택한 역할 및 부여되는 권한에 대한 간단한 설명이 창에 표시됩니다.
저장을 클릭합니다.
gcloud
gcloud CLI를 사용하여 프로젝트의 리소스에 대한 IAM 역할을 부여하려면 다음을 수행합니다.
리소스가 정의된 프로젝트의 프로젝트 번호를 가져옵니다.
gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)
리소스에 대한 액세스 권한을 부여합니다.
gcloud CLI를 사용하여 특정 기준을 충족하는 외부 ID에 워크로드 아이덴티티 사용자(
roles/iam.workloadIdentityUser
) 역할을 부여하려면 다음 명령어를 실행합니다.주체별
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
그룹별
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
속성별
gcloud storage buckets add-iam-policy-binding BUCKET_ID \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
다음을 바꿉니다.
BUCKET_ID
: 액세스 권한을 부여할 버킷PROJECT_NUMBER
: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호POOL_ID
: 워크로드 아이덴티티 풀의 IDSUBJECT
:google.subject
에 매핑한 속성의 예상 값GROUP
:google.groups
에 매핑한 속성의 예상 값ATTRIBUTE_NAME
: 속성 매핑의 커스텀 속성 이름ATTRIBUTE_VALUE
: 속성 매핑의 커스텀 속성 값
IAM 허용 정책을 지원하는 모든 Google Cloud 리소스에 대한 역할을 부여할 수 있습니다.
서비스 계정 가장
외부 워크로드의 서비스 계정을 만들려면 다음을 수행합니다.
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 가장 좋습니다.
서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없습니다.
외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.
서비스 계정에 워크로드 아이덴티티 사용자 역할(
roles/iam.workloadIdentityUser
)을 부여합니다.워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 좋습니다.
서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없지만 서비스 계정이 포함된 프로젝트를 참조해야 합니다.
Google Cloud 콘솔 또는 gcloud CLI를 사용하여 서비스 계정 가장으로 제휴 ID에 액세스 권한을 부여하려면 다음을 수행합니다.
콘솔
Google Cloud 콘솔을 사용하여 서비스 계정으로 제휴 ID에 IAM 역할을 부여하려면 다음을 수행합니다.
다음을 수행하여 가장할 ID 역할을 하는 서비스 계정을 만듭니다.
Enable the IAM, Security Token Service, and Service Account Credentials APIs.
워크로드의 ID를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 좋습니다.
서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없지만 IAM 액세스 권한을 부여할 때 서비스 계정이 포함된 프로젝트를 참조해야 합니다.
외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.
서비스 계정 가장을 사용하여 액세스 권한을 부여하려면 다음을 수행합니다.
워크로드 아이덴티티 풀 페이지로 이동합니다.
액세스 권한 부여를 선택합니다.
서비스 계정에 액세스 권한 부여 대화상자에서 서비스 계정 가장을 사용하여 액세스 권한 부여를 선택합니다.
서비스 계정 목록에서 가장하려는 외부 ID의 서비스 계정을 선택하고 다음을 수행합니다.
풀에서 서비스 계정을 가장할 수 있는 ID를 선택하려면 다음 작업 중 하나를 수행합니다.
워크로드 아이덴티티 풀의 특정 ID만 서비스 계정을 가장하도록 허용하려면 필터와 일치하는 ID만을 선택합니다.
속성 이름 목록에서 필터링할 속성을 선택합니다.
속성 값 필드에서 속성의 예상 값을 입력합니다. 예를 들어 속성 매핑
google.subject=assertion.sub
를 사용하는 경우 속성 이름을subject
로, 속성 값을 외부 ID 공급업체에서 발급한 토큰의sub
클레임 값으로 설정합니다.
구성을 저장하려면 저장을 클릭한 다음 닫기를 클릭합니다.
gcloud
gcloud CLI를 사용하여 특정 기준을 충족하는 외부 ID에 워크로드 아이덴티티 사용자(
roles/iam.workloadIdentityUser
) 역할을 부여하려면 다음 명령어를 실행합니다.주체별
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT"
그룹별
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP"
속성별
gcloud storage buckets add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \ --role=roles/storage.objectViewer \ --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE"
다음을 바꿉니다.
사용자 인증 정보 구성 다운로드 또는 만들기
Cloud 클라이언트 라이브러리, gcloud CLI, Terraform은 외부 사용자 인증 정보를 자동으로 가져오고 이러한 사용자 인증 정보를 사용하여 서비스 계정을 가장할 수 있습니다. 라이브러리 및 도구가 이 프로세스를 완료하도록 하려면 사용자 인증 정보 구성 파일을 제공해야 합니다. 이 파일은 다음을 정의합니다.
- 외부 사용자 인증 정보를 가져올 위치
- 사용할 워크로드 아이덴티티 풀 및 공급업체
- 가장할 서비스 계정
사용자 인증 정보 구성 파일을 만들려면 다음을 수행합니다.
콘솔
Google Cloud 콘솔에서 사용자 인증 정보 구성 파일을 다운로드하려면 다음을 수행합니다.
Google Cloud 콘솔에서 워크로드 아이덴티티 풀 페이지로 이동합니다.
사용할 IdP의 워크로드 아이덴티티 풀을 찾아 클릭합니다.
직접 리소스 액세스를 사용하기로 선택한 경우 다음을 수행합니다.
액세스 권한 부여를 클릭합니다.
제휴 ID를 사용하여 액세스 권한 부여(권장)
다운로드를 클릭합니다.
계속해서 이 절차 뒷부분에 있는 애플리케이션 구성 대화상자의 안내를 따릅니다.
서비스 계정 가장을 사용하기로 선택한 경우 다음을 수행합니다.
연결된 서비스 계정을 선택합니다.
사용하려는 서비스 계정을 찾은 후
다운로드를 클릭합니다.계속해서 이 절차 뒷부분에 있는 애플리케이션 구성 대화상자의 안내를 따릅니다.
애플리케이션 구성 대화상자에서 외부 ID가 포함된 공급업체를 선택합니다.
다음 추가 설정을 제공하세요.
AWS
추가 설정이 필요하지 않습니다.
Azure
애플리케이션 ID URL: Azure 애플리케이션의 애플리케이션 ID URI
구성 다운로드를 선택하여 사용자 인증 정보 구성 파일을 다운로드한 후 닫기를 클릭합니다.
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
: 워크로드 아이덴티티 풀의 IDPROVIDER_ID
: 워크로드 아이덴티티 풀 공급업체의 IDSERVICE_ACCOUNT_EMAIL
: 서비스 계정 가장을 사용하는 경우 서비스 계정의 이메일 주소. 서비스 계정 가장을 사용하지 않으면 이 플래그를 생략합니다.SERVICE_ACCOUNT_TOKEN_LIFETIME
: 서비스 계정 가장을 사용하는 경우 서비스 계정 액세스 토큰의 수명 기간(단위: 초). 제공되지 않은 경우 기본값은 1시간입니다. 서비스 계정 가장을 사용하지 않으면 이 플래그를 생략합니다. 1시간보다 긴 수명 기간을 지정하려면constraints/iam.allowServiceAccountCredentialLifetimeExtension
조직 정책 제약조건을 구성해야 합니다.FILEPATH
: 구성을 저장할 파일
AWS IMDSv2를 사용하는 경우 플래그
--enable-imdsv2
를gcloud 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
AWS 메타데이터 서버를 사용할 수 없는 경우 gcloud CLI 및 라이브러리가 이러한 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
: 워크로드 아이덴티티 풀의 IDPROVIDER_ID
: 워크로드 아이덴티티 풀 공급업체의 IDSERVICE_ACCOUNT_EMAIL
: 서비스 계정 가장을 사용하는 경우 서비스 계정의 이메일 주소. 서비스 계정 가장을 사용하지 않으면 이 플래그를 생략합니다.APPLICATION_ID_URI
: Azure 애플리케이션의 애플리케이션 ID URISERVICE_ACCOUNT_TOKEN_LIFETIME
: 서비스 계정 가장을 사용하는 경우 서비스 계정 액세스 토큰의 수명 기간(단위: 초). 제공되지 않은 경우 기본값은 1시간입니다. 서비스 계정 가장을 사용하지 않으면 이 플래그를 생략합니다. 1시간보다 긴 수명 기간을 지정하려면constraints/iam.allowServiceAccountCredentialLifetimeExtension
조직 정책 제약조건을 구성해야 합니다.FILEPATH
: 구성을 저장할 파일
사용자 인증 정보 구성을 사용하여 Google Cloud에 액세스
도구 및 클라이언트 라이브러리가 사용자 인증 정보 구성을 사용하도록 하려면 AWS 또는 Azure 환경에서 다음을 수행합니다.
환경 변수
GOOGLE_APPLICATION_CREDENTIALS
를 초기화하고 사용자 인증 정보 구성 파일을 가리키도록 합니다.Bash
여기서export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
FILEPATH
는 사용자 인증 정보 구성 파일의 상대 경로입니다.PowerShell
여기서$env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
FILEPATH
는 사용자 인증 정보 구성 파일의 상대 경로입니다.워크로드 아이덴티티 제휴를 지원하고 사용자 인증 정보를 자동으로 찾을 수 있는 클라이언트 라이브러리 또는 도구를 사용합니다.
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를 사용하여 외부 워크로드가 단기 액세스 토큰을 가져오도록 할 수 있습니다.
외부 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로 인코딩 토큰을 추출합니다. 또한 참조를 위해 인간이 읽을 수 있는 토큰도 만듭니다.다음 변수를 초기화합니다.
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입니다.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
: 워크로드 아이덴티티 풀의 IDPROVIDER_ID
: 워크로드 아이덴티티 풀의 ID
서비스 계정 가장을 사용하는 경우 보안 토큰 서비스의 토큰을 사용하여 IAM Service Account Credentials API의
generateAccessToken
메서드를 호출하여 액세스 토큰을 가져옵니다.
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
을 서비스 계정의 이메일 주소로 바꿉니다.다음 단계
- 워크로드 아이덴티티 제휴 자세히 알아보기
- 워크로드 아이덴티티 제휴 사용 권장사항 알아보기
- 워크로드 아이덴티티 풀 및 공급업체 관리 방법 알아보기
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2024-11-12(UTC)