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

이 가이드에서는 외부 ID 공급업체에서 발급된 사용자 인증 정보를 사용하여 서비스 계정을 가장하고 Google Cloud의 리소스에 액세스하는 방법을 설명합니다. 이 프로세스를 워크로드 아이덴티티 제휴라고 부릅니다.

워크로드 아이덴티티 제휴의 일반적인 사용 사례는 다음과 같습니다.

  • Google Cloud 외부에서 실행되는 백그라운드 애플리케이션 또는 지속적 통합/지속적 배포(CI/CD) 파이프라인을 사용 설정하여 Google Cloud 리소스 및 API에 액세스하는 경우
  • Google Cloud 외부에서 실행되는 웹 애플리케이션의 사용자가 Cloud Storage 또는 BigQuery와 같은 Google Cloud 서비스에 저장된 데이터에 액세스할 수 있도록 하는 경우

워크로드 아이덴티티 제휴를 사용하려면 Amazon Web Services(AWS), Azure Active Directory(AD), OIDC 호환 ID 공급업체 또는 SAML 2.0 호환 ID 공급 업체미리보기 등의 외부 ID 공급업체를 신뢰하도록 Google Cloud를 구성합니다. 그런 다음 애플리케이션에서 외부 ID 공급업체가 발급한 사용자 인증 정보를 사용하여 다음 단계에 따라 서비스 계정을 가장할 수 있습니다.

  1. 신뢰할 수 있는 ID 공급업체에서 사용자 인증 정보를 가져옵니다.
  2. 보안 토큰 서비스의 토큰에 대해 사용자 인증 정보를 교환합니다.
  3. 보안 토큰 서비스의 토큰을 사용하여 서비스 계정을 가장하고 단기 Google 액세스 토큰을 가져옵니다..

워크로드 아이덴티티 제휴를 사용하면 서비스 계정 키를 저장하고 관리할 필요가 없습니다.

시작하기 전에

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

    API 사용 설정

  • 추가 공급업체별 안내

    SAML

    SAML 2.0 호환 ID 공급업체를 이용하여 제휴를 구성하려면 다음 단계를 완료해야 합니다.

    • 워크로드 아이덴티티 제휴를 구성할 때 사용할 프로젝트를 식별합니다.

    • Google Cloud 계정팀에 프로젝트의 SAML 2.0 미리보기 액세스를 요청합니다. 미리보기에 대한 액세스 권한이 부여되면 Google Cloud 계정팀에서 알림이 제공됩니다.

    • SAML 2.0 ID 공급업체의 워크로드 아이덴티티 제휴를 구성하려면 gcloud CLI를 사용해야 합니다. SAML 미리보기에 대해 액세스 권한이 부여된 프로젝트로 billing/quota_project를 구성합니다.

필요한 역할

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

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

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

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

외부 ID 공급업체 준비

워크로드 아이덴티티 제휴를 이용하려면 프로젝트에서 워크로드 아이덴티티 풀워크로드 아이덴티티 풀 공급업체를 구성해야 합니다.

AWS

AWS 사용자AWS 역할은 영구 또는 임시 AWS 보안 사용자 인증 정보를 사용하여 Google Cloud에서 서비스 계정을 가장할 수 있습니다.

AWS 보안 사용자 인증 정보를 사용하려면 AWS 계정을 신뢰하도록 워크로드 아이덴티티 풀을 구성해야 합니다. 그러면 이 AWS 계정에 대해 발급된 보안 토큰이 워크로드 아이덴티티 제휴에서 인식되고 토큰을 사용하여 단기 서비스 계정 사용자 인증 정보를 얻을 수 있습니다.

Azure

Azure 사용자 및 서비스 주 구성원은 Azure AD 액세스 토큰을 사용하여 Google Cloud에서 서비스 계정을 가장할 수 있습니다.

Azure AD 액세스 토큰을 사용하려면 Azure AD 애플리케이션을 신뢰하도록 워크로드 아이덴티티 풀을 구성해야 합니다. 그러면 이 애플리케이션에 발급된 액세스 토큰이 워크로드 아이덴티티 제휴에서 인식되고 토큰을 사용해서 단기 서비스 계정 사용자 인증 정보를 얻을 수 있습니다.

