서비스 계정을 사용하여 워크로드 인증

이 페이지에서는 서비스 계정을 사용하여 가상 머신(VM) 인스턴스에서 실행되는 앱이 Google Cloud API에 인증하고 리소스에 대한 액세스를 승인하도록 하는 방법을 설명합니다.

Compute Engine이 서비스 계정을 사용하는 방법에 대한 자세한 내용은 서비스 계정 개요를 참조하세요.

시작하기 전에

이 가이드의 명령줄 예시를 사용하려면 다음을 수행하세요.
1. 최신 버전의 Google Cloud CLI를 설치하거나 업데이트합니다.
2. 기본 리전 및 영역을 설정합니다.
이 가이드의 API 예시를 사용하려면 API 액세스를 설정합니다.
서비스 계정 개요를 읽어봅니다.

새 서비스 계정 만들기

IAM을 사용하여 새 서비스 계정을 만들고 설정할 수 있습니다. 계정을 만들면 계정에 IAM 역할을 한 개 이상 부여한 후 이 서비스 계정으로 실행되도록 가상 머신 인스턴스를 승인합니다.

콘솔

새 서비스 계정을 만들려면 다음 안내를 따르세요.

서비스 계정 만들기의 설명대로 새 서비스 계정을 만듭니다.
서비스 계정의 이메일을 가져옵니다. 이 서비스 계정으로 실행되도록 인스턴스를 설정하려면 이메일이 필요합니다. 콘솔에서 서비스 계정의 이메일을 확인합니다.
1. 서비스 계정 페이지로 이동합니다.
  
  서비스 계정으로 이동
2. 메시지가 표시되면 프로젝트를 선택합니다.
3. 새 서비스 계정을 찾아 서비스 계정 이메일을 기록해 둡니다.
일반적으로 서비스 계정의 이메일은 서비스 계정 ID에서 다음과 같은 형식으로 파생됩니다.

[SERVICE-ACCOUNT-NAME]@[PROJECT_ID].iam.gserviceaccount.com
서비스 계정에 IAM 역할을 부여합니다. 역할을 부여하지 않으면 서비스 계정을 통해 모든 서비스에 액세스할 수 없습니다. IAM 역할의 전체 목록은 IAM 문서의 역할 이해를 참조하세요.
그런 다음 서비스 계정으로 실행되도록 인스턴스를 설정합니다. 안내를 따라 서비스 계정으로 실행할 인스턴스를 설정합니다.

Terraform

google_service_account 리소스를 사용하여 서비스 계정을 만들 수 있습니다.

compute/service_account_for_instances/main.tf

GitHub에서 보기 의견 보내기

resource "google_service_account" "default" {
  account_id   = "service-account-id"
  display_name = "Service Account"
}

account_id 및 display_name 속성의 자리표시자 값을 바꿔야 합니다.

Terraform 구성을 적용하거나 삭제하는 방법은 기본 Terraform 명령어를 참조하세요.

서비스 계정으로 실행되도록 새 인스턴스 설정

새 서비스 계정을 만든 후 서비스 계정으로 실행되도록 새 가상 머신 인스턴스를 만들 수 있습니다. 서비스 계정이 인스턴스와 다른 프로젝트에 있으면 다른 프로젝트의 리소스에 서비스 계정을 구성해야 합니다.

기존 인스턴스의 서비스 계정을 할당하거나 변경하려면 인스턴스의 서비스 계정 및 액세스 범위 변경을 대신 참조하세요.

여러 가상 머신 인스턴스에서 동일한 서비스 계정을 사용 설정할 수 있지만, 가상 머신 인스턴스에는 서비스 계정 ID 하나만 있을 수 있습니다. 동일한 서비스 계정을 여러 가상 머신 인스턴스에 할당할 경우 나중에 서비스 계정을 변경하면 서비스 계정을 사용하는 인스턴스에 영향을 줍니다. 이러한 변경에는 서비스 계정에 부여된 IAM 역할의 변경도 포함됩니다. 예를 들어 역할을 삭제하면 서비스 계정을 사용하는 모든 인스턴스에서 이 역할로 부여된 권한이 손실됩니다.

