X.509 인증서로 워크로드 아이덴티티 제휴 구성

이 가이드에서는 자체 인증 기관(CA)에서 발급한 X.509 인증서가 포함된 워크로드 아이덴티티 제휴를 사용하여 Google Cloud에 인증하고 Google Cloud 리소스에 액세스하는 방법을 설명합니다.

워크로드에 mTLS 클라이언트 인증서가 포함된 경우 하나 이상의 CA를 워크로드 아이덴티티 제휴에 신뢰 앵커로 등록하여 Google Cloud에 인증할 수 있습니다. 중간 CA를 등록할 수도 있습니다.

워크로드 아이덴티티 제휴를 사용하면 상호 TLS(mTLS) 연결을 통해 이러한 워크로드가 단기적으로 사용되는 Google Cloud 사용자 인증 정보를 얻도록 설정할 수 있습니다. 워크로드에서 이 단기 사용자 인증 정보를 사용하여 Google Cloud API에 액세스할 수 있습니다.

개념

X.509 인증서 기반 제휴 개념에는 다음이 포함됩니다.

신뢰 앵커는 신뢰할 수 있는 루트로 간주되는 CA 인증서입니다. 클라이언트 인증서 체인은 신뢰 앵커 중 하나에 연결되어야 합니다.
중간 CA는 클라이언트 인증서 체인을 빌드할 수 있게 도와주는 선택적인 인증 기관 인증서입니다.
트러스트 저장소에는 클라이언트 인증서 체인을 검증하는 데 사용되는 신뢰 앵커 인증서와 중간 CA 인증서가 포함됩니다. CA는 클라이언트에 대해 신뢰 인증서를 발급합니다.

다음 유형의 클라이언트 인증서를 트러스트 저장소에 업로드할 수 있습니다.
- 원하는 타사 CA에서 발급한 인증서
- 비공개 CA에서 발급한 인증서
- 자체 서명 인증서 만들기에서 설명하는 서명된 인증서

시작하기 전에

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

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

전용 프로젝트를 사용하여 워크로드 아이덴티티 풀과 제공업체를 관리

Make sure that billing is enabled for your Google Cloud project.

Enable the IAM, Resource Manager, Service Account Credentials, and Security Token Service APIs.

Enable the APIs

필요한 역할

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