Azure AD에서 새 애플리케이션을 만들고 이 애플리케이션을 Google Cloud 사용자 인증 정보를 가져오는 데만 사용하는 것이 가장 좋습니다.

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

  2. 애플리케이션의 애플리케이션 ID URI를 설정합니다.

    애플리케이션 ID URI를 설정할 때는 기본적으로 api://<appid>로 설정됩니다. 나중에 워크로드 아이덴티티 풀 제공업체 및 사용자 인증 정보 파일을 만들 때 필요하므로 URI를 기록해 둡니다.

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

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

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

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

GitHub Actions

GitHub Actions 워크플로가 GitHub OIDC 토큰을 사용하여 Google Cloud에서 서비스 계정을 가장하도록 할 수 있습니다.

이러한 토큰의 사용을 허용하려면 GitHub에서 발급한 OIDC 토큰을 신뢰하도록 워크로드 아이덴티티 풀을 구성해야 합니다. 워크로드에 대해 발급된 ID 토큰이 워크로드 아이덴티티 제휴에서 인식되고 토큰을 사용해서 단기 서비스 계정 사용자 인증 정보를 얻을 수 있습니다.

OIDC

ID 토큰 또는 OIDC 준수 ID 공급업체에서 발급한 JSON 웹 토큰 형식의 액세스 토큰를 사용하여 사용자와 애플리케이션이 Google Cloud에서 서비스 계정을 가장하도록 할 수 있습니다.

이러한 토큰을 사용하려면 외부 ID 공급업체를 신뢰하도록 워크로드 아이덴티티 풀을 구성해야 합니다. 그러면 외부 ID 공급업체에서 발급된 토큰이 워크로드 아이덴티티 제휴에서 인식되고, 토큰을 사용하여 단기 서비스 계정 사용자 인증 정보를 얻을 수 있습니다.

워크로드 아이덴티티 제휴를 사용하려면 인터넷을 통해 ID 공급업체의 OIDC 메타데이터 URI에 공개적으로 액세스할 수 있어야 하고 엔드포인트 ISSUER/.well-known/openid-configuration을 사용합니다. 여기서 ISSUER는 토큰의 발급기관(iss) 클레임 값입니다. Google Cloud는 메타데이터 엔드포인트를 쿼리하여 제공업체의 JSON 웹 키 세트(JWKS)를 가져온 다음 이 키 세트를 사용하여 토큰을 검증합니다.

ID 토큰에 사용자 ID가 반영되기 때문에 일반적으로 토큰 교환을 수행할 때 ID 토큰을 사용하는 것이 가장 좋습니다. 대신 액세스 토큰을 사용하도록 결정하는 경우에는 Google Cloud 사용자 인증 정보를 얻기 위한 단일 목적으로 ID 공급업체에서 전용 애플리케이션 또는 리소스를 구성합니다.