일반적으로 대부분의 Cloud API에 대한 액세스를 허용하도록 cloud-platform 액세스 범위를 설정한 다음, 서비스 계정에 관련 IAM 역할만 부여할 수 있습니다. 가상 머신 인스턴스에 부여된 액세스 범위와 서비스 계정에 부여된 IAM 역할의 조합에 따라 서비스 계정에서 이 인스턴스에 액세스할 수 있는 양이 결정됩니다. 액세스 범위와 IAM 역할 모두에서 API 메서드가 허용되는 경우에만 서비스 계정에서 이 메서드를 실행할 수 있습니다.

또는 서비스에서 호출할 특정 API 메서드에 대한 액세스를 허용하는 특정 범위를 설정할 수 있습니다. 예를 들어 instances.insert 메서드를 호출하려면 이 메서드에 대한 액세스 권한을 부여하는 IAM 역할과 함께 https://www.googleapis.com/auth/compute 범위 또는 https://www.googleapis.com/auth/cloud-platform 범위의 승인이 필요합니다. cloud-platform 범위 대신 compute 범위를 설정할 수 있습니다. 이렇게 하면 서비스가 Compute Engine에서 메서드를 호출할 수 있는 승인이 제공되지만 Compute Engine 외부에서 API 메서드를 호출할 수 있는 승인은 제공되지 않습니다.

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하거나 API를 직접 호출하여 서비스 계정으로 실행할 새 인스턴스를 설정할 수 있습니다.

콘솔

인스턴스 만들기 페이지로 이동

인스턴스 만들기로 이동
VM 세부정보를 지정합니다.
ID 및 API 액세스 섹션의 드롭다운 목록에서 사용할 서비스 계정을 선택합니다.
VM 만들기 프로세스를 계속 진행합니다.

gcloud

Google Cloud CLI를 사용하여 새 인스턴스를 만들고 커스텀 서비스 계정으로 실행되도록 승인하려면 인스턴스에 서비스 계정 이메일과 원하는 액세스 범위를 제공합니다.

gcloud compute instances create [INSTANCE_NAME] \
    --service-account [SERVICE_ACCOUNT_EMAIL] \
    --scopes [SCOPES,...]

각 항목의 의미는 다음과 같습니다.

[SERVICE_ACCOUNT_EMAIL]은 사용할 서비스 계정 이메일입니다. 예를 들면 my-sa-123@my-project-123.iam.gserviceaccount.com입니다. 이메일을 모르는 경우 서비스 계정 이메일을 가져오는 방법을 살펴보세요.
[INSTANCE_NAME]은 인스턴스의 이름입니다.
[SCOPES]는 쉼표로 구분된 전체 범위 URI이거나 --scopes 플래그의 설명에서 제공된 범위 별칭의 목록입니다.

예를 들면 다음과 같습니다.

gcloud compute instances create example-vm \
    --service-account 123-my-sa@my-project-123.iam.gserviceaccount.com \
    --scopes https://www.googleapis.com/auth/cloud-platform

gcloud CLI도 범위가 더 긴 URI 대신 범위 별칭을 제공합니다 예를 들어 Cloud Storage에 대한 전체 액세스 범위는 https://www.googleapis.com/auth/devstorage.full_control이며, 이 범위의 별칭은 storage-full입니다.

instances create 페이지의 --scopes 플래그 설명에서 범위와 범위 별칭의 목록을 볼 수 있습니다. instances create 명령어의 도움말에도 이러한 범위와 별칭이 나열됩니다.

gcloud compute instances create --help

일반 범위 URI 지정과 동일한 방식으로 별칭을 지정합니다. 예를 들면 다음과 같습니다.

gcloud compute instances create [INSTANCE_NAME] \
    --service-account [SERVICE_ACCOUNT_EMAIL] \
    --scopes cloud-platform

Terraform

서비스 계정으로 실행되도록 새 인스턴스를 설정하려면 google_compute_instance 리소스를 사용하면 됩니다.

