다른 ID 공급업체와의 워크로드 아이덴티티 제휴 구성

이 가이드에서는 다른 ID 공급업체(IdP)와 함께 워크로드 아이덴티티 제휴를 사용하는 방법을 설명합니다.

Google Cloud 외부에서 실행되는 워크로드가 기존 환경별 사용자 인증 정보에 액세스할 수 있습니다. 예를 들면 다음과 같습니다.

워크로드는 동일한 환경에서 실행되는 ID 공급업체(IdP)에서 SAML 어설션 또는 OpenID Connect(OIDC) 토큰을 가져올 수 있습니다.

Google Cloud에 인증하려면 워크로드 아이덴티티 제휴를 사용하여 워크로드에서 환경별 사용자 인증 정보를 단기 Google Cloud 사용자 인증 정보로 교환하도록 하면 됩니다.
워크로드에는 mTLS 클라이언트 인증서와 같은 다른 유형의 사용자 인증 정보가 있을 수 있습니다.

워크로드 아이덴티티 제휴를 커스텀 토큰 브로커와 결합하면 워크로드에서 다른 유형의 사용자 인증 정보를 사용하여 단기 Google Cloud 사용자 인증 정보를 가져오도록 할 수 있습니다.

워크로드 아이덴티티 제휴를 사용하면 순환이 필요한 사용자 인증 정보 수를 줄이는데 도움이 됩니다.

다음 섹션에서는 OpenID Connect(OIDC) 또는 SAML 인증 프로토콜을 지원하는 IdP로 워크로드 아이덴티티 제휴를 사용하는 방법을 설명합니다.

외부 IdP 준비

각 IdP에서 한 번만 다음 단계를 수행하면 됩니다.

시작하기 전에 외부 IdP가 다음 요구사항을 충족하는지 확인하세요.

OIDC

이 IdP는 OpenID Connect 1.0을 지원합니다.
IdP의 OIDC 메타데이터 및 JWKS 엔드포인트는 SSL 및 TLS로 보호되고, 엔드포인트 URL은 https://로 시작하며, 인터넷을 통해 공개적으로 엔드포인트에 액세스할 수 있습니다.

Google Cloud는 이러한 엔드포인트를 사용하여 IdP의 키 세트를 다운로드하고 이 키 세트를 사용하여 토큰을 검증합니다.

자체 서명 인증서로 보호되는 엔드포인트는 Google Cloud에서 지원되지 않습니다.

SAML

이 IdP는 SAML 2.0을 지원합니다.
이 IdP에서는 SAML 서비스 제공업체 구성을 설명하고 IdP의 서명 인증서를 포함하는 SAML SP 메타데이터 문서를 제공합니다.

Google Cloud는 이 인증서를 사용하여 SAML 어설션 및 응답의 유효성을 검사합니다.

IdP가 이러한 기준을 충족하면 다음을 수행합니다.

OIDC

워크로드가 다음 기준을 충족하는 ID 토큰을 가져올 수 있도록 IdP를 구성합니다.