기본적으로 워크로드 아이덴티티 제휴에는 다음 URL을 잠재고객(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를 사용해야 합니다.

워크로드 아이덴티티 풀 및 공급업체를 만들 때 허용된 잠재고객의 커스텀 목록을 지정할 수 있습니다.

OIDC(AD FS)

Active Directory 사용자는 Active Directory Federation Services(AD FS)의 OIDC 액세스 토큰을 사용하여 Google Cloud에서 서비스 계정을 가장할 수 있습니다.

애플리케이션에서 AD FS 액세스 토큰을 요청하고 이러한 토큰을 사용하여 Google Cloud에 액세스하도록 하려면 AD FS에 애플리케이션 등록 두 개가 필요합니다.

  1. 기본 애플리케이션 또는 서버 애플리케이션 유형의 애플리케이션 등록

  2. Google Cloud의 워크로드 아이덴티티 풀 제공업체에 해당하는 Web API 유형의 애플리케이션 등록

그런 다음 Web API에 발급된 액세스 토큰을 허용하도록 워크로드 아이덴티티 공급업체를 구성합니다.

Windows 통합 인증 사용

워크로드 아이덴티티 제휴를 Windows 통합 인증(IWA)과 결합할 수 있습니다. IWA를 사용하면 Active Directory 애플리케이션에서 Kerberos 또는 NTLM 사용자 인증 정보를 사용하여 AD FS에 인증할 수 있습니다. 워크로드 아이덴티티 제휴와 IWA를 결합하면 AD FS 클라이언트 사용자 인증 정보 및 서비스 계정 키를 저장하고 관리할 필요가 없습니다.

IWA를 사용하려면 다음 기본 요건을 충족해야 합니다.

클라이언트 애플리케이션 등록

Windows Server 2019용 AD FS에 애플리케이션을 등록하려면 다음을 수행합니다.

  1. AD FS MMC 스냅인을 열고 애플리케이션 그룹으로 이동합니다.
  2. 애플리케이션 그룹 추가를 클릭합니다.
  3. 시작 페이지에서 클라이언트 이름을 입력하고 서버 애플리케이션을 선택합니다. 그런 다음 다음을 클릭합니다.
  4. 서버 애플리케이션 페이지에서 클라이언트 식별자(클라이언트 ID)와 리디렉션 URI를 입력합니다. client_credentials 부여 유형만 사용하려는 경우 리디렉션 URI는 사용되지 않으며 http://localhost/와 같은 URI를 사용할 수 있습니다. 그런 다음 다음을 클릭합니다.
  5. 애플리케이션 사용자 인증 정보 구성 페이지에서 클라이언트가 인증할 방법을 선택합니다. IWA를 사용하려면 Windows 통합 인증사용 설정됨으로 설정하고 애플리케이션이 실행되도록 구성된 도메인 사용자를 선택합니다. 그런 다음 다음을 클릭합니다.
  6. 요약 페이지에서 설정을 검토하고 다음을 클릭합니다.
  7. 닫기를 클릭하여 대화상자를 닫습니다.

워크로드 아이덴티티 제휴 풀의 웹 API 애플리케이션 만들기

Web API 유형의 다른 애플리케이션 등록을 만듭니다. 이 애플리케이션은 워크로드 아이덴티티 풀 제공업체에 해당하며 이 애플리케이션을 사용하여 Google Cloud와의 트러스트 관계를 설정합니다.

Windows Server 2019용 AD FS에서 애플리케이션을 만들려면 다음을 수행합니다.

  1. AD FS MMC 스냅인을 열고 애플리케이션 그룹으로 이동합니다.
  2. 애플리케이션 그룹 추가를 클릭합니다.
  3. 시작 페이지에서 Workload Identity Federation (test environment)과 같은 이름을 입력하고 Web API를 선택합니다. 그런 다음 다음을 클릭합니다.
  4. Web API 구성 페이지에서 Web API의 신뢰 당사자 식별자를 입력합니다.

    커스텀 신뢰 당사자 식별자를 정의하는 대신 다음 URI를 신뢰 당사자 식별자로 사용할 수 있습니다.

    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를 사용해야 합니다.

    이 형식은 신뢰 당사자 식별자가 워크로드 아이덴티티 풀 제공업체를 고유하게 식별하도록 합니다.

    나중에 워크로드 아이덴티티 풀 제공업체를 구성할 때 신뢰 당사자 식별자가 필요합니다.

  5. 다음을 클릭합니다.

  6. 액세스 제어 정책 적용 페이지에서 적절한 액세스 정책을 선택하고 다음을 클릭합니다.

  7. 애플리케이션 권한 구성 페이지에서 이전에 만든 클라이언트 애플리케이션을 추가합니다. 그런 다음 다음을 클릭합니다.

  8. 요약 페이지에서 설정을 검토하고 다음을 클릭합니다.

  9. 닫기를 클릭하여 대화상자를 닫습니다.

SAML

SAML 2.0 호환 ID 공급업체에서 발급된 어설션을 사용하여 Google Cloud에서 사용자 및 애플리케이션이 서비스 계정을 가장하도록 허용할 수 있습니다. 암호화된 어설션을 사용하는 제휴는 지원되지 않습니다.

워크로드 아이덴티티 풀 공급업체에 어설션을 https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID 형식의 대상으로 발급하도록 SAML ID 공급업체를 구성합니다.

이러한 어설션을 사용하려면 SAML ID 공급업체의 메타데이터 문서를 제공하여 외부 ID 공급업체를 신뢰하도록 워크로드 아이덴티티 풀을 구성해야 합니다.

그러면 워크로드 아이덴티티 제휴에서 외부 ID 공급업체에서 발급된 어설션이 인식되고, 토큰을 사용하여 단기 서비스 계정 사용자 인증 정보를 얻을 수 있습니다.

SAML(AD FS)

Active Directory Federation Services(AD FS)SAML 2.0 어설션을 사용하여 애플리케이션이 Google Cloud의 서비스 계정을 가장하도록 할 수 있습니다.

애플리케이션이 워크로드 아이덴티티 제휴에 사용할 수 있는 SAML 어설션을 AD FS에서 요청하도록 하려면 신뢰 당사자 트러스트를 만들어야 합니다. Windows Server 2019용 AD FS에서 신뢰 당사자 트러스트를 만들려면 다음을 수행합니다.

  1. AD FS MMC 스냅인을 열고 신뢰 당사자 트러스트로 이동합니다.
  2. 신뢰 당사자 트러스트 추가를 클릭합니다.
  3. 신뢰 당사자 트러스트 추가 마법사의 시작 페이지에서 클레임 인식을 선택하고 시작을 클릭합니다.
  4. 데이터 소스 선택 페이지에서 신뢰 당사자에 대한 데이터를 수동으로 입력을 선택합니다. 그런 다음 다음을 클릭합니다.
  5. 표시 이름 지정 페이지에서 트러스트 이름을 입력합니다. 그런 다음 다음을 클릭합니다.
  6. 인증서 구성 페이지에서 다음을 클릭합니다. 워크로드 아이덴티티 제휴는 암호화된 SAML 어설션을 지원하지 않으므로 암호화 인증서가 필요하지 않습니다.
  7. URL 구성 페이지에서 기본 설정을 유지하고 다음을 클릭합니다.
  8. 식별자 구성 페이지에서 신뢰 당사자 식별자를 입력합니다.

    커스텀 신뢰 당사자 식별자를 정의하는 대신 다음 URI를 신뢰 당사자 식별자로 사용할 수 있습니다.

    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를 사용해야 합니다.

    이 형식은 신뢰 당사자 식별자가 워크로드 아이덴티티 풀 제공업체를 고유하게 식별하도록 합니다.

    나중에 워크로드 아이덴티티 풀 제공업체를 구성할 때 신뢰 당사자 식별자가 필요합니다.

  9. 다음을 클릭합니다.

  10. 액세스 제어 정책 선택 페이지에서 적절한 액세스 제어 정책을 선택하고 다음을 클릭합니다.

  11. 트러스트 추가 준비 완료 페이지에서 설정을 검토하고 다음을 클릭합니다.

  12. 마침 페이지에서 닫기를 클릭하여 대화상자를 닫습니다.

워크로드 아이덴티티 제휴와 호환되도록 SAML 어설션에는 Active Directory 사용자를 고유하게 식별하는 클레임이 최소 하나 이상 포함되어야 합니다. 일반적으로 이 용도로 이름 ID 클레임을 사용하며 이는 SAML 어설션의 NameID 요소 값에 해당합니다.

SAML 어설션의 클레임 집합을 맞춤설정하려면 신뢰 당사자 트러스트의 클레임 발급 정책을 수정해야 합니다. 클레임 발급 정책을 수정하려면 다음을 수행합니다.

  1. 신뢰 당사자 트러스트 목록에서 방금 만든 트러스트를 선택하고 클레임 발급 정책 수정을 클릭합니다.
  2. 규칙 추가를 클릭합니다.
  3. 변환 클레임 규칙 추가 마법사의 규칙 유형 선택 페이지에서 수신 클레임 변환을 선택합니다. 그런 다음 다음을 클릭합니다.
  4. 클레임 규칙 구성 페이지에서 다음 설정을 구성합니다.

    • 클레임 규칙 이름: Name Identifier
    • 수신 클레임 유형: 기본 SID, UPN 또는 다른 클레임을 선택하여 제목을 고유하게 식별합니다.
    • 보내는 클레임 유형: 이름 ID
    • 보내는 이름 ID 형식: 미지정
  5. 모든 클레임 값 통과를 선택하고 마침을 클릭합니다.

  6. 필요한 경우 SAML 어설션에 더 많은 속성이 포함되도록 추가 규칙을 구성합니다.

  7. 확인을 클릭하여 클레임 발급 정책 대화상자를 닫습니다.

제휴 구성

외부 ID 공급업체와 제휴하려면 다음을 수행해야 합니다.

  1. 워크로드 아이덴티티 풀 및 공급업체를 포함할 Google Cloud 프로젝트를 준비합니다.
  2. ID 공급업체의 사용자 인증 정보를 외부 ID에 매핑하는 속성 매핑속성 조건(선택사항)을 정의합니다.
  3. 워크로드 아이덴티티 풀 및 공급업체를 만듭니다.

다음 섹션에서는 이러한 절차를 진행하는 방법을 안내합니다.

프로젝트 준비

워크로드 아이덴티티 풀 및 공급업체를 포함할 프로젝트를 선택하고 준비합니다.

  1. 프로젝트에 워크로드 아이덴티티 풀 관리자(roles/iam.workloadIdentityPoolAdmin) 및 서비스 계정 관리자(roles/iam.serviceAccountAdmin) 역할이 있는지 확인합니다.

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

  2. 제휴를 허용하도록 조직의 조직 정책을 업데이트합니다.

  3. API IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) 사용 설정

    API 사용 설정