compute/service_account_for_instances/main.tf

GitHub에서 보기 의견 보내기

resource "google_compute_instance" "default" {
  name         = "my-test-vm"
  machine_type = "n1-standard-1"
  zone         = "us-central1-a"

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-11"
    }
  }

  // Local SSD disk
  scratch_disk {
    interface = "SCSI"
  }

  network_interface {
    network = "default"

    access_config {
      // Ephemeral public IP
    }
  }

  service_account {
    # Google recommends custom service accounts with `cloud-platform` scope with
    # specific permissions granted via IAM Roles.
    # This approach lets you avoid embedding secret keys or user credentials
    # in your instance, image, or app code
    email  = google_service_account.default.email
    scopes = ["cloud-platform"]
  }
}

API

API에서 인스턴스를 만들고 serviceAccounts 속성을 포함하는 표준 요청을 만듭니다. 서비스 계정 이메일을 가져오고 인스턴스에 원하는 액세스 범위와 함께 email 속성을 포함합니다.

POST https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances

{
  "machineType": "https://www.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/machineTypes/[MACHINE_TYPE]",
  "name": "[INSTANCE_NAME]",
  "serviceAccounts": [
   {
    "email": "[SERVICE_ACCOUNT_EMAIL]",
    "scopes": ["https://www.googleapis.com/auth/cloud-platform"]
   }
  ],
  ...
}

서비스 계정으로 실행되도록 인스턴스를 설정하면 인스턴스에서 실행되는 애플리케이션이 다음 방법 중 하나를 사용하여 인증을 수행할 수 있습니다.

대부분의 애플리케이션에서 다음 중 하나를 선택합니다.
- 애플리케이션 기본 사용자 인증 정보 및 클라이언트 라이브러리 사용
- gcloud 및 gsutil 명령어 사용
OAuth2 액세스 토큰이 필요한 애플리케이션의 경우 메타데이터 서버에서 직접 액세스 토큰을 요청하고 사용합니다.

서비스 계정 사용자 인증 정보를 사용하여 애플리케이션 인증

서비스 계정으로 실행되도록 인스턴스를 설정한 후 서비스 계정 사용자 인증 정보를 사용하여 인스턴스에서 실행 중인 애플리케이션을 인증할 수 있습니다.

클라이언트 라이브러리로 애플리케이션 인증

클라이언트 라이브러리에서는 애플리케이션 기본 사용자 인증 정보를 사용하여 Google API로 인증하고 이 API에 요청을 보낼 수 있습니다. 애플리케이션에서는 애플리케이션 기본 사용자 인증 정보를 통해 자동으로 여러 소스에서 사용자 인증 정보를 가져올 수 있으므로 애플리케이션 코드를 변경하지 않고 로컬에서 애플리케이션을 테스트한 다음 Compute Engine 인스턴스에 배포할 수 있습니다.

애플리케이션 기본 사용자 인증 정보 설정에 대한 자세한 내용은 애플리케이션 기본 사용자 인증 정보에 사용자 인증 정보 제공을 참조하세요.

이 예시에서는 Python 클라이언트 라이브러리를 사용하여 Cloud Storage API를 인증하고 프로젝트의 버킷을 나열하도록 요청합니다. 이 예시에서는 다음 절차를 사용합니다.

Cloud Storage API에 필요한 사용자 인증 정보를 가져오고 build() 메서드와 사용자 인증 정보로 Cloud Storage 서비스를 초기화합니다.
Cloud Storage의 버킷을 나열합니다.

Cloud Storage에서 버킷을 관리할 수 있는 액세스 권한이 있는 인스턴스에서 이 샘플을 실행할 수 있습니다.

compute/auth/application_default.py

GitHub에서 보기 의견 보내기

import argparse
from typing import List

from google.cloud import storage

def create_client() -> storage.Client:
    """
    Construct a client object for the Storage API using the
    application default credentials.

    Returns:
        Storage API client object.
    """
    # Construct the service object for interacting with the Cloud Storage API -
    # the 'storage' service, at version 'v1'.
    # Authentication is provided by application default credentials.
    # When running locally, these are available after running
    # `gcloud auth application-default login`. When running on Compute
    # Engine, these are available from the environment.
    return storage.Client()

