OIDC ID 공급업체에서 리소스 액세스

이 문서에서는 ID 제휴를 사용하여 OpenID Connect(OIDC)를 지원하는 ID 공급업체에서 Google Cloud 리소스에 액세스하는 방법을 설명합니다.

일반적으로 Google Cloud 외부에서 실행되는 애플리케이션이 Google Cloud 리소스에 액세스하려면 서비스 계정 키를 사용합니다. ID 제휴를 사용하면 외부 ID가 서비스 계정을 가장할 수 있습니다. 이를 통해 워크로드가 단기 액세스 토큰을 사용하여 Google Cloud 리소스에 직접 액세스할 수 있으며 서비스 계정 키와 관련된 유지보수 및 보안 부담이 사라집니다.

시작하기 전에

  1. IAM, Resource Manager, Service Account Credentials, and Security Token Service (STS) API를 사용 설정합니다.

    API 사용 설정

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

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

  3. ID 공급업체에서 제휴를 허용하도록 조직의 조직 정책을 업데이트합니다.

  4. Google Cloud 서비스 계정을 만듭니다.

  5. 워크로드에 필요한 Google Cloud API를 호출할 수 있는 액세스 권한을 서비스 계정에 부여합니다.

OIDC의 ID 공급업체 설정

워크로드 아이덴티티 풀에 OIDC ID 공급업체를 추가할 때는 다음을 제공해야 합니다.

  • 공급업체의 ID

  • 공급업체의 발급기관 URI 일반적으로 https://example.com 형식을 사용합니다. URI를 찾으려면 공급업체의 OIDC 통합 관련 문서를 참조하세요.

  • 외부 토큰에 대한 클레임을 Google 토큰의 속성에 매핑하는 속성 매핑 목록. assertion을 사용하여 외부 사용자 인증 정보를 나타내고 Google 속성에는 google을, 커스텀 속성에는 attribute를 사용합니다.

    Google 속성에는 google.subjectgoogle.groups 등 두 가지가 있습니다. IAM 역할 결합에서 이러한 속성을 참조할 수 있습니다. google.subject는 Cloud Logging 로그 항목에도 표시됩니다.

    google.subject에 대한 매핑을 제공해야 합니다. 일반적으로 assertion.sub에 매핑하는 것이 좋습니다. 이렇게 하면 IAM 역할 binding에 사용할 수 있는 안정적인 식별자가 제공됩니다. 매핑은 다음과 같습니다.

    google.subject=assertion.sub
    

    좀 더 복잡한 어설션의 경우 Common Expression Language를 사용하면 됩니다. 예를 들어 워크로드 아이덴티티 풀에 여러 ID 공급업체가 포함된 경우 프리픽스를 추가하여 ID를 구별할 수 있습니다.

    google.subject="provider-a::" + assertion.sub
    

    google.subject 필드의 내용은 127자를 초과할 수 없습니다.

    커스텀 속성을 지정할 수도 있습니다. 예를 들어 다음은 assertion.fooattribute.bar에 매핑합니다.

    attribute.bar=assertion.foo
    

    참조할 수 있는 전체 클레임 목록은 액세스 토큰에 대한 공급업체의 문서를 참조하세요.

    표현식의 클레임 특정 부분을 참조하려면 제공된 템플릿에 따라 클레임에서 값을 추출하는 CEL extract() 함수를 사용합니다. extract()에 대한 자세한 내용은 속성에서 값 추출을 참조하세요.

    사용자 인증 정보에 클레임이 포함되어 있는지 확인하려면 has() 함수를 사용합니다.

  • 외부 사용자 인증 정보의 aud 필드에 포함될 수 있는 값을 지정하는 허용되는 잠재고객 목록. 최대 256자의 잠재고객을 최대 10개까지 구성할 수 있습니다. aud의 기본값에 대한 자세한 내용은 공급업체의 문서를 참조하세요.

    또는 ID 공급업체에서 aud의 커스텀 값을 구성할 수 있도록 허용하는 경우 허용되는 잠재고객 매개변수를 비워두고 aud 값을 워크로드 아이덴티티 공급업체 전체 리소스 이름으로 설정할 수 있습니다. HTTP 프리픽스는 선택사항입니다. 예를 들면 다음과 같습니다.

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

    두 경우 모두 허용되는 값 중 하나가 포함되지 않은 토큰 교환 요청은 거부됩니다.