속성 매핑 및 조건 정의

ID 공급업체의 사용자 인증 정보를 외부 ID에 매핑하는 속성 매핑속성 조건(선택사항)을 정의합니다.

외부 ID 공급업체에서 발급된 사용자 인증 정보에는 클레임이라고 부르는 하나 이상의 속성이 포함됩니다. 워크로드 아이덴티티 제휴는 이러한 속성을 어설션 속성으로 참조하고 여기에 assertion. 프리픽스를 추가합니다.

속성 매핑은 워크로드 아이덴티티 제휴로 인식된 사전 정의된 대상 속성에 어설션 속성을 매핑할 수 있게 해줍니다. 이러한 사전 정의된 대상 속성은 다음과 같습니다.

속성 설명
google.subject 필수. 사용자의 고유 식별자입니다. 이 속성은 IAM principal:// 역할 결합에 사용되며 Cloud Logging 로그에 표시됩니다. 값은 고유해야 하며 127자를 초과할 수 없습니다.
google.groups 선택사항. ID가 속하는 그룹 집합입니다. 이 속성은 IAM principalSet:// 역할 바인딩에서 그룹의 모든 구성원에게 액세스 권한을 부여하는 데 사용됩니다.
attribute.NAME 선택사항. 최대 50개의 커스텀 속성을 정의하고 IAM principalSet:// 역할 결합에서 이러한 속성을 사용하여 특정 속성이 있는 모든 ID에 액세스 권한을 부여할 수 있습니다.