def list_buckets(client: storage.Client, project_id: str) -> List[storage.Bucket]:
    """
    Retrieve bucket list of a project using provided client object.

    Args:
        client: Storage API client object.
        project_id: name of the project to list buckets from.

    Returns:
        List of Buckets found in the project.
    """
    buckets = client.list_buckets()
    return list(buckets)

def main(project_id: str) -> None:
    client = create_client()
    buckets = list_buckets(client, project_id)
    print(buckets)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project_id", help="Your Google Cloud Project ID.")

    args = parser.parse_args()

    main(args.project_id)

액세스 토큰으로 직접 애플리케이션 인증

대부분의 애플리케이션에서는 사용자 인증 정보를 찾아 토큰을 관리하는 애플리케이션 기본 사용자 인증 정보를 사용하여 인증할 수 있습니다. 하지만 애플리케이션에서 OAuth2 액세스 토큰을 제공해야 하는 경우 Compute Engine을 사용하면 애플리케이션에서 사용할 메타데이터 서버에서 액세스 토큰을 가져올 수 있습니다.

애플리케이션을 인증하도록 이러한 액세스 토큰을 가져오고 사용하는 몇 가지 옵션이 있습니다. 예를 들어 curl을 사용하여 간단한 요청을 만들거나 Python과 같은 프로그래밍 언어를 사용하여 유연성을 높일 수 있습니다.

cURL

curl을 사용하여 액세스 토큰을 요청하고 API에 요청을 보내려면 다음 안내를 따르세요.

애플리케이션이 실행되는 인스턴스에서 다음 명령어를 실행하여 메타데이터 서버에 액세스 토큰을 쿼리합니다.
```
$ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
-H "Metadata-Flavor: Google"
```
요청을 실행하면 다음과 비슷한 응답이 반환됩니다.
```
{
      "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAS08i85nHq39HE3C2LTrCARA",
      "expires_in":3599,
      "token_type":"Bearer"
 }
```
API 요청의 경우 전체 응답이 아닌 access_token 값을 포함해야 합니다. jq 명령줄 JSON 프로세서가 설치되었으면 다음 명령어를 사용하여 응답에서 액세스 토큰 값을 추출할 수 있습니다.
```
$ ACCESS_TOKEN=`curl \
"http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
-H "Metadata-Flavor: Google" | jq -r '.access_token'`
```
응답에서 access_token 속성 값을 복사하고 이 값을 사용하여 API에 요청을 보냅니다. 예를 들어 다음 요청은 특정 영역의 프로젝트에 있는 인스턴스를 목록으로 출력합니다.
```
$ curl https://compute.googleapis.com/compute/v1/projects/[PROJECT_ID]/zones/[ZONE]/instances \
-H "Authorization":"Bearer [ACCESS_TOKEN]"
```
각 항목의 의미는 다음과 같습니다.
- [PROJECT_ID]는 이 요청의 프로젝트 ID입니다.
- [ZONE]은 인스턴스를 나열할 영역입니다.
- [ACCESS_TOKEN]은 1단계에서 가져온 액세스 토큰 값입니다.
참고: 인스턴스를 만들 때 지정한 범위에만 액세스 토큰을 사용할 수 있습니다. 예를 들어 인스턴스에 Cloud Storage의 https://www.googleapis.com/auth/storage-full 범위만 부여된 경우, 액세스 토큰을 사용하여 BigQuery에 요청할 수 없습니다.

요청에 설정할 수 있는 매개변수에 대한 자세한 내용은 매개변수 문서를 참조하세요.

Python

다음 예시에서는 Python 애플리케이션에서 Cloud Storage API에 액세스할 수 있는 토큰을 요청하는 방법을 보여줍니다. 이 예시에서는 다음 절차를 따릅니다.