워크로드 아이덴티티 풀 관리자(roles/iam.workloadIdentityPoolAdmin)
서비스 계정 관리자(roles/iam.serviceAccountAdmin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

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

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

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

이 섹션에서는 워크로드 아이덴티티 제휴와 트러스트 저장소를 구성하는 방법을 보여줍니다. 이 단계는 각 트러스트 저장소마다 한 번만 수행하면 됩니다. 그러면 여러 워크로드와 여러 Google Cloud 프로젝트에 동일한 워크로드 아이덴티티 풀과 공급업체를 사용할 수 있습니다.

트러스트 저장소 만들기 및 구성

이 섹션에서는 트러스트 저장소의 YAML 구성 파일과 자체 서명된 CA 인증서를 만드는 방법을 보여줍니다.

키 및 서명된 인증서 생성

이 섹션에서는 openssl 명령어를 사용하여 루트 인증서와 중간 인증서를 만듭니다.

인증서가 이미 있으면 이 단계를 건너뛰고 인증서 형식 지정을 계속하면 됩니다.

유효한 keyUsage 및 extendedKeyUsage 필드를 사용하여 루트 인증서 및 서명된 중간 인증서를 생성하려면 다음을 수행합니다.

유효한 서명 인증서를 만드는 데 필요한 최소 구성으로 샘플 example.cnf 파일을 만듭니다. 이 파일을 수정하여 이러한 인증서에 대해 추가 필드를 설정할 수 있습니다.

cat > example.cnf << EOF
[req]
distinguished_name = empty_distinguished_name
[empty_distinguished_name]
# Kept empty to allow setting via -subj command line arg.
[ca_exts]
basicConstraints=critical,CA:TRUE
keyUsage=keyCertSign
extendedKeyUsage=clientAuth
EOF

루트 인증서를 만듭니다.

openssl req -x509 \
    -new -sha256 -newkey rsa:2048 -nodes \
    -days 3650 -subj '/CN=root' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout root.key -out root.cert

중간 인증서에 대한 서명 요청을 만듭니다.

openssl req \
    -new -sha256 -newkey rsa:2048 -nodes \
    -subj '/CN=int' \
    -config example.cnf \
    -extensions ca_exts \
    -keyout int.key -out int.req

중간 인증서를 만듭니다.

openssl x509 -req \
    -CAkey root.key -CA root.cert \
    -set_serial 1 \
    -days 3650 \
    -extfile example.cnf \
    -extensions ca_exts \
    -in int.req -out int.cert

인증서 형식 지정

트러스트 저장소에 새 인증서 또는 기존 인증서를 포함하려면 YAML 파일로 읽어 들일 수 있도록 인증서를 한 줄 형식으로 지정하고 환경 변수에 저장합니다. 인증서는 PEM 형식으로 지정해야 합니다. 인증서 형식을 지정하고 환경 변수에 저장하려면 다음을 수행합니다.

루트 인증서를 한 줄 문자열로 저장합니다.

export ROOT_CERT=$(cat root.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

중간 인증서를 한 줄 문자열로 저장합니다.

export INTERMEDIATE_CERT=$(cat int.cert | sed 's/^[ ]*//g' | sed -z '$ s/\n$//' | tr '\n' $ | sed 's/\$/\\n/g')

트러스트 저장소 YAML 파일 만들기

이 섹션에서는 신뢰 앵커 및 중간 CA가 포함된 트러스트 저장소 YAML 파일을 만듭니다.

트러스트 저장소 YAML 파일을 만들려면 다음 명령어를 실행합니다. 이 파일에는 인증서 형식 지정에서 만든 환경 변수의 인증서 콘텐츠가 포함됩니다. 신뢰 앵커를 추가하려면 trustStore 아래에 trustAnchors 항목을 추가합니다. 중간 CA 인증서를 추가하려면 trustStore 아래에 intermediateCas 항목을 추가합니다.

cat << EOF > trust_store.yaml
trustStore:
  trustAnchors:
  - pemCertificate: "${ROOT_CERT}"
  intermediateCas:
  - pemCertificate: "${INTERMEDIATE_CERT}"
EOF

속성 매핑 및 조건 정의

클라이언트 X.509 인증서에는 여러 속성이 포함될 수 있습니다. Google Cloud의 google.subject를 인증서의 속성에 매핑하여 주체 식별자로 사용하려는 속성을 선택해야 합니다. 예를 들어 인증서의 속성이 주체 일반 이름이면 매핑이 다음과 같이 표시됩니다. google.subject=assertion.subject.dn.cn

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

속성 매핑은 클라이언트 인증서 내에서 다음과 같은 속성을 사용할 수 있습니다.

serialNumberHex: 일련번호
subject.dn.cn: 주체 일반 이름
subject.dn.o: 주체 조직 이름
subject.dn.ou: 주체 조직 단위
issuer.dn.cn: 발급자 일반 이름
issuer.dn.o: 발급자 조직 이름
issuer.dn.ou: 발급자 조직 단위
san.dns: 주체 대체 이름의 첫 번째 DNS 이름
san.uri: 주체 대체 이름의 첫 번째 URI

주체를 고유하게 식별하려면 이러한 속성 중 하나를 google.subject에 매핑해야 합니다. 스푸핑 위협을 방지하려면 변경될 수 없는 고유 값을 갖는 속성을 선택합니다. 기본적으로 google.subject 식별자는 클라이언트 인증서 주체 일반 이름인 assertion.subject.dn.cn으로 설정됩니다.

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

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

예를 들어 다음 조건은 SPIFFE ID spiffe://example/path를 포함하는 클라이언트 인증서에 대한 액세스를 제한합니다.

assertion.san.uri=="spiffe://example/path"

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

새 워크로드 아이덴티티 풀을 만들려면 다음 명령어를 실행합니다.
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
다음을 바꿉니다.
- POOL_ID: 풀의 고유 ID
- DISPLAY_NAME: 풀의 이름
- DESCRIPTION: 선택한 풀에 대한 설명 (이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.)
X.509 워크로드 아이덴티티 풀 공급업체를 추가하려면 다음 명령어를 실행합니다.
```
gcloud iam workload-identity-pools providers create-x509 PROVIDER_ID \
    --location=global \
    --workload-identity-pool="POOL_ID" \
    --trust-store-config-path="TRUST_STORE_CONFIG" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS" \
    --billing-project="ALLOWLISTED_PROJECT"
```
다음을 바꿉니다.
- PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 공급업체 ID
- POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
- TRUST_STORE_CONFIG: 트러스트 저장소 YAML 파일입니다.
- MAPPINGS: 이 가이드 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록 google.subject를 지정하지 않은 경우 기본 매핑은 google.subject=assertion.subject.dn.cn입니다.
- CONDITIONS: 이 가이드 앞부분에서 만든 속성 조건(선택사항). 속성 조건이 없는 경우 매개변수를 삭제하세요.
- ALLOWLISTED_PROJECT: 프로젝트 ID입니다.

워크로드 인증

각 워크로드에서 한 번씩 다음 단계를 수행해야 합니다.

외부 워크로드가 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 버킷 페이지로 이동합니다.
버킷으로 이동
버킷 목록에서 역할을 부여하려는 버킷의 이름을 클릭합니다.
페이지 상단의 권한 탭을 선택합니다.
액세스 권한 부여 버튼을 클릭합니다.

주 구성원 추가 대화상자가 표시됩니다.
새 주 구성원 필드에 버킷에 액세스해야 하는 ID를 한 개 이상 입력합니다.
주체별
```
principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
```
다음을 바꿉니다.
- PROJECT_NUMBER: 프로젝트 번호
- POOL_ID: 워크로드 풀 ID
- SUBJECT: IdP에서 매핑된 개별 주체(예: administrator@example.com)
그룹별
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
```
다음을 바꿉니다.
- PROJECT_NUMBER: 프로젝트 번호
- WORKLOAD_POOL_ID: 워크로드 풀 ID
- GROUP: IdP에서 매핑된 그룹(예: administrator-group@example.com)
속성별
```
principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
```
다음을 바꿉니다.
- PROJECT_NUMBER: 프로젝트 번호
- WORKLOAD_POOL_ID: 워크로드 풀 ID
- ATTRIBUTE_NAME: IdP에서 매핑된 속성 중 하나
- ATTRIBUTE_VALUE: 속성의 값
역할 선택 드롭다운 메뉴에서 역할을 한 개 이상 선택합니다. 선택한 역할 및 부여되는 권한에 대한 간단한 설명이 창에 표시됩니다.
저장을 클릭합니다.

gcloud

gcloud CLI를 사용하여 프로젝트의 리소스에 대한 IAM 역할을 부여하려면 다음을 수행합니다.

리소스가 정의된 프로젝트의 프로젝트 번호를 가져옵니다.

gcloud projects describe $(gcloud config get-value core/project) --format=value\(projectNumber\)

리소스에 대한 액세스 권한을 부여합니다.

gcloud CLI를 사용하여 스토리지 객체 뷰어 역할(roles/storage.objectViewer)을 특정 조건을 충족하는 외부 ID에 부여하려면 다음 명령어를 실행합니다.
주체별
```
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: 워크로드 아이덴티티 풀의 ID
- SUBJECT: google.subject에 매핑한 속성의 예상 값
- GROUP: google.groups에 매핑한 속성의 예상 값
- ATTRIBUTE_NAME: 속성 매핑의 커스텀 속성 이름
- ATTRIBUTE_VALUE: 속성 매핑의 커스텀 속성 값
IAM 허용 정책을 지원하는 모든 Google Cloud 리소스에 대한 역할을 부여할 수 있습니다.

참고: 구성원 식별자에 프로젝트 ID가 아닌 프로젝트 번호를 사용해야 합니다.

서비스 계정 가장

외부 워크로드의 서비스 계정을 만들려면 다음을 수행합니다.
1. Enable the IAM, Security Token Service, and Service Account Credentials APIs.
  Enable the APIs
2. 워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 좋습니다. 서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없지만 서비스 계정이 포함된 프로젝트를 참조해야 합니다.
3. 외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.
4. 서비스 계정에 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 부여합니다.
Google Cloud 콘솔 또는 gcloud CLI를 사용해서 서비스 계정 가장으로 제휴 ID에 액세스 권한을 부여하려면 다음 안내를 따르세요.

콘솔

Google Cloud 콘솔을 사용하여 서비스 계정으로 제휴 ID에 IAM 역할을 부여하려면 다음을 수행합니다.

동일한 프로젝트의 서비스 계정

동일한 프로젝트에서 서비스 계정에 대해 서비스 계정 가장을 사용하여 액세스 권한을 부여하려면 다음을 수행합니다.
1. 워크로드 아이덴티티 풀 페이지로 이동합니다.
  
  워크로드 아이덴티티 풀로 이동
2. 액세스 권한 부여를 선택합니다.
3. 서비스 계정에 액세스 권한 부여 대화상자에서 서비스 계정 가장을 사용하여 액세스 권한 부여를 선택합니다.
4. 서비스 계정 목록에서 가장하려는 외부 ID의 서비스 계정을 선택하고 다음을 수행합니다.
5. 풀에서 서비스 계정을 가장할 수 있는 ID를 선택하려면 다음 작업 중 하나를 수행합니다.
  - 워크로드 아이덴티티 풀의 특정 ID만 서비스 계정을 가장하도록 허용하려면 필터와 일치하는 ID만을 선택합니다.
  - 속성 이름 목록에서 필터링할 속성을 선택합니다.
  - 속성 값 필드에서 속성의 예상 값을 입력합니다. 예를 들어 속성 매핑 google.subject=assertion.sub를 사용하는 경우 속성 이름을 subject로, 속성 값을 외부 ID 공급업체에서 발급한 토큰의 sub 클레임 값으로 설정합니다.
6. 구성을 저장하려면 저장을 클릭한 다음 닫기를 클릭합니다.

다른 프로젝트의 서비스 계정

다른 프로젝트의 서비스 계정에 대해 서비스 계정 가장을 사용하여 액세스 권한을 부여하려면 다음을 수행합니다.
1. 서비스 계정 페이지로 이동합니다.
  
  서비스 계정으로 이동
2. 가장하려는 서비스 계정을 선택합니다.
3. 액세스 관리를 클릭합니다.
4. 주 구성원 추가를 클릭합니다.
5. 주 구성원 필드에 서비스 계정을 가장할 풀의 ID에 대해 다음 주 구성원 식별자 중 하나를 입력합니다.
  주체별
  principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT
  다음을 바꿉니다.
  - PROJECT_NUMBER: 프로젝트 번호
  - POOL_ID: 워크로드 풀 ID
  - SUBJECT: IdP에서 매핑된 개별 주체(예: administrator@example.com)
  그룹별
  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/group/GROUP
  다음을 바꿉니다.
  - PROJECT_NUMBER: 프로젝트 번호
  - WORKLOAD_POOL_ID: 워크로드 풀 ID
  - GROUP: IdP에서 매핑된 그룹(예: administrator-group@example.com)
  속성별
  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
  다음을 바꿉니다.
  - PROJECT_NUMBER: 프로젝트 번호
  - WORKLOAD_POOL_ID: 워크로드 풀 ID
  - ATTRIBUTE_NAME: IdP에서 매핑된 속성 중 하나
  - ATTRIBUTE_VALUE: 속성의 값
  풀별
  principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*
  다음을 바꿉니다.
  - PROJECT_NUMBER: 프로젝트 번호
  - WORKLOAD_POOL_ID: 워크로드 풀 ID
6. 역할 선택에서 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 선택합니다.
7. 구성을 저장하려면 저장을 클릭합니다.

gcloud

gcloud CLI를 사용하여 특정 기준을 충족하는 외부 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: 속성 매핑의 커스텀 속성 이름
ATTRIBUTE_VALUE: 속성 매핑의 커스텀 속성 값

사용자 인증 정보 구성 다운로드 또는 만들기

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

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

또한 X.509 인증서 제휴의 경우 인증서 구성 파일이 필요합니다. 이 파일에는 X.509 클라이언트 인증서 및 비공개 키 파일에 대한 경로가 포함되어 있습니다.

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

직접 리소스 액세스

gcloud iam workload-identity-pools create-cred-config를 사용하여 직접 리소스 액세스에 대해 사용자 인증 정보 및 인증서 구성 파일을 만들려면 다음을 수행합니다.

라이브러리가 X.509 인증서를 사용하여 액세스 토큰을 얻을 수 있게 해주는 사용자 인증 정보 및 인증서 구성 파일을 만듭니다.

gcloud iam workload-identity-pools create-cred-config
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

다음을 바꿉니다.

PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호입니다.
POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID입니다.
CLIENT_CERT_PATH: 클라이언트 인증서 파일의 경로입니다.
CLIENT_KEY_PATH: 클라이언트 인증서 비공개 키 파일의 경로입니다.
FILEPATH: 구성을 저장할 파일입니다.

이 명령어를 실행하면 인증서 구성 파일도 생성되고 기본 Google Cloud CLI 위치에 저장됩니다.

Linux 및 macOS: ~/.config/gcloud/certificate_config.json
Windows: %APPDATA%\gcloud\certificate_config.json

서비스 계정 가장

gcloud iam workload-identity-pools create-cred-config를 사용해서 서비스 계정 가장으로 사용자 인증 정보 및 인증서 구성 파일을 만들려면 다음을 수행합니다.

라이브러리가 X.509 인증서를 사용하여 액세스 토큰을 얻을 수 있게 해주는 사용자 인증 정보 및 인증서 구성 파일을 만듭니다.

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 \
    --credential-cert-path CLIENT_CERT_PATH \
    --credential-cert-private-key-path CLIENT_KEY_PATH \
    --output-file=FILEPATH.json

다음을 바꿉니다.

PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호입니다.
POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID입니다.
SERVICE_ACCOUNT_EMAIL: 서비스 계정 가장을 사용하는 경우 서비스 계정의 이메일 주소입니다.
SERVICE_ACCOUNT_TOKEN_LIFETIME: 서비스 계정 가장을 사용하는 경우 서비스 계정 액세스 토큰의 수명 기간(단위: 초)입니다. 제공되지 않은 경우 기본값은 1시간입니다. 서비스 계정 가장을 사용하지 않으면 이 플래그를 생략합니다. 1시간보다 긴 수명 기간을 지정하려면 constraints/iam.allowServiceAccountCredentialLifetimeExtension 조직 정책 제약조건을 구성해야 합니다.
CLIENT_CERT_PATH: 클라이언트 인증서 파일의 경로입니다.
CLIENT_KEY_PATH: 클라이언트 인증서 비공개 키 파일의 경로입니다.
FILEPATH: 구성을 저장할 파일입니다.

이 명령어를 실행하면 인증서 구성 파일도 생성되고 기본 Google Cloud CLI 위치에 저장됩니다.

Linux 및 macOS: ~/.config/gcloud/certificate_config.json
Windows: %APPDATA%\gcloud\certificate_config.json

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

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

환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 초기화하고 사용자 인증 정보 구성 파일을 가리키도록 합니다.
Bash
export GOOGLE_APPLICATION_CREDENTIALS=`pwd`/FILEPATH.json
여기서 FILEPATH는 사용자 인증 정보 구성 파일의 상대 경로입니다.
PowerShell
$env:GOOGLE_APPLICATION_CREDENTIALS = Resolve-Path 'FILEPATH.json'
여기서 FILEPATH는 사용자 인증 정보 구성 파일의 상대 경로입니다.
클라이언트 라이브러리가 인증서 구성 파일을 찾을 수 있는지 확인합니다. 인증서 구성 파일은 다음 중 하나의 기본 Google Cloud CLI 위치에 저장되어야 합니다.
- Linux 및 macOS: ~/.config/gcloud/certificate_config.json
- Windows: %APPDATA%\gcloud\certificate_config.json
또는 GOOGLE_API_CERTIFICATE_CONFIG 환경 변수로 지정해야 합니다.
워크로드 아이덴티티 제휴를 지원하고 사용자 인증 정보를 자동으로 찾을 수 있는 클라이언트 라이브러리 또는 도구를 사용합니다.

Go

Go용 클라이언트 라이브러리는 cloud.google.com/go/auth 모듈 버전 0.8.0 이상 그리고 google.golang.org/api 모듈 버전 0.189.0을 사용하는 경우 X.509 워크로드 아이덴티티 제휴를 지원합니다.

클라이언트 라이브러리에 사용되는 모듈 버전을 확인하려면 모듈에 대해 go.mod 파일이 포함된 디렉터리에서 다음 명령어를 실행합니다.

  go list -m cloud.google.com/go/auth
  go list -m cloud.google.com/api

Python

Python용 클라이언트 라이브러리는 google-auth 패키지 버전 2.32.0 이상을 사용하는 경우 X.509 워크로드 아이덴티티 제휴를 지원합니다.

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

  pip show google-auth

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

gcloud

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

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

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

gcloud CLI에서 X.509 워크로드 아이덴티티 제휴 지원은 gcloud CLI 버전 488.0.0 이상에서 제공됩니다.

Google Cloud에 액세스하기 위해 일반 요청을 사용하여 액세스 토큰 가져오기

액세스 토큰을 가져오려면 다음을 수행합니다.

curl을 사용하여 mTLS 및 클라이언트 인증서로 토큰 교환을 수행합니다.

curl --key CLIENT_CERT_KEY \
--cert CLIENT_CERT \
--request POST 'https://sts.mtls.googleapis.com/v1/token' \
--header "Content-Type: application/json" \
--data-raw '{
    "subject_token_type": "urn:ietf:params:oauth:token-type:mtls",
    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
    "audience": "WORKLOAD_IDENTITY_POOL_URI",
    "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
    "scope": "https://www.googleapis.com/auth/cloud-platform",
}'

다음을 바꿉니다.

CLIENT_CERT_KEY: 클라이언트 인증서 비공개 키입니다.
CLIENT_CERT: 클라이언트 인증서입니다.
WORKLOAD_IDENTITY_POOL_URI: 다음 형식의 워크로드 아이덴티티 풀 공급업체의 URL입니다.

//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID

이전 단계에서 생성한 Bearer 액세스 토큰을 사용해서 Google Cloud 리소스에 액세스합니다. 예를 들면 다음과 같습니다.
```
curl -X GET 'https://storage.googleapis.com/my_object' -H "Authorization: Bearer $ACCESS_TOKEN"
```

할당량 및 한도

다음 표는 할당량 및 한도를 보여줍니다.

항목	할당량 및 한도	참고
신뢰 앵커 수	한도: 3	각 인증서는 32KB를 초과하지 않아야 합니다.
중간 인증서 수	한도: 10	각 인증서는 32KB를 초과하지 않아야 합니다.
루트 및 중간 인증서 검증 중에 허용되는 이름 제약조건 수	한도: 10
동일한 제목 및 제목 공개 키 정보를 공유하는 중간 인증서	한도: 5	이 한도는 트러스트 저장소별로 지정됩니다.
인증서 체인 깊이	한도: 5	루트 및 클라이언트 인증서를 포함하여 인증서 체인의 최대 깊이입니다.
트러스트 체인을 빌드하려고 시도할 때 중간 인증서를 평가할 수 있는 횟수	한도: 100
클라이언트에서 업로드 및 전달된 인증서의 키	한도: RSA 키는 2,048~4,096비트일 수 있습니다. ECDSA 인증서는 P-256 또는 P-384 곡선을 사용해야 합니다.	RSA-2048 및 P-256은 일반 사용 사례에 권장됩니다. 가장 높은 보안 수준을 위해서는 다른 알고리즘을 사용하세요.

X.509 인증서로 워크로드 아이덴티티 제휴 구성

개념

시작하기 전에

필요한 역할

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

트러스트 저장소 만들기 및 구성

키 및 서명된 인증서 생성

인증서 형식 지정

트러스트 저장소 YAML 파일 만들기

속성 매핑 및 조건 정의

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

워크로드 인증

외부 워크로드가 Google Cloud 리소스에 액세스하도록 허용

직접 리소스 액세스

콘솔

주체별

그룹별

속성별

gcloud

주체별

그룹별

속성별

서비스 계정 가장

콘솔

동일한 프로젝트의 서비스 계정

다른 프로젝트의 서비스 계정

주체별

그룹별

속성별

풀별

gcloud

주체별

그룹별

속성별

사용자 인증 정보 구성 다운로드 또는 만들기

직접 리소스 액세스

서비스 계정 가장

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

Bash

PowerShell

Go

Python

gcloud

Google Cloud에 액세스하기 위해 일반 요청을 사용하여 액세스 토큰 가져오기

할당량 및 한도

다음 단계