속성 매핑에는 TARGET_ATTRIBUTE=SOURCE_EXPRESSION 형식이 사용됩니다. 다음 예를 참조하세요.

  • 이 매핑은 어설션 속성 subgoogle.subject에 할당합니다.

    google.subject=assertion.sub
    
  • 이 매핑은 Common Expression Language(CEL) 표현식을 사용하여 여러 어설션 속성을 연결합니다.

    google.subject="myprovider::" + assertion.aud + "::" + assertion.sub
    
  • 이 매핑은 다른 CEL 표현식을 사용하여 GUID 값 어설션 속성 workload_id를 이름에 매핑하고 결과를 attribute.my_display_name라는 커스텀 속성에 할당합니다.

    attribute.my_display_name={
      "8bb39bdb-1cc5-4447-b7db-a19e920eb111": "Workload1",
      "55d36609-9bcf-48e0-a366-a3cf19027d2a": "Workload2"
    }[assertion.workload_id]
    
  • 이 매핑은 ID의 Amazon 리소스 이름(ARN)에 따라 CEL 논리 연산자 및 함수를 사용하여 attribute.environment라는 커스텀 속성을 prod 또는 test로 설정합니다.

    attribute.environment=assertion.arn.contains(":instance-profile/Production") ? "prod" : "test"
    
  • 이 매핑은 extract 함수를 사용하여 가정된 역할의 이름(또는 역할이 가정되지 않은 경우 ID의 ARN)과 함께 커스텀 속성 aws_role을 입력할 수 있습니다.

    attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn
    

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

사용 사례에 적합한 속성 매핑 및 조건을 선택하려면 서비스 ID 또는 사용자 ID를 매핑할지 여부를 결정해야 합니다.

  • 서비스 ID를 매핑하여 Google Cloud 외부에서 실행되는 백그라운드 애플리케이션 또는 CI/CD 파이프라인을 사용 설정하여 Google Cloud에 대해 단기 사용자 인증 정보를 얻을 수 있습니다. 애플리케이션은 사용자 개입 없이 이러한 단기 사용자 인증 정보를 자체적으로 얻습니다.
  • 사용자 ID를 매핑하여 Google Cloud 외부에서 실행되는 애플리케이션 사용자가 Google Cloud에 대해 단기 사용자 인증 정보를 얻을 수 있도록 설정할 수 있습니다. 애플리케이션은 사용자 대신 이러한 단기 사용자 인증 정보를 얻습니다.