토큰은 RS256 또는 ES256 알고리즘을 사용하여 서명됩니다.
토큰에는 다음 값을 가진 aud 클레임이 포함됩니다.
```
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
다음을 바꿉니다.
- PROJECT_NUMBER: 워크로드 아이덴티티 풀을 만들기 위해 사용하는 Google Cloud 프로젝트의 프로젝트 번호
- POOL_ID: 워크로드 아이덴티티 풀을 식별하는 사용자가 선택한 ID. 나중에 워크로드 아이덴티티 풀을 만들 때 동일한 ID를 사용해야 합니다.
- PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체를 식별하는 사용자가 선택한 ID. 나중에 워크로드 아이덴티티 풀 공급업체를 만들 때 동일한 ID를 사용해야 합니다.
또는 커스텀 잠재고객을 예상하도록 워크로드 아이덴티티 풀 공급업체를 구성할 수 있습니다.
토큰에는 미래의 exp 클레임과 과거의 iat 클레임이 포함됩니다.

exp 값은 iat 값보다 커야 하며 최대 24시간입니다.

ID 토큰에 사용자 ID가 반영되기 때문에 일반적으로 토큰 교환을 수행할 때 ID 토큰을 사용하는 것이 가장 좋습니다. 액세스 토큰을 대신 사용하기로 결정한 경우 액세스 토큰이 다음 추가 요구사항을 충족하는지 확인합니다.

액세스 토큰이 JSON 웹 토큰 형식입니다.
ISSUER/.well-known/openid-configuration URL이 IdP의 OIDC 메타데이터 엔드포인트를 가리키도록 액세스 토큰에 ISSUER 클레임이 포함되어 있습니다.
로컬 JWK 키를 업로드하려면 OIDC JWK 관리를 참조하세요.

SAML

SAML 어설션에 다음이 포함되도록 IdP를 구성합니다.

워크로드 아이덴티티 풀 공급업체에 구성된 항목 ID로 설정된 Issuer 요소. 발급기관 형식은 생략하거나 urn:oasis:names:tc:SAML:2.0:nameid-format:entity으로 설정해야 합니다.
다음이 포함된 Subject 요소:
- NameID 요소.
- Method가 urn:oasis:names:tc:SAML:2.0:cm:bearer로 설정된 정확히 SubjectConfirmation 요소 하나
- NotOnOrAfter가 미래에 발생하는 타임스탬프로 설정되어 있고 NotBefore 값이 아닌 SubjectConfirmationData 요소
다음이 포함된 Conditions 요소:
- NotBefore가 생략되었거나 과거임.
- NotOnOrAfter가 생략되었거나 미래임.
- 형식이 다음과 같이 지정된 Audience:
```
https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID
```
  다음을 바꿉니다.
  - PROJECT_NUMBER: 워크로드 아이덴티티 풀을 만들기 위해 사용하는 Google Cloud 프로젝트의 프로젝트 번호
  - POOL_ID: 워크로드 아이덴티티 풀을 식별하는 사용자가 선택한 ID. 나중에 워크로드 아이덴티티 풀을 만들 때 동일한 ID를 사용해야 합니다.
  - PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체를 식별하는 사용자가 선택한 ID. 나중에 워크로드 아이덴티티 풀 공급업체를 만들 때 동일한 ID를 사용해야 합니다.
하나 이상의 AuthnStatement 요소.
미래에 발생하는 타임스탬프가 있는 SessionNotOnOrAfter 요소. 또는 이 요소를 생략합니다.

SAML 응답에 묶인 SAML 어설션의 경우 SAML 응답에 다음이 포함되어야 합니다.

위 기준을 충족하는 정확히 1개의 어설션.
과거의 1시간 내 값이 있는 IssueInstant 속성.
urn:oasis:names:tc:SAML:2.0:status:Success 상태 코드.

SAML 어설션, 응답 또는 둘 다 서명해야 합니다.

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

각 IdP에서 한 번만 다음 단계를 수행하면 됩니다. 그러면 여러 워크로드와 여러 Google Cloud 프로젝트에 동일한 워크로드 아이덴티티 풀과 공급업체를 사용할 수 있습니다.

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

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

프로젝트 선택기로 이동

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

Google Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다.

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

API 사용 설정

OIDC JWK 관리(선택사항)

이 섹션에서는 워크로드 아이덴티티 풀 OIDC 제공업체에서 자체 업로드된 OIDC JWK를 관리하는 방법을 보여줍니다.

공급업체 만들기 및 OIDC JWK 업로드

OIDC JWK를 만들려면 JWT, JWS, JWE, JWK, JWA 구현을 참조하세요.

워크로드 아이덴티티 풀 공급업체를 만들 때 OIDC JWK 파일을 업로드하려면 --jwk-json-path="JWK_JSON_PATH"로 gcloud iam workload-identity-pools providers create-oidc 명령어를 실행합니다. JWK_JSON_PATH를 JWK JSON 파일의 경로로 바꿉니다.

이 작업은 파일에 있는 항목을 사용해서 업로드된 키를 만듭니다.

OIDC JWK 업데이트

OIDC JWK를 업데이트하려면 gcloud iam Workloads-identity-pools Provider update-oidc 명령어를 --jwk-json-path="JWK_JSON_PATH"로 실행하세요. JWK_JSON_PATH를 JWK JSON 파일의 경로로 바꿉니다.

이 작업은 기존 업로드된 키를 파일에 있는 항목으로 바꿉니다. 교체된 키는 복원할 수 없습니다.

업로드된 모든 OIDC JWK 삭제

업로드된 모든 OIDC JWK를 삭제하고 다시 발급자 URI를 사용하여 키를 가져오려면, gcloud iam workload-identity-pools providers update-oidc 명령어를 --jwk-json-path="JWK_JSON_PATH"로 실행합니다. JWK_JSON_PATH를 빈 파일의 경로로 바꿉니다. --issuer-uri 플래그를 사용해서 발급자 URI를 설정합니다.

이 작업을 수행하면 기존의 모든 업로드 키를 파일에 포함된 키로 삭제합니다. 삭제된 키는 복원할 수 없습니다.

속성 매핑 및 조건 정의

IdP에서 발급한 OIDC 토큰 또는 SAML 어설션에 여러 속성이 포함되어 있을 수 있으며 사용자가 Google Cloud에서 주체 식별자(google.subject)로 사용할 속성을 직접 결정해야 합니다.

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

OIDC

속성 매핑은 외부 IdP에서 발급된 ID 토큰 또는 액세스 토큰에 포함된 클레임을 사용할 수 있습니다.

사용자를 고유하게 식별하려면 이러한 클레임 중 하나를 google.subject에 매핑해야 합니다. 스푸핑 위협을 방지하려면 변경될 수 없는 고유 값을 갖는 클레임을 선택합니다.

많은 IdP가 sub 클레임에 고유하고 변경할 수 없는 ID를 채웁니다. 이러한 IdP의 경우 sub 클레임을 google.subject로 매핑하는 것을 고려하세요.

google.subject=assertion.sub

이 용도로 email 같은 클레임을 사용하지 마세요. 이메일 주소는 일반적으로 재할당되거나 변경될 수 있으므로 사용자를 영구적으로 고유하게 식별하지 않습니다.

SAML

속성 매핑은 외부 IdP에서 발급된 어설션에 포함된 <Subject> 및 <Attribute> 요소를 사용할 수 있습니다. SAML 속성은 다음 키워드를 사용하여 참조될 수 있습니다.

assertion.subject: <Subject> 요소에 있는 인증된 사용자의 NameID가 포함됩니다.
assertion.attributes['ATTRIBUTE_NAME']: 이름이 비슷한 <Attribute>의 값 목록이 포함됩니다.

많은 IdP가 NameId에 고유하고 변경할 수 없는 ID를 채웁니다. 이러한 IdP의 경우 NameId 속성을 google.subject로 매핑하는 것을 고려하세요.

google.subject=assertion.subject

이 용도로 http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress 같은 속성을 사용하지 마세요. 이메일 주소는 일반적으로 재할당되거나 변경될 수 있으므로 사용자를 영구적으로 고유하게 식별하지 않습니다.

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

OIDC

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

예를 들어 다음 조건은 값이 true인 커스텀 service_account 클레임을 포함하는 토큰으로 액세스를 제한합니다.

assertion.service_account==true

SAML

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

예를 들어 다음 조건은 true 값의 커스텀 https://example.com/SAML/Attributes/AllowGcpFederation 속성을 포함하는 어설션으로 액세스를 제한합니다.

assertion.attributes['https://example.com/SAML/Attributes/AllowGcpFederation'][0]=='true'

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

필요한 역할

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

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

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

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

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

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

콘솔

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

새 워크로드 공급업체 및 풀로 이동
ID 풀 만들기에서 다음을 입력합니다.
- 이름: 풀의 이름입니다. 이 이름은 풀 ID로도 사용됩니다. 풀 ID는 나중에 변경할 수 없습니다.
- 설명: 풀의 목적을 설명하는 텍스트.
계속을 클릭합니다.
다음과 같이 제공업체 설정을 구성합니다.
OIDC
- 공급업체 선택에서 OpenID Connect(OIDC)를 선택합니다.
- 공급업체 이름에 공급업체 이름을 입력합니다. 이 이름은 공급업체 ID로도 사용됩니다. 공급업체가 생성된 후에는 공급업체 ID를 변경할 수 없습니다.
- Issuer URL에 IdP의 발급기관 URL을 입력합니다. URL은 https://로 시작해야 합니다.
- (선택사항) JWK 파일(JSON)에서 업로드할 JWK 파일을 선택합니다. 이 필드를 제공하지 않으면 Google Cloud는 발급기관에서 JWK를 가져오려고 시도합니다.
- 허용된 잠재고객: ID 토큰의 예상 잠재고객입니다.
SAML
- 공급업체 선택에서 SAML을 선택합니다.
- 공급업체 이름에 공급업체 이름을 입력합니다. 이 이름은 공급업체 ID로도 사용됩니다. 공급업체가 생성된 후에는 공급업체 ID를 변경할 수 없습니다.
- IDP 메타데이터 파일(XML)에 ID 공급업체에서 제공한 SAML 메타데이터 XML 문서를 업로드합니다.
계속을 클릭합니다.
공급업체 속성 구성에서 이 가이드 앞부분에서 확인한 속성 매핑을 추가합니다.
속성 조건에 이 가이드 앞부분에서 확인한 속성 조건을 입력합니다. 속성 조건이 없으면 필드를 비워둡니다.
워크로드 아이덴티티 풀과 공급업체를 만들려면 저장을 클릭합니다.

gcloud

새 워크로드 아이덴티티 풀을 만들려면 다음 명령어를 실행합니다.
```
gcloud iam workload-identity-pools create POOL_ID \
    --location="global" \
    --description="DESCRIPTION" \
    --display-name="DISPLAY_NAME"