메타데이터 서버에서 액세스 토큰을 요청합니다.
서버 응답에서 액세스 토큰을 추출합니다.
액세스 토큰을 사용하여 Cloud Storage에 요청합니다.
요청이 성공하면 스크립트가 응답을 출력합니다.

compute/auth/access_token.py

GitHub에서 보기 의견 보내기


import argparse

import requests

METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/"
METADATA_HEADERS = {"Metadata-Flavor": "Google"}
SERVICE_ACCOUNT = "default"

def get_access_token() -> str:
    """
    Retrieves access token from the metadata server.

    Returns:
        The access token.
    """
    url = f"{METADATA_URL}instance/service-accounts/{SERVICE_ACCOUNT}/token"

    # Request an access token from the metadata server.
    r = requests.get(url, headers=METADATA_HEADERS)
    r.raise_for_status()

    # Extract the access token from the response.
    access_token = r.json()["access_token"]

    return access_token

def list_buckets(project_id: str, access_token: str) -> dict:
    """
    Calls Storage API to retrieve a list of buckets.

    Args:
        project_id: name of the project to list buckets from.
        access_token: access token to authenticate with.

    Returns:
        Response from the API.
    """
    url = "https://www.googleapis.com/storage/v1/b"
    params = {"project": project_id}
    headers = {"Authorization": f"Bearer {access_token}"}

    r = requests.get(url, params=params, headers=headers)
    r.raise_for_status()

    return r.json()

def main(project_id: str) -> None:
    """
    Retrieves access token from metadata server and uses it to list
    buckets in a project.

    Args:
        project_id: name of the project to list buckets from.
    """
    access_token = get_access_token()
    buckets = list_buckets(project_id, access_token)
    print(buckets)

if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project_id", help="Your Google Cloud project ID.")

    args = parser.parse_args()

    main(args.project_id)

액세스 토큰은 짧은 기간이 지나면 만료됩니다. 메타데이터 서버에서는 액세스 토큰이 만료되기 전 남은 시간이 5분이 될 때까지 액세스 토큰을 캐시합니다. 원하는 만큼 자주 새 토큰을 요청할 수 있지만, API 호출이 성공하려면 애플리케이션에 유효한 액세스 토큰이 있어야 합니다.

서비스 계정을 사용하여 인스턴스에서 도구 인증

일부 애플리케이션에서는 대부분의 Compute Engine 이미지에 기본적으로 포함된 gcloud 및 gsutil 도구의 명령어를 사용할 수 있습니다. 이러한 도구는 인스턴스의 서비스 계정과 서비스 계정에 부여된 관련 권한을 자동으로 인식합니다. 특히 서비스 계정에 올바른 역할을 부여했다면 gcloud auth login을 사용하지 않고도 인스턴스에서 gcloud 및 gsutil 도구를 사용할 수 있습니다.

서비스 계정은 자동으로 인식되며 인스턴스에 포함된 gcloud 도구와 gsutil 도구에만 인식이 적용됩니다. 새 도구를 만들거나 커스텀 도구를 추가한 경우 클라이언트 라이브러리를 사용하거나 애플리케이션에서 직접 액세스 토큰을 사용하여 애플리케이션을 승인해야 합니다.

자동 서비스 계정 인식을 활용하려면 서비스 계정에 적절한 IAM 역할을 부여하고 서비스 계정으로 실행되도록 인스턴스를 설정합니다. 예를 들어 서비스 계정에 roles/storage.objectAdmin 역할을 부여하면 gsutil 도구는 자동으로 Cloud Storage 객체를 관리하고 액세스할 수 있습니다.

마찬가지로 서비스 계정에 roles/compute.instanceAdmin.v1을 사용 설정하면 gcloud compute 도구는 자동으로 인스턴스를 관리할 수 있습니다.

인스턴스의 서비스 계정 및 액세스 범위 변경