서비스 ID 매핑

AWS

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

  • account: AWS 계정 번호가 포함됩니다.
  • arn: 외부 항목의 AWS ARN이 포함됩니다.
  • userid: 호출 항목의 고유 식별자가 포함됩니다.

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

google.subject=assertion.arn
attribute.aws_role=assertion.arn.contains('assumed-role') ? assertion.arn.extract('{account_arn}assumed-role/') + 'assumed-role/' + assertion.arn.extract('assumed-role/{role_name}/') : assertion.arn

이 매핑을 사용하면 다음 식별자를 사용하여 특정 EC2 인스턴스에 또는 역할을 기준으로 서비스 계정을 가장할 수 있는 기능을 부여할 수 있습니다.

특정 EC2 인스턴스에 대한 액세스 권한을 부여합니다.

principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE/AWS_ROLE_SESSION_NAME

역할을 기준으로 액세스 권한을 부여합니다.

principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.aws_role/arn:aws:sts::ACCOUNT_ID:assumed-role/AWS_ROLE

AWS 계정에 많은 수의 사용자 및 역할이 포함될 수 있지만 이들 중 일부만 Google Cloud 리소스에 대한 액세스가 필요할 수 있습니다. 워크로드 아이덴티티 제휴를 사용할 수 있는 사용자 및 역할 집합을 제한하려면 속성 조건을 사용합니다. 예를 들어 다음 조건은 특정 계정이 Google Cloud 리소스에 액세스하도록 허용합니다.

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

Azure

속성 매핑은 커스텀 클레임을 포함하여 Azure 액세스 토큰에 포함된 클레임을 소스 속성으로 사용할 수 있습니다.

참조 가능한 클레임의 전체 목록을 얻으려면 관리형 ID가 할당된 Azure VM에 연결하고 다음을 수행합니다.

  1. 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로 바꿉니다.

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

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

서비스 주 구성원으로 인증하려면 다음 속성 매핑을 사용할 수 있습니다.

google.subject=assertion.sub

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

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

Google Cloud에 대해 단기 사용자 인증 정보를 얻을 수 있는 ID를 제어하려면 속성 조건을 정의하지 마세요. 대신 앱 역할 할당을 사용하도록 Azure AD 애플리케이션을 구성합니다.

GitHub Actions

속성 매핑은 OIDC 토큰에 포함된 클레임을 소스 속성으로 사용할 수 있습니다. 예를 들면 다음과 같습니다.

  • sub: 저장소 이름과 Git 참조를 포함합니다(예: repo:username/reponame:ref:refs/heads/master).
  • repository: 소유자 및 저장소 이름을 포함합니다(예: username/reponame).
  • repository_owner: 사용자 이름이나 GitHub 조직의 이름일 수 있는 소유자를 포함합니다.
  • ref: Git 참조를 포함합니다(예: refs/heads/main).

다음 속성 매핑은 GitHub Actions OIDC 토큰의 google.subjectsub 클레임으로 설정합니다. sub 클레임에는 저장소 이름과 Git 참조가 모두 포함되므로 이 매핑을 사용하면 저장소 및 분기별로 액세스를 제어할 수 있습니다.

google.subject=assertion.sub

저장소 및 분기별로 액세스를 제어하면 특정 분기(예: main)에서 다른 분기(예: 기능 분기)와 다른 리소스 액세스가 필요한 경우에 유용할 수 있습니다.

분기별로 액세스를 구별하지 않으려면 google.subjectrepository 클레임으로 설정하는 다음 속성 매핑을 사용할 수 있습니다.

google.subject=assertion.repository

선택적으로 속성 조건을 사용하여 ID 토큰이 충족해야 하는 추가 요구사항을 정의할 수 있습니다. 예를 들어 다음 조건은 Git 분기 main을 사용하는 워크플로의 ID 토큰에 대한 액세스를 제한합니다.

assertion.ref=='refs/heads/main'

OIDC

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

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

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

google.subject=assertion.sub

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