```
다음을 바꿉니다.
- POOL_ID: 풀의 고유 ID
- DISPLAY_NAME: 풀의 이름
- DESCRIPTION: 선택한 풀에 대한 설명 (이 설명은 풀 ID에 액세스 권한을 부여할 때 표시됩니다.)
워크로드 아이덴티티 풀 공급업체를 추가하려면 다음을 수행합니다.
OIDC
OIDC 워크로드 아이덴티티 풀 공급업체를 추가하려면 다음 명령어를 실행합니다.
```
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER" \
    --allowed-audiences="AUDIENCE" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
    --jwk-json-path="JWK_JSON_PATH"
```
다음을 바꿉니다.
- PROVIDER_ID: 선택한 고유 워크로드 아이덴티티 풀 공급업체 ID
- POOL_ID: 앞에서 만든 워크로드 아이덴티티 풀 ID
- ISSUER: OIDC 메타데이터에 정의된 발급기관 URI
- AUDIENCE: ID 토큰의 예상 대상. 예상 대상이 클라이언트 ID와 일치하는 공급업체가 많습니다.
- MAPPINGS: 이 가이드 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록
- CONDITIONS: 이 가이드 앞부분에서 만든 속성 조건(선택사항). 속성 조건이 없는 경우 매개변수를 삭제하세요.
- JWK_JSON_PATH: 로컬로 업로드된 OIDC JWK의 선택적 경로. 이 매개변수를 제공하지 않으면 Google Cloud에서 대신 IdP의 /.well-known/openid-configuration 경로를 사용해서 공개 키가 포함된 JWK를 소싱합니다.
SAML
SAML 워크로드 아이덴티티 풀 공급업체를 추가하려면 다음 명령어를 실행합니다.
```
gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
    --location="global" \
    --workload-identity-pool="POOL_ID" \
    --idp-metadata-path="IDP_METADATA_PATH" \
    --attribute-mapping="MAPPINGS" \
    --attribute-condition="CONDITIONS"