또한 몇 가지 선택적 매개변수를 제공할 수 있습니다.

  • 표시 이름설명

  • 주 구성원이 있어야 하는 속성을 지정하는 속성 조건. 외부 사용자 인증 정보에 또는 Google 사용자 인증 정보 속성에 대한 클레임에 속성 조건을 적용할 수 있습니다. 속성 조건을 충족하지 않는 요청은 거부됩니다.

    속성 조건 형식은 부울을 반환하는 CEL 표현식으로 지정됩니다. 예를 들어 다음은 특정 그룹의 구성원이 아닌 모든 ID의 요청을 거부합니다.

    GROUP in assertion.groups
    

    일반 대중이 ID 공급업체를 사용할 수 있는 경우에는 속성 조건을 사용하는 것이 좋습니다. 일반적인 사용 사례에 대한 상세 내용은 속성 조건을 참조하세요.

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

워크로드 아이덴티티 풀을 사용하여 외부 ID를 구성 및 관리할 수 있습니다. 워크로드 아이덴티티 풀은 서로 분리되어 있지만 풀 하나가 수에 상관없이 서비스 계정을 가장할 수 있습니다. 일반적으로 개발, 스테이징 또는 프로덕션과 같은 환경마다 새로운 풀을 만드는 것이 좋습니다.

새 워크로드 아이덴티티 풀을 만들려면 ID를 제공해야 합니다. 원하는 경우 설명표시 이름을 제공할 수도 있습니다. ID는 gcp-로 시작할 수 없습니다. 이 프리픽스는 Google에서 사용하도록 예약되어 있습니다.

워크로드 아이덴티티 풀을 만든 후 워크로드 아이덴티티 풀 공급업체를 추가할 수 있습니다. 각 워크로드 아이덴티티 풀 공급업체는 특정 ID 공급업체를 나타냅니다. 하나의 풀에는 여러 공급업체가 포함될 수 있습니다. 공급업체를 만들려면 이 페이지에서 OIDC용 ID 공급업체 설정에 설명된 정보가 필요합니다.

콘솔

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

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

  2. 워크로드 아이덴티티 풀의 이름을 입력합니다.

    Cloud Console은 이 이름을 사용하여 풀 ID를 만듭니다. 풀 ID를 변경하려면 수정을 클릭합니다. 나중에 풀 ID를 변경할 수 없습니다.

  3. 선택사항: 워크로드 아이덴티티 풀에 대한 설명을 입력합니다.

  4. 계속을 클릭합니다.

  5. 공급업체 선택 드롭다운 목록에서 OpenID Connect(OIDC)를 선택한 후 계속을 클릭합니다.

  6. 공급업체 이름을 입력합니다.

    Cloud Console은 이 이름을 사용하여 공급업체 ID를 만듭니다. 공급업체 ID를 변경하려면 수정을 클릭합니다. 나중에 이 공급업체 ID를 변경할 수 없습니다.

  7. 공급업체의 발급기관 URL을 입력한 다음 계속을 클릭합니다.

  8. 속성 매핑을 구성하려면 매핑 수정을 클릭합니다.

    속성 매핑을 사용하면 외부 ID 정보를 사용하여 해당 ID의 하위 집합에 대해 액세스를 부여할 수 있습니다. OIDC ID 공급업체의 경우 google.subjectassertion.sub로 매핑하는 것이 좋습니다. 다른 매핑은 선택사항입니다.

    자세한 내용은 이 페이지의 OIDC의 ID 공급업체 설정을 참조하세요.

  9. 선택사항: 인증 가능한 ID를 지정하는 속성 조건을 제공하려면 조건 추가를 클릭하고 올바른 Common Expression Language(CEL) 표현식을 입력합니다. 자세한 내용은 속성 조건을 참조하세요.

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

gcloud

워크로드 아이덴티티 풀을 만들려면, gcloud iam workload-identity-pools create 명령어를 사용합니다.

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

응답은 다음과 같습니다.

Created workload identity pool [POOL_ID].

워크로드 아이덴티티 풀 공급업체를 추가하려면 gcloud iam workload-identity-pools providers create-oidc 명령어를 사용합니다.

gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \
    --workload-identity-pool="POOL_ID" \
    --issuer-uri="ISSUER_URI" \
    --location="global" \
    --attribute-mapping="google.subject=assertion.sub"

응답은 다음과 같습니다.