ID 공급업체에 많은 수의 사용자가 포함될 수 있지만 이들 중 일부만 Google Cloud 리소스에 대한 액세스가 필요할 수 있습니다. 워크로드 아이덴티티 제휴를 사용할 수 있는 사용자 및 사용자 인증 정보 집합을 제한하려면 선택적으로 속성 조건을 사용할 수 있습니다.

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

assertion.service_account==true

OIDC(AD FS)

속성 매핑은 AD FS 액세스 토큰에 포함된 클레임을 소스 속성으로 사용할 수 있습니다.

애플리케이션을 인증하려면 다음 속성 매핑을 사용하면 됩니다.

google.subject=assertion.appid

이 매핑은 google.subject를 AD FS 애플리케이션의 클라이언트 ID가 포함된 appid 클레임 값으로 설정합니다.

선택적으로 속성 조건을 사용하여 AD FS 액세스 토큰이 충족해야 하는 추가 요구사항을 정의할 수 있습니다. 예를 들어 다음 조건은 애플리케이션이 AD FS에 인증하려면 IWA를 사용해야 함을 정의합니다.

assertion.authmethod=='http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/windows'

애플리케이션 목록을 제어하려면 Google Cloud의 단기 사용자 인증 정보를 가져오면 됩니다. 속성 조건을 정의하지 마세요. 대신 AD FS의 클라이언트 권한을 사용하여 허용되는 애플리케이션을 정의합니다.

SAML

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

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

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

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

google.subject=assertion.subject

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

ID 공급업체에 많은 수의 사용자가 포함될 수 있지만 이들 중 일부만 Google Cloud 리소스에 대한 액세스가 필요할 수 있습니다. 워크로드 아이덴티티 제휴를 사용할 수 있는 사용자 및 사용자 인증 정보 집합을 제한하려면 선택적으로 속성 조건을 사용할 수 있습니다.

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

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

SAML(AD FS)

속성 매핑은 이 가이드의 앞부분에서 설명한 대로 AD FS에서 발행하는 어설션에 포함된 클레임을 사용할 수 있습니다.

다음 매핑을 사용하면 워크로드 아이덴티티 제휴에서 SAML 어설션의 이름 ID 클레임을 사용하여 사용자를 고유하게 식별할 수 있습니다.

google.subject=assertion.subject

SAML 어설션에 추가 클레임이 포함되도록 클레임 발급 정책을 구성한 경우 매핑을 추가할 수 있습니다. 예를 들면 다음과 같습니다.

google.groups=assertion.attributes['http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid']
attribute.userip=['http://schemas.microsoft.com/2014/09/requestcontext/claims/userip'][0]

원하는 경우 모든 SAML 어설션이 충족해야 하는 속성 조건을 사용할 수 있습니다. 예를 들어 다음 조건은 특정 그룹 멤버십 클레임이 포함된 SAML 어설션만 허용합니다.

"S-1-5-6" in google.groups

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

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