```
다음을 바꿉니다.
- POOL_ID: 풀의 ID
- IDP_METADATA_PATH: SAML IdP 메타데이터 문서의 로컬 파일 경로
- MAPPINGS: 이 가이드의 앞부분에서 만든 쉼표로 구분된 속성 매핑의 목록
- CONDITIONS: 선택사항: 이 가이드의 앞부분에서 만든 속성 조건
gcp- 프리픽스는 예약되어 있으며 풀 또는 공급업체 ID에 사용될 수 없습니다.

선택사항: IdP에서 암호화된 SAML 어설션 허용

SAML 2.0 IdP에서 워크로드 아이덴티티 제휴에서 허용할 수 있는 암호화된 SAML 어설션을 생성할 수 있도록 하려면 다음을 수행합니다.
- 워크로드 아이덴티티 제휴에서 다음을 수행합니다.
- IdP에서 다음을 수행합니다.
SAML 암호화 제공업체 키가 구성되어 있더라도 워크로드 아이덴티티 제휴는 일반 텍스트 어설션을 처리할 수 있습니다.

워크로드 아이덴티티 제휴 SAML 어설션 암호화 키 만들기

이 섹션에서는 워크로드 아이덴티티 제휴가 암호화된 SAML 어설션을 허용할 수 있도록 하는 비대칭 키 쌍을 만드는 방법을 설명합니다.

Google Cloud는 비공개 키를 사용하여 IdP에서 발급하는 SAML 어설션을 복호화합니다. SAML 암호화에 사용할 비대칭 키 쌍을 만들려면 다음 명령어를 실행합니다. 자세한 내용은 지원되는 SAML 암호화 알고리즘을 참조하세요.
```
gcloud iam workload-identity-pools providers keys create KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --use encryption \
    --spec KEY_SPECIFICATION