Created workload identity pool provider [PROVIDER_ID].

REST

워크로드 아이덴티티 풀을 만들려면 다음을 수행합니다.

projects.locations.workloadIdentityPools.create 메서드는 워크로드 아이덴티티 풀을 만듭니다.

HTTP 메서드 및 URL:

POST https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools?workloadIdentityPoolId=pool-id

JSON 요청 본문:

{
  "description": "description",
  "display-name": "display-name"
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

이 메서드는 다음과 비슷한 장기 실행 Operation을 반환합니다.

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/operations/operation-id"
}

워크로드 아이덴티티 풀 공급업체를 추가하려면 다음을 수행합니다.

projects.locations.workloadIdentityPools.providers.create 메서드는 OIDC ID 공급업체를 추가합니다.

HTTP 메서드 및 URL:

POST https://iam.googleapis.com/v1/projects/project-id/locations/global/workloadIdentityPools/pool-id/providers?workloadIdentityPoolProviderId=provider-id

JSON 요청 본문:

{
  "issuerUrl": "issuer-uri"
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

이 메서드는 다음과 비슷한 장기 실행 Operation을 반환합니다.

{
  "name": "projects/project-number/locations/global/workloadIdentityPools/pool-id/providers/provider-id/operations/operation-id"
}

외부 ID의 서비스 계정 가장 허용

외부 ID는 대부분의 Google Cloud 리소스에 직접 액세스할 수 없습니다. 대신 ID를 서비스 계정의 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)에 부여하여 서비스 계정을 가장할 수 있습니다. 외부 ID가 서비스 계정을 가장하면 서비스 계정과 동일한 역할 및 권한을 가집니다.

외부 ID에 워크로드 아이덴티티 사용자 역할을 부여하려면 다음을 수행합니다.

콘솔

워크로드 아이덴티티 사용자 역할을 부여하기 전에 서비스 계정을 가장할 ID를 결정합니다. 워크로드 아이덴티티 풀의 모든 ID에 역할을 부여하거나 속성 매핑에 따라 이러한 ID의 하위 집합에 역할을 부여할 수 있습니다.

ID 속성 이름 속성 값
단일 ID subject SUBJECT_NAME
특정 속성값의 모든 ID ATTRIBUTE_NAME ATTRIBUTE_VALUE

그런 다음 서비스 계정에 대한 액세스 권한을 부여하고 필요에 따라 사용자 인증 정보를 자동으로 생성하기 위한 구성 파일을 다운로드합니다.

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

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

  2. 외부 ID가 포함된 워크로드 아이덴티티 풀을 찾은 후 수정 아이콘을 클릭합니다. Cloud Console은 워크로드 아이덴티티 풀에 대한 세부정보를 보여줍니다.

  3. 액세스 권한 부여를 클릭합니다.

  4. 서비스 계정 드롭다운 목록에서 외부 ID가 가장할 서비스 계정을 선택합니다.

  5. 풀에서 서비스 계정을 가장할 수 있는 ID를 선택합니다.

    모든 ID가 서비스 계정을 가장하도록 허용하려면 풀의 모든 ID를 선택합니다.

    ID의 하위 집합이 서비스 계정을 가장하도록 허용하려면 필터와 일치하는 ID만 선택한 후 다음을 수행합니다.

    1. 속성 이름 드롭다운 목록에서 평가하려는 속성을 선택합니다.

      매핑된 속성만 목록에 표시됩니다. google.attribute. 프리픽스는 표시되지 않습니다.

    2. 속성값 필드에서 예상되는 속성값을 입력합니다.

  6. 저장을 클릭합니다.

    ID에 이미 서비스 계정에 대한 액세스 권한이 있는 경우 Cloud Console에 워크로드 아이덴티티 풀에 대한 세부정보가 표시됩니다. 나머지 단계는 건너뛸 수 있습니다.

    ID에 서비스 계정에 대한 액세스 권한이 부여되면 Cloud Console에 애플리케이션 구성 대화상자가 표시됩니다.

  7. 선택사항: 사용자 인증 정보 자동 생성을 위해 구성 파일을 다운로드하려면 다음을 수행합니다.

    1. 공급업체 드롭다운 목록에서 서비스 계정을 가장할 외부 ID가 포함된 공급업체를 선택합니다.

    2. 구성 다운로드를 클릭하여 JSON 구성 파일을 다운로드합니다.

  8. 닫기를 클릭합니다.