Console

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

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

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

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

  4. 공급업체 선택 드롭다운 목록에서 공급업체를 선택합니다.

    • AWS와 제휴하는 경우 AWS
    • OpenID Connect(OIDC): Azure, GitHub Actions 또는 다른 OIDC 호환 제공업체와 페더레이션된 경우
    • Cloud Console를 사용하여 SAML 2.0 ID 공급업체의 워크로드 아이덴티티 제휴를 구성할 수 없습니다. SAML 2.0 ID 공급업체의 워크로드 아이덴티티 제휴를 구성하려면 gcloud CLI를 사용해야 합니다.
  5. 공급업체 세부정보에서 ID 공급업체의 세부정보를 입력합니다.

    AWS

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

    Azure

    • 공급업체 이름: 공급업체의 이름입니다. 이 이름은 공급업체 ID로도 사용됩니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
    • 발급기관 URL: https://sts.windows.net/TENANT_ID이며, 여기서 TENANT_ID는 Azure AD 테넌트의 테넌트 ID(GUID)입니다.
    • 허용된 잠재고객: Azure AD에서 애플리케이션을 등록할 때 사용한 애플리케이션 ID URI입니다.

    GitHub Actions

    • 공급업체 이름: 공급업체의 이름입니다. 이 이름은 공급업체 ID로도 사용됩니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
    • 발급기관 URL: https://token.actions.githubusercontent.com/

    OIDC

    • 공급업체 이름: 공급업체의 이름입니다. 이 이름은 공급업체 ID로도 사용됩니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
    • 발급기관 URL: ID 공급업체의 발급기관 URL입니다.
    • 허용된 잠재고객: ID 토큰의 예상 잠재고객입니다.

    OIDC(AD FS)

    • 공급업체 이름: 공급업체의 이름입니다. 이 이름은 공급업체 ID로도 사용됩니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.
    • 발급기관 URL: https://ADFS_DOMAIN/adfs. 여기서 ADFS_DOMAIN은 AD FS 서버나 팜의 공개 도메인 이름입니다.
  6. 계속을 클릭합니다.

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

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

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

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

    gcloud iam workload-identity-pools providers create-aws PROVIDER_ID \
      --location="global"  \
      --workload-identity-pool="POOL_ID" \
      --account-id="AWS_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

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="https://sts.windows.net/TENANT_ID" \
        --allowed-audiences="APPLICATION_ID_URI" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="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"
    

    GitHub Actions

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="https://token.actions.githubusercontent.com/" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    다음 값을 바꿉니다.

    • PROVIDER_ID: 공급업체의 고유 ID입니다.
    • POOL_ID: 풀의 ID입니다.
    • OWNER: 저장소를 소유하는 사용자 또는 조직의 이름입니다.
    • REPOSITORY: 저장소 이름입니다.
    • MAPPINGS: 쉼표로 구분된 이전에 식별한 속성 매핑의 목록입니다.
    • CONDITIONS: 이전에 식별한 속성 조건입니다. 속성 조건이 없는 경우 매개변수를 삭제하세요.

    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"
    

    다음 값을 바꿉니다.

    • PROVIDER_ID: 공급업체의 고유 ID입니다.
    • POOL_ID: 풀의 ID입니다.
    • ISSUER: OIDC 메타데이터에 정의된 발급자 URI입니다.
    • AUDIENCE: ID 토큰의 예상 대상입니다. 많은 공급업체의 경우 대상이 클라이언트 ID와 일치합니다.
    • MAPPINGS: 쉼표로 구분된 이전에 식별한 속성 매핑의 목록입니다.
    • CONDITIONS: 이전에 식별한 속성 조건입니다. 속성 조건이 없는 경우 매개변수를 삭제하세요.

    OIDC(AD FS)

    gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --issuer-uri="https://ADFS_DOMAIN/adfs" \
        --allowed-audiences="RELYING_PARTY_ID" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    다음 값을 바꿉니다.

    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 ID 공급업체의 IdP 메타데이터 문서를 얻기 위한 로컬 파일 경로입니다.
    • MAPPINGS: 쉼표로 구분된 이전에 식별한 속성 매핑의 목록입니다.
    • CONDITIONS: 이전에 식별한 속성 조건입니다. 속성 조건이 없는 경우 매개변수를 삭제하세요.

    예:

    gcloud iam workload-identity-pools providers create-saml example-provider \
        --location="global" \
        --workload-identity-pool="pool-1" \
        --idp-metadata-path="/path/to/idp_metadata.xml" \
        --attribute-mapping="google.subject=assertion.subject,google.groups=assertion.attributes.groups"
    

    다음 오류가 표시되는 경우:

    INVALID_ARGUMENT: Invalid WorkloadIdentityPoolProvider IDP configuration: PROVIDERCONFIG_NOT_SET.
    

    SAML 미리보기 액세스 요청 페이지에 설명된 단계를 완료했는지 확인합니다.

    SAML(AD FS)

    curl -O https://DOMAIN/federationmetadata/2007-06/federationmetadata.xml
    
    gcloud iam workload-identity-pools providers create-saml PROVIDER_ID \
        --location="global" \
        --workload-identity-pool="POOL_ID" \
        --idp-metadata-path="federationmetadata.xml" \
        --attribute-mapping="MAPPINGS" \
        --attribute-condition="CONDITIONS"
    

    다음을 바꿉니다.

    예:

    gcloud iam workload-identity-pools providers create-saml example-provider \
        --location="global" \
        --workload-identity-pool="pool-1" \
        --idp-metadata-path="federationmetadata.xml" \
        --attribute-mapping=google.subject=assertion.subject"
    

    다음 오류가 표시되는 경우:

    INVALID_ARGUMENT: Invalid WorkloadIdentityPoolProvider IDP configuration: PROVIDERCONFIG_NOT_SET.
    

    SAML 미리보기 액세스 요청 페이지에 설명된 단계를 완료했는지 확인합니다.

다음 단계