```
다음을 바꿉니다.
- KEY_ID: 선택한 키 이름
- WORKLOAD_POOL_ID: 풀 ID
- PROVIDER_ID: 공급업체 ID
- KEY_SPECIFICATION: 키 사양(rsa-2048, rsa-3072, rsa-4096 중 하나일 수 있음)
키 쌍이 생성된 후 공개 키를 인증서 파일로 다운로드하려면 다음 명령어를 실행합니다. 워크로드 아이덴티티 제휴만 비공개 키에 액세스할 수 있습니다.
```
gcloud iam workload-identity-pools providers keys describe KEY_ID \
    --workload-identity-pool WORKLOAD_POOL_ID \
    --provider PROVIDER_ID \
    --location global \
    --format "value(keyData.key)" \
    > CERTIFICATE_PATH
```
다음을 바꿉니다.
- KEY_ID: 키 이름
- WORKLOAD_POOL_ID: 풀 ID
- PROVIDER_ID: 공급업체 ID
- CERTIFICATE_PATH: 인증서를 작성할 경로(예: saml-certificate.cer 또는 saml-certificate.pem)
암호화된 SAML 어설션을 발급하도록 SAML 2.0 호환 IdP 구성

마지막 단계에서 다운로드한 공개 인증서를 사용하여 발급되는 SAML 어설션을 암호화하도록 SAML IdP를 구성합니다. 자세한 내용은 IdP팀에 문의하세요.

SAML 어설션을 암호화하도록 IdP를 구성한 후 생성되는 어설션이 실제로 암호화되는지 확인하는 것이 좋습니다. SAML 어설션 암호화가 구성되어 있더라도 워크로드 아이덴티티 제휴는 일반 텍스트 어설션을 처리할 수 있습니다.

워크로드 아이덴티티 제휴 암호화 키 삭제
SAML 암호화 키를 삭제하려면 다음 명령어를 실행합니다.
```
  gcloud iam workload-identity-pools providers keys delete KEY_ID \
      --workload-identity-pool WORKLOAD_POOL_ID \
      --provider PROVIDER_ID \
      --location global