gcloud

워크로드 아이덴티티 사용자 역할을 부여하기 전에 서비스 계정을 가장할 ID를 결정합니다. 워크로드 아이덴티티 풀의 모든 ID에 역할을 부여하거나 속성 매핑에 따라 이러한 ID의 하위 집합에 역할을 부여할 수 있습니다.

ID 식별자 형식
단일 ID principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_NAME
특정 속성값의 모든 ID principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
풀의 모든 ID principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

그런 다음 gcloud iam service-accounts add-iam-policy-binding 명령어를 실행합니다.

gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_EMAIL \
    --role=roles/iam.workloadIdentityUser \
    --member="PRINCIPAL"

다음 값을 바꿉니다.

  • SERVICE_ACCOUNT_EMAIL: 서비스 계정의 이메일 주소입니다.
  • PRINCIPAL: 서비스 계정을 가장할 외부 ID입니다.

REST

워크로드 아이덴티티 사용자 역할을 부여하기 전에 서비스 계정을 가장할 ID를 결정합니다. 워크로드 아이덴티티 풀의 모든 ID에 역할을 부여하거나 속성 매핑에 따라 이러한 ID의 하위 집합에 역할을 부여할 수 있습니다.

ID 식별자 형식
단일 ID principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/SUBJECT_NAME
특정 속성값의 모든 ID principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.ATTRIBUTE_NAME/ATTRIBUTE_VALUE
풀의 모든 ID principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/*

그런 후 읽기-수정-쓰기 패턴을 사용하여 정책을 업데이트합니다.

  1. 서비스 계정의 최신 IAM 정책을 읽습니다.
  2. 정책을 수정하여 역할을 부여합니다.
  3. 업데이트된 정책을 작성합니다.

서비스 계정의 IAM 정책을 읽습니다.

serviceAccounts.getIamPolicy 메서드는 서비스 계정의 IAM 정책을 가져옵니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다.
  • SA_ID: 서비스 계정의 ID입니다. SA_NAME@PROJECT_ID.iam.gserviceaccount.com 형식의 서비스 계정 이메일 주소이거나 서비스 계정의 고유 숫자 ID일 수 있습니다.

  • POLICY_VERSION: 반환할 정책 버전입니다. 요청에는 정책 버전 3인 최신 정책 버전이 지정되어야 합니다. 자세한 내용은 정책을 가져올 때 정책 버전 지정을 참조하세요.

HTTP 메서드 및 URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:getIamPolicy

JSON 요청 본문:

{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

다음과 비슷한 JSON 응답이 표시됩니다.

{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

기존 정책이 없는 경우 응답에 기본 etag만 포함됩니다. 이 응답을 받으면 version 필드를 추가하고 3으로 설정하고 bindings 필드를 빈 배열로 설정합니다.

적절한 역할을 주 구성원에 부여하도록 정책을 수정합니다.

역할을 부여하려면 응답 본문에서 bindings 배열을 수정합니다.

  • 역할에 대한 바인딩이 없으면 부여하려는 역할과 이를 부여할 주 구성원을 정의하는 bindings 배열에 새 객체를 추가합니다.
  • 역할에 대한 바인딩이 있으면 새 주 구성원을 기존 주 구성원 목록에 추가합니다.

:

풀의 모든 ID에 워크로드 아이덴티티 사용자 역할(roles/iam.workloadIdentityUser)을 부여하려면 이전 단계의 예를 다음과 같이 변경하세요.

{
  "version": 1,
  "etag": "BwUqLaVeua8=",
  "bindings": [
    {
      "role": "roles/iam.workloadIdentityUser",
      "members": [
        "principalSet://iam.googleapis.com/projects/1234567890123/locations/global/workloadIdentityPools/my-pool/*"
      ]
    },
    {
      "role": "roles/iam.serviceAccountAdmin",
      "members": [
        "user:admin@example.com"
      ]
    }
  ]
}

업데이트된 정책을 작성합니다.

serviceAccounts.setIamPolicy 메서드는 서비스 계정에 업데이트된 IAM 정책을 설정합니다.

요청 데이터를 사용하기 전에 다음을 바꿉니다.

  • PROJECT_ID: Google Cloud 프로젝트 ID. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다.
  • SA_ID: 서비스 계정의 ID입니다. SA_NAME@PROJECT_ID.iam.gserviceaccount.com 형식의 서비스 계정 이메일 주소이거나 서비스 계정의 고유 숫자 ID일 수 있습니다.

  • POLICY: 설정하려는 정책의 JSON 표현입니다. 정책 형식에 대한 자세한 내용은 정책 참조를 확인하세요.

    예를 들어 이전 단계에 표시된 정책을 설정하려면 policy를 다음으로 바꿉니다.

    {
      "version": 1,
      "etag": "BwUqLaVeua8=",
      "bindings": [
        {
          "role": "roles/iam.workloadIdentityUser",
          "members": [
            "principalSet://iam.googleapis.com/projects/1234567890123/locations/global/workloadIdentityPools/my-pool/*"
          ]
        },
        {
          "role": "roles/iam.serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

HTTP 메서드 및 URL:

POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID:setIamPolicy

JSON 요청 본문:

{
  "policy": POLICY
}

요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

응답에는 업데이트된 정책이 포함됩니다.

Google 사용자 인증 정보 생성

지원되는 클라이언트 라이브러리를 사용하는 경우 자동으로 Google 사용자 인증 정보가 생성되도록 클라이언트 라이브러리를 구성할 수 있습니다. 또는 OIDC ID 토큰을 수동으로 생성한 후 토큰을 Google 사용자 인증 정보로 교환할 수 있습니다.

가능하면 토큰 교환 프로세스를 직접 구현할 필요가 없도록 사용자 인증 정보를 자동으로 생성하는 것이 좋습니다.

자동으로 사용자 인증 정보 생성

다음 언어 중 하나의 클라이언트 라이브러리로 Google Cloud에 액세스하는 경우 ID 제휴를 사용하여 클라이언트 라이브러리가 자동으로 사용자 인증 정보를 생성하도록 구성할 수 있습니다.

C++

대부분의 C++용 Google Cloud 클라이언트 라이브러리grpc::GoogleDefaultCredentials()를 호출하여 생성된 ChannelCredentials 객체를 사용해 ID 제휴를 지원합니다. 이 사용자 인증 정보를 초기화하려면 클라이언트 라이브러리를 gRPC 버전 1.36.0 이상으로 빌드해야 합니다.

C++용 Cloud Storage 클라이언트 라이브러리는 gRPC가 아닌 REST API를 사용하므로 ID 제휴를 지원하지 않습니다.

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

자바

자바용 클라이언트 라이브러리에서 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 이상을 사용하면 ID 제휴가 지원됩니다.

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

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 패키지 사용자 가이드를 참조하세요.

사용자 인증 정보를 자동으로 생성하도록 클라이언트 라이브러리를 구성하려면 JSON 구성 파일을 만듭니다. Cloud Console 또는 gcloud 도구를 사용하여 이 파일을 만들 수 있습니다.

구성 파일은 클라이언트 라이브러리가 ID 공급업체에서 토큰을 가져오는 방법을 지정합니다. 클라이언트 라이브러리가 토큰을 가져오는 데에는 몇 가지 방법이 있습니다.

  • 파일 소스 사용자 인증 정보: 토큰이 파일에서 로드됩니다. 다른 프로세스가 이전 토큰이 만료되기 전에 새 OIDC 토큰을 사용하여 이 파일을 새로 고쳐야 합니다. 예를 들어 토큰 수명이 1시간이면 파일을 1시간 전에 새로 고쳐야 합니다.
  • URL 소스 사용자 인증 정보: 토큰은 HTTP GET 요청에 응답하는 엔드포인트를 통해 로컬 서버에서 로드됩니다. 응답은 일반 텍스트 또는 JSON 형식의 OIDC ID 토큰이어야 합니다.

콘솔

먼저 이 페이지의 안내에 따라 외부 ID의 서비스 계정 가장을 허용합니다. 그런 후 외부 ID가 가장할 수 있는 모든 서비스 계정에 대해 JSON 구성 파일을 만들 수 있습니다.

JSON 구성 파일을 만들려면 다음을 수행합니다.

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

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

  2. 사용하려는 ID 공급업체가 포함된 워크로드 아이덴티티 풀을 찾은 후 수정 아이콘을 클릭합니다. Cloud Console은 워크로드 아이덴티티 풀에 대한 세부정보를 보여줍니다.
  3. 연결된 서비스 계정을 클릭합니다.
  4. 사용하려는 서비스 계정을 찾은 후 다운로드를 클릭합니다.
  5. 공급업체 드롭다운 목록에서 서비스 계정을 가장할 OIDC ID를 포함하는 공급업체를 선택합니다.
  6. OIDC ID 토큰 경로 상자에 다음 중 하나를 입력합니다.

    • 파일 소스 사용자 인증 정보: OIDC ID 토큰이 저장되는 파일 경로입니다.
    • URL 소스 사용자 인증 정보: HTTP GET 요청에 대한 응답으로 OIDC ID 토큰을 제공하는 URL입니다.
  7. 형식 유형 드롭다운 목록에서 텍스트 형식에 대해 txt, JSON 형식에 대해 json을 선택합니다.

    json을 선택한 경우 제목 토큰 필드 이름 상자의 값이 토큰을 포함하는 JSON 필드 이름과 일치하는지 확인합니다. 필요에 따라 값을 업데이트합니다.

  8. 구성 다운로드를 클릭하여 JSON 구성 파일을 다운로드한 다음 완료를 클릭합니다.

URL 소스 사용자 인증 정보를 사용 중인 경우 요청에 특정 HTTP 헤더를 포함하려면 구성 파일에 다음 헤더를 추가하면 됩니다.

  1. 텍스트 편집기에서 구성 파일을 열고 headers 필드를 찾습니다. 수정 결과가 다음과 비슷할 것입니다.

    "headers": {},
    
  2. HTTP 헤더를 headers 객체에 키-값 쌍으로 추가합니다. 각 키 및 값을 큰따옴표로 묶어야 합니다.

    예를 들어 값이 testX-Example-One 헤더와 값이 exampleX-Example-Two 헤더를 전송하려면 다음을 추가합니다.

    "headers": {
      "X-Example-One": "test",
      "X-Example-Two": "example"
    },
    
  3. 변경 사항을 구성 파일에 저장합니다.

gcloud

파일 소스 사용자 인증 정보를 사용하려면 gcloud iam workload-identity-pools create-cred-config 명령어를 실행하여 구성 파일을 생성합니다. --credential-source-type 플래그는 선택사항입니다. --credential-source-typejson이 아니면 --credential-source-field-name 플래그는 선택사항입니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --output-file=CONFIGURATION_FILEPATH \
    --credential-source-file=TOKEN_FILEPATH \
    --credential-source-type=SOURCE_TYPE \
    --credential-source-field-name=FIELD_NAME

다음 값을 바꿉니다.

  • PROJECT_NUMBER: 프로젝트의 숫자 ID입니다.
  • POOL ID: 워크로드 아이덴티티 풀의 ID입니다.
  • PROVIDER_ID: 워크로드 아이덴티티 풀 제공업체의 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: 가장하려는 서비스 계정의 이메일 주소입니다.
  • CONFIGURATION_FILEPATH: 구성 파일의 파일 경로입니다.
  • TOKEN_FILEPATH: OIDC ID 토큰이 저장될 파일 경로입니다.
  • SOURCE_TYPE: OIDC ID 토큰 파일 형식입니다. text 또는 json으로 설정합니다. 기본값은 text입니다.
  • FIELD_NAME: JSON 토큰 파일의 경우 토큰이 포함된 JSON 필드 이름입니다. --credential-source-typejson인 경우에 필요합니다.

URL 소스 사용자 인증 정보를 사용하려면 gcloud iam workload-identity-pools create-cred-config 명령어를 실행하여 구성 파일을 생성합니다. --credential-source-headers--credential-source-type 플래그는 선택사항입니다. --credential-source-typejson이 아니면 --credential-source-field-name 플래그는 선택사항입니다.

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID \
    --service-account=SERVICE_ACCOUNT_EMAIL \
    --output-file=CONFIGURATION_FILEPATH \
    --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: 프로젝트의 숫자 ID입니다.
  • POOL_ID: 워크로드 아이덴티티 풀의 ID입니다.
  • PROVIDER_ID: 워크로드 아이덴티티 풀 제공업체의 ID입니다.
  • SERVICE_ACCOUNT_EMAIL: 가장하려는 서비스 계정의 이메일 주소입니다.
  • CONFIGURATION_FILEPATH: 구성 파일의 파일 경로입니다.
  • TOKEN_URL: HTTP GET 요청에 대한 응답으로 OIDC ID 토큰을 제공하는 URL입니다.
  • KEY_1, KEY_2: 요청에 포함할 HTTP 헤더의 이름입니다.
  • VALUE_1, VALUE_2: 요청에 포함할 HTTP 헤더의 값입니다.
  • SOURCE_TYPE: OIDC 토큰 파일 형식입니다. text 또는 json으로 설정합니다. 기본값은 text입니다.
  • FIELD_NAME: JSON 토큰 파일의 경우 토큰이 포함된 필드 이름입니다. --credential-source-typejson인 경우에 필요합니다.

구성 파일을 생성한 후 환경 변수 GOOGLE_APPLICATION_CREDENTIALS를 구성 파일의 파일 경로로 설정합니다. 이 환경 변수는 클라이언트 라이브러리에 애플리케이션 기본 사용자 인증 정보를 사용하여 인증하도록 지시합니다. 자세한 내용은 사용자 인증 정보 자동으로 찾기를 참조하세요.

수동으로 사용자 인증 정보 교환

외부 ID가 서비스 계정을 가장할 수 있게 되면 수동으로 사용자 인증 정보를 Google 사용자 인증 정보로 교환할 수 있습니다.

사용자 인증 정보를 교환하려면 다음 안내를 따르세요.

  1. ID 공급업체에서 OIDC ID 토큰을 가져옵니다(자세한 내용은 ID 공급업체의 문서 참조).

  2. OIDC ID 토큰을 보안 토큰 서비스 token() 메서드에 전달하여 제휴 액세스 토큰을 가져옵니다.

    REST

    token 메서드는 타사 토큰을 Google 토큰으로 교환합니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_NUMBER: Google Cloud 프로젝트 번호입니다.
    • POOL_ID: 만든 워크로드 아이덴티티 풀의 ID입니다.
    • PROVIDER_ID: 구성한 ID 공급업체의 ID입니다.
    • ACCESS_TOKEN: ID 공급업체의 토큰입니다.

    HTTP 메서드 및 URL:

    POST https://sts.googleapis.com/v1/token

    JSON 요청 본문:

    {
      "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": "urn:ietf:params:oauth:token-type:jwt",
      "subjectToken": "ACCESS_TOKEN"
    }
    

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

     

    이 메서드는 제휴 토큰을 반환합니다.

  3. generateAccessToken()을 호출하여 제휴 토큰을 서비스 계정 액세스 토큰으로 교환합니다. 일부 Google Cloud APIs에서만 제휴 토큰을 지원하지만 모든 Google Cloud APIs에서 서비스 계정 액세스 토큰을 지원합니다.

    REST

    Service Account Credentials API의 serviceAccounts.generateAccessToken 메서드는 서비스 계정의 OAuth 2.0 액세스 토큰을 생성합니다.

    요청 데이터를 사용하기 전에 다음을 바꿉니다.

    • PROJECT_ID: Google Cloud 프로젝트 ID. 프로젝트 ID는 my-project 같은 영숫자 문자열입니다.
    • SA_ID: 서비스 계정의 ID입니다. SA_NAME@PROJECT_ID.iam.gserviceaccount.com 형식의 서비스 계정 이메일 주소이거나 서비스 계정의 고유 숫자 ID일 수 있습니다.
    • token: 제휴 액세스 토큰입니다.

    HTTP 메서드 및 URL:

    POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com:generateAccessToken

    JSON 요청 본문:

    {
      "scope": [
        "https://www.googleapis.com/auth/cloud-platform"
      ]
    }
    

    요청을 보내려면 다음 옵션 중 하나를 펼칩니다.

    generateAccessToken 요청이 성공하면 응답 본문에 OAuth 2.0 액세스 토큰과 만료 시간이 포함됩니다. 그런 다음 accessTokenexpireTime에 도달할 때까지 서비스 계정 대신 요청을 인증하는 데 사용할 수 있습니다.

    {
      "accessToken": "eyJ0eXAi...NiJ9",
      "expireTime": "2020-04-07T15:01:23.045123456Z"
    }
    

서비스 계정에 대한 액세스 토큰이 있으면 이 토큰을 통해 요청의 Authorization 헤더에 토큰을 포함하여 Google Cloud APIs를 호출할 수 있습니다.

Authorization: Bearer SERVICE_ACCOUNT_ACCESS_TOKEN

요청이 서비스 계정으로 승인됩니다.

다음 단계