VM을 다른 ID로 실행하거나 필요한 API를 호출하기 위해 인스턴스에 다른 범위 집합이 필요하다고 판단되는 경우 기존 인스턴스의 서비스 계정과 액세스 범위를 변경할 수 있습니다. 예를 들어 새 API에 대한 액세스 권한을 부여하도록 액세스 범위를 변경하거나, VM이 Google Cloud 서비스에 액세스하지 못하도록 서비스 계정 및 액세스 범위를 삭제하거나, Compute Engine 기본 서비스 계정 대신 사용자가 만든 서비스 계정으로 실행되도록 VM을 변경할 수 있습니다. 하지만 액세스 범위를 사용하는 대신 세분화된 IAM 정책을 사용하여 서비스 계정의 리소스 액세스 권한을 제어하는 것이 좋습니다.

인스턴스의 서비스 계정과 액세스 범위를 변경하려면 인스턴스를 일시적으로 중지해야 합니다. 인스턴스를 중지하려면 인스턴스 중지 문서를 읽어보세요. 서비스 계정이나 액세스 범위를 변경한 후 인스턴스를 다시 시작해야 합니다. 다음 방법 중 하나를 사용하여 중지된 인스턴스의 서비스 계정이나 액세스 범위를 변경합니다.

콘솔

VM 인스턴스 페이지로 이동합니다.

VM 인스턴스로 이동
서비스 계정을 변경할 VM 인스턴스 이름을 클릭합니다.
인스턴스가 중지되지 않은 경우 중지를 클릭합니다. 인스턴스가 중지될 때까지 기다립니다.
그런 다음 수정을 클릭합니다.
서비스 계정 섹션까지 아래로 스크롤합니다.
드롭다운 목록에서 인스턴스에 할당할 서비스 계정을 선택합니다.
- 기본 서비스 계정을 선택한 경우 Google Cloud 콘솔에서 액세스 범위를 수정할 수 있습니다.
  - 범위를 변경하려면 액세스 범위 섹션에서 각 API에 액세스 설정을 선택하고 필요에 따라 적합한 범위를 설정합니다.
  - 설정할 올바른 액세스 범위를 모른다면 모든 Cloud API에 대한 전체 액세스 허용을 선택한 후 서비스 계정에 IAM 역할을 설정하여 액세스를 제한해야 합니다.
- 다른 서비스 계정을 선택하면 VM의 액세스 범위가 기본적으로 cloud-platform 범위로 지정됩니다. gcloud CLI 또는 Compute Engine API를 사용하여 범위를 수정할 수 있습니다.
- 액세스 범위 설정에 대한 자세한 내용은 권장사항을 참조하세요.
저장을 클릭하여 변경사항을 저장합니다.

gcloud

instances set-service-account 명령어를 사용하고 인스턴스 이름, 서비스 계정 이메일, 원하는 범위를 지정합니다. 액세스 범위 설정에 대한 자세한 내용은 권장사항을 참조하세요.

gcloud compute instances set-service-account [INSTANCE_NAME] \
   [--service-account [SERVICE_ACCOUNT_EMAIL] | --no-service-account] \
   [--no-scopes | --scopes [SCOPES,...]]

각 항목의 의미는 다음과 같습니다.

[SERVICE_ACCOUNT_EMAIL]은 사용할 서비스 계정 이메일입니다. 예를 들면 my-sa-123@my-project-123.iam.gserviceaccount.com입니다.
[INSTANCE_NAME]은 인스턴스의 이름입니다.
[SCOPES]는 쉼표로 구분된 전체 범위 URI이거나 --scopes 플래그의 설명에서 제공된 범위 별칭의 목록입니다. 인스턴스의 모든 범위를 삭제하려면 대신 --no-scopes 플래그를 사용합니다.

예를 들어 다음 명령어는 my-sa-123@my-project-123.iam.gserviceaccount.com 서비스 계정을 example-instance라는 인스턴스에 할당하고, Compute Engine에 대한 읽기/쓰기 액세스 권한과 Cloud Storage에 대한 읽기 전용 액세스 권한을 허용하도록 인스턴스의 액세스 범위를 설정합니다.

gcloud compute instances set-service-account example-instance \
   --service-account my-sa-123@my-project-123.iam.gserviceaccount.com \
   --scopes compute-rw,storage-ro

API

API에서