```
다음을 바꿉니다.
- KEY_ID: 키 이름
- WORKLOAD_POOL_ID: 풀 ID
- PROVIDER_ID: 공급업체 ID
지원되는 SAML 암호화 알고리즘

워크로드 아이덴티티 제휴는 다음과 같은 주요 전송 알고리즘을 지원합니다.
워크로드 아이덴티티 제휴는 다음과 같은 블록 암호화 알고리즘을 지원합니다.

워크로드 인증

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

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

API IAM, Security Token Service, and Service Account Credentials 사용 설정
API 사용 설정
워크로드를 나타내는 서비스 계정을 만듭니다. 워크로드마다 전용 서비스 계정을 사용하는 것이 가장 좋습니다.

서비스 계정이 워크로드 아이덴티티 풀과 동일한 프로젝트에 있을 필요는 없습니다.
외부 ID가 액세스할 리소스에 대한 액세스 권한을 서비스 계정에 부여합니다.

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

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

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

콘솔

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

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

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

gcloud

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

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

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

특정 기준을 충족하는 외부 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은 외부 사용자 인증 정보를 자동으로 가져오고 이러한 사용자 인증 정보를 사용하여 서비스 계정을 가장할 수 있습니다. 라이브러리 및 도구가 이 프로세스를 완료하도록 하려면 사용자 인증 정보 구성 파일을 제공해야 합니다. 이 파일은 다음을 정의합니다.

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

Cloud 클라이언트 라이브러리는 로컬 실행 파일을 실행하여 로컬 파일(HTTP URL)에서 외부 사용자 인증 정보를 가져옵니다.

실행 파일 소스 사용자 인증 정보: 라이브러리에서 새 사용자 인증 정보가 필요할 때마다 실행 파일을 실행합니다. 실행 파일이 새 외부 사용자 인증 정보를 가져오는 데 성공하면 다음과 비슷한 JSON 문서를 STDOUT에 작성합니다.
OIDC
```
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}
```
실행 파일이 새 사용자 인증 정보를 얻는 데 실패하면 다음과 같은 JSON 문서를 STDOUT에 작성합니다.
```
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}
```
JSON 문서는 다음 필드를 사용합니다.
- version: JSON 출력의 버전입니다. 현재는 버전 1만 지원됩니다.
- success: 응답 상태입니다.
  
  true인 경우 응답에 id_token 및 token_type 필드가 포함되어야 합니다. 실행 파일은 종료 코드 0으로 종료되어야 합니다.
  
  false인 경우 응답에 code 및 message 필드가 포함되며 0이 아닌 값으로 종료되어야 합니다.
- token_type: 외부 사용자 인증 정보의 토큰 유형입니다. 지원되는 값:
  - urn:ietf:params:oauth:token-type:id_token
  - urn:ietf:params:oauth:token-type:jwt
- id_token: 외부 사용자 인증 정보입니다.
- expiration_time: OIDC 토큰 만료 시간(초 단위 Unix epoch 시간)입니다. 이 필드는 출력 파일이 사용자 인증 정보 구성에 지정된 경우에만 필요합니다.
- code: 오류 코드 문자열입니다.
- message: 오류 메시지입니다.
SAML
```
{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}
```
실행 파일이 새 사용자 인증 정보를 얻는 데 실패하면 다음과 같은 JSON 문서를 STDOUT에 작성합니다.
```
{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}
```
JSON 문서는 다음 필드를 사용합니다.
- version: JSON 출력의 버전입니다. 현재는 버전 1만 지원됩니다.
- success: 응답 상태입니다.
  
  true인 경우 응답에 id_token 및 token_type 필드가 포함되어야 합니다. 실행 파일은 종료 코드 0으로 종료되어야 합니다.
  
  false인 경우 응답에 code 및 message 필드가 포함되며 0이 아닌 값으로 종료되어야 합니다.
- token_type: 외부 사용자 인증 정보의 토큰 유형입니다. urn:ietf:params:oauth:token-type:saml2여야 합니다.
- saml_response: SAML 응답 또는 base64로 인코딩된 SAML 어설션입니다.
- expiration_time: 어설션 만료 시간(초 단위 Unix Epoch 시간)입니다. 이 필드는 출력 파일이 사용자 인증 정보 구성에 지정된 경우에만 필요합니다.
- code: 오류 코드 문자열입니다.
- message: 오류 메시지입니다.
실행 파일을 실행할 때 클라이언트 라이브러리에서 다음 환경 변수를 설정합니다.
- GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: 사용자 인증 정보 구성의 잠재고객입니다. 항상 표시됩니다.
- GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: 예상되는 주체 토큰 유형입니다. 항상 표시됩니다.
- GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: 서비스 계정 이메일입니다. 서비스 계정 명의 도용이 사용된 경우에만 표시됩니다.
- GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: 사용자 인증 정보 구성의 출력 파일 위치입니다. 사용자 인증 정보 구성에 지정된 경우에만 존재합니다.
실행 파일 소스 사용자 인증 정보를 사용하려면 GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES 환경 변수를 1로 설정해야 합니다.
파일 소스 사용자 인증 정보: 라이브러리가 로컬 일반 텍스트 또는 JSON 파일에서 외부 사용자 인증 정보를 읽습니다. 예를 들면 다음과 같습니다.
JSON
```
{
  "mytoken": "ey...
}
```
텍스트
```
ey...
```
외부 사용자 인증 정보는 다음과 같습니다.
- OIDC 토큰
- SAML 응답
- base64로 인코딩된 SAML 어설션
항상 유효한 사용자 인증 정보가 포함되도록 파일을 정기적으로 업데이트해야 합니다. 예를 들어 OIDC 토큰 또는 SAML 어설션이 1시간 동안 유효하다면 적어도 1시간마다 파일을 새로고침해야 합니다.
URL 소스 사용자 인증 정보: 라이브러리에서 새로운 사용자 인증 정보가 필요할 때마다 HTTP 엔드포인트로 GET 요청을 보냅니다. 엔드포인트가 파일 소스 사용자 인증 정보에 사용되는 형식과 동일한 일반 텍스트 또는 JSON 응답을 반환해야 합니다.

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

실행 파일 소스 사용자 인증 정보

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 \
    --output-file=FILEPATH.json \
    --executable-command=EXECUTABLE_COMMAND \
    --executable-timeout-millis=EXECUTABLE_TIMEOUT \
    --executable-output-file=EXECUTABLE_OUTPUT_FILE

다음을 바꿉니다.

PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
POOL_ID: 워크로드 아이덴티티 풀의 ID
PROVIDER_ID: 워크로드 아이덴티티 풀 공급업체의 ID
SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
SERVICE_ACCOUNT_TOKEN_LIFETIME: 서비스 계정 액세스 토큰의 원하는 수명 기간(초). 제공되지 않은 경우 기본값은 1시간입니다. 1시간보다 긴 수명 기간을 지정하려면 constraints/iam.allowServiceAccountCredentialLifetimeExtension 조직 정책 제약조건을 구성해야 합니다.
FILEPATH: 구성을 저장할 파일
EXECUTABLE_COMMAND: OIDC ID 토큰(예: --executable-command="/path/to/command --foo=bar")을 검색하기 위해 실행할 인수를 포함한 전체 명령어
EXECUTABLE_TIMEOUT: 실행 파일이 실행될 때까지 대기하는 선택적 기간(단위: 밀리초, 기본값: 30초)
EXECUTABLE_OUTPUT_FILE: 실행 파일이 생성한 3PI 사용자 인증 정보를 가리키는 파일 경로. 사용자 인증 정보를 캐싱하는 데 유용합니다. 이 경로를 지정하면 인증 라이브러리가 실행 파일을 실행하기 전에 먼저 파일이 있는지 확인합니다.

파일 소스 사용자 인증 정보

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 \
    --output-file=FILEPATH.json \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

다음을 바꿉니다.

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

URL 소스 사용자 인증 정보

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 \
    --output-file=FILEPATH.json \
    --credential-source-url="TOKEN_URL" \
    --credential-source-headers="KEY_1=VALUE_1,KEY_2=VALUE_2" \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

다음을 바꿉니다.

PROJECT_NUMBER: 워크로드 아이덴티티 풀이 포함된 프로젝트의 프로젝트 번호
POOL_ID: 워크로드 아이덴티티 풀의 ID
PROVIDER_ID: 워크로드 아이덴티티 풀의 ID
SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소
SERVICE_ACCOUNT_TOKEN_LIFETIME: 서비스 계정 액세스 토큰의 원하는 수명 기간(초). 제공되지 않은 경우 기본값은 1시간입니다. 1시간보다 긴 수명 기간을 지정하려면 constraints/iam.allowServiceAccountCredentialLifetimeExtension 조직 정책 제약조건을 구성해야 합니다.
FILEPATH: 구성을 저장할 파일
TOKEN_URL: OIDC ID 토큰을 검색할 URL
KEY_n, VALUE_n: TOKEN_URL에 대한 HTTP 요청에 포함할 커스텀 헤더
SOURCE_TYPE: OIDC ID 토큰 파일 형식(text(기본값) 또는 json으로 설정)
FIELD_NAME: 토큰이 포함된 텍스트 파일의 필드(SOURCE_TYPE가 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는 사용자 인증 정보 구성 파일의 상대 파일 경로입니다.
워크로드 아이덴티티 제휴를 지원하고 사용자 인증 정보를 자동으로 찾을 수 있는 클라이언트 라이브러리나 도구를 사용합니다.
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 이상에서 지원됩니다.

다른 ID 공급업체와의 워크로드 아이덴티티 제휴 구성

외부 IdP 준비

OIDC

SAML

OIDC

SAML

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

OIDC JWK 관리(선택사항)

공급업체 만들기 및 OIDC JWK 업로드

OIDC JWK 업데이트

업로드된 모든 OIDC JWK 삭제

속성 매핑 및 조건 정의

OIDC

SAML

OIDC

SAML

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

필요한 역할

콘솔

OIDC

SAML

gcloud

OIDC

SAML

선택사항: IdP에서 암호화된 SAML 어설션 허용

워크로드 아이덴티티 제휴 SAML 어설션 암호화 키 만들기

암호화된 SAML 어설션을 발급하도록 SAML 2.0 호환 IdP 구성

워크로드 아이덴티티 제휴 암호화 키 삭제

지원되는 SAML 암호화 알고리즘

워크로드 인증

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

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

콘솔

gcloud

주체별

그룹별

속성별

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

OIDC

SAML

JSON

텍스트

실행 파일 소스 사용자 인증 정보

파일 소스 사용자 인증 정보

URL 소스 사용자 인증 정보

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

Bash

PowerShell

C++

Go

Java

Node.js

Python

gcloud

Terraform

gsutil

bq

다음 단계