서비스 계정 키 생성 및 관리

이 페이지에서는 Google Cloud Platform Console, gcloud 명령줄 도구, Cloud Identity and Access Management API 또는 Google Cloud 클라이언트 라이브러리를 사용해 서비스 계정 키를 만들고 관리하는 방법을 알아봅니다.

이 가이드의 기본 요건

• 서비스 계정 이해
• gcloud 도구 설치

필수 권한

사용자가 서비스 계정 키를 관리할 수 있도록 서비스 계정 키 관리자 역할(roles/iam.serviceAccountKeyAdmin)을 부여합니다. Cloud IAM 기본 역할도 서비스 계정 키를 관리하는 권한을 포함하지만, 다른 GCP 리소스에 불필요하게 액세스하지 못하도록 이 역할을 대신 부여하는 것이 좋습니다.

자세한 내용은 서비스 계정 역할 목록을 참조하세요.

서비스 계정 키 만들기

다른 플랫폼 또는 온프레미스 등 GCP 외부의 서비스 계정을 사용하려면 먼저 서비스 계정 ID 정보를 제공해야 합니다. 공개 키/비공개 키 쌍을 통해 안전하게 제공할 수 있습니다.

서비스 계정 키는 GCP Console, gcloud 도구, serviceAccounts.keys.create() 메서드 또는 클라이언트 라이브러리 중 하나를 사용하여 만들 수 있습니다.

아래 예시에서 [SA-NAME]은 서비스 계정 이름을, 그리고 [PROJECT-ID]는 Google Cloud Platform 프로젝트의 ID를 나타냅니다. GCP Console의 서비스 계정 페이지에서 [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com 문자열을 가져올 수 있습니다.

Console

1. GCP Console에서 IAM 및 관리자 페이지를 엽니다.

   IAM 및 관리자 페이지 열기

2. 프로젝트를 선택한 다음 계속을 클릭합니다.

3. 왼쪽 탐색 메뉴에서 서비스 계정을 클릭합니다.

4. 키를 만들려고 하는 서비스 계정을 찾아 해당 행에서 더보기 버튼을 클릭한 후 키 만들기를 클릭합니다.

5. 키 유형을 선택하고 만들기를 클릭합니다.

gcloud 명령어

gcloud iam service-accounts keys create 명령어를 실행하여 서비스 계정 키를 만듭니다.

명령어:

gcloud iam service-accounts keys create ~/key.json \
  --iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com

출력:

created key [e44da1202f82f8f4bdd9d92bc412d1d8a837fa83] of type [json] as
[/usr/home/username/key.json] for
[[e-mail]]

REST API

요청:

POST https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys

응답:

{
    "name":"projects/PROJECT-ID/serviceAccounts/[e-mail]/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
    "privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE",
    "privateKeyData":"MIIJqAIB . . .",
    "validBeforeTime": "2028-05-08T21:00:00Z",
    "validAfterTime": "2016-01-25T18:38:09.000Z",
    "keyAlgorithm": "KEY_ALG_RSA_2048"
}

C#

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 C# 설정 안내를 따르세요. 자세한 내용은 Cloud IAM C# API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class ServiceAccountKeys
{
    public static ServiceAccountKey CreateKey(string serviceAccountEmail)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var key = service.Projects.ServiceAccounts.Keys.Create(
            new CreateServiceAccountKeyRequest(),
            "projects/-/serviceAccounts/" + serviceAccountEmail)
            .Execute();
        Console.WriteLine("Created key: " + key.Name);
        return key;
    }
}

Go

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 Cloud IAM Go API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// createKey creates a service account key.
func createKey(w io.Writer, serviceAccountEmail string) (*iam.ServiceAccountKey, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/-/serviceAccounts/" + serviceAccountEmail
	request := &iam.CreateServiceAccountKeyRequest{}
	key, err := service.Projects.ServiceAccounts.Keys.Create(resource, request).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.Keys.Create: %v", err)
	}
	fmt.Fprintf(w, "Created key: %v", key.Name)
	return key, nil
}

자바

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하여 Cloud IAM 빠른 시작의 자바 설정 안내를 따르세요. 자세한 내용은 Cloud IAM 자바 API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

public ServiceAccountKey createKey(String serviceAccountEmail) throws IOException {

  ServiceAccountKey key =
      service
          .projects()
          .serviceAccounts()
          .keys()
          .create(
              "projects/-/serviceAccounts/" + serviceAccountEmail,
              new CreateServiceAccountKeyRequest())
          .execute();

  System.out.println("Created key: " + key.getName());
  return key;
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 Cloud IAM Python API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

import os

from google.oauth2 import service_account
import googleapiclient.discovery

def create_key(service_account_email):
    """Creates a key for a service account."""

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ['GOOGLE_APPLICATION_CREDENTIALS'],
        scopes=['https://www.googleapis.com/auth/cloud-platform'])

    service = googleapiclient.discovery.build(
        'iam', 'v1', credentials=credentials)

    key = service.projects().serviceAccounts().keys().create(
        name='projects/-/serviceAccounts/' + service_account_email, body={}
        ).execute()

    print('Created key: ' + key['name'])

반환되는 privateKeyData는 TYPE_GOOGLE_CREDENTIALS_FILE 값(JSON 또는 P12 키/사용자 인증 정보)의 base64 인코딩 문자열 표현입니다.

키를 만들면 공개 키/비공개 키 쌍이 새로 생성되어 시스템에 다운로드되며, 이 파일이 비공개 키의 유일한 사본입니다. 비공개 키를 안전하게 보관할 책임은 사용자에게 있습니다. 파일 위치를 잘 기록해 두고 애플리케이션에서 액세스할 수 있도록 조치하세요. 인증된 API 호출을 수행하려면 이 키가 필요합니다.

새롭게 만든 키를 인증에 사용하려면 최대 60초까지 기다려야 할 수도 있습니다. 새로운 키를 만든 직후에 인증 문제가 발생할 경우에는 다시 시도하기 전에 60초가 지났는지 확인하세요.

키의 형식은 생성 방법에 따라 다를 수 있습니다. GCP Console 또는 gcloud 명령줄 도구에서 만든 키의 모습은 다음과 같습니다.

{
"type": "service_account",
"project_id": "[PROJECT-ID]",
"private_key_id": "[KEY-ID]",
"private_key": "-----BEGIN PRIVATE KEY-----\n[PRIVATE-KEY]\n-----END PRIVATE KEY-----\n",
"client_email": "[SERVICE-ACCOUNT-EMAIL]",
"client_id": "[CLIENT-ID]",
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://accounts.google.com/o/oauth2/token",
"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/[SERVICE-ACCOUNT-EMAIL]"
}

반면 REST API 또는 클라이언트 라이브러리에서 생성된 키의 모습은 다음과 같습니다.

{
"name": "projects/[PROJECT-ID]/serviceAccounts/[SERVICE-ACCOUNT-EMAIL]/keys/[KEY-ID]",
"privateKeyType": "TYPE_GOOGLE_CREDENTIALS_FILE",
"privateKeyData": "[PRIVATE-KEY]",
"validAfterTime": "[DATE]",
"validBeforeTime": "[DATE]",
"keyAlgorithm": "KEY_ALG_RSA_2048"
}

반환되는 privateKeyData는 TYPE_GOOGLE_CREDENTIALS_FILE 값(JSON 또는 P12 키/사용자 인증 정보)의 base64 인코딩 문자열 표현입니다.

각 방법마다 형식이 다르기 때문에 앞으로 API를 호출할 때는 동일한 방법을 사용해 키를 생성하는 것이 가장 편리합니다. 예를 들어 gcloud를 사용하는 경우에는 gcloud를 사용해 키를 생성하세요. 키를 생성한 방법과 다르게 사용하려면(REST에서 생성된 키를 gcloud로 사용하는 등) 올바른 형식에 맞춰 키를 편집해야 하기 때문입니다.

모든 서비스 계정의 모든 공개 키는 누구나 공개적으로 액세스할 수 있으며 비공개 키로 생성한 서명을 검증하는 데 사용하도록 제공됩니다. 다음 URL에서 공개 키에 공개적으로 액세스할 수 있습니다.

• x.509 인증서: https://www.googleapis.com/service_accounts/v1/metadata/x509/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
• JSON 웹 키(JWK): https://www.googleapis.com/service_accounts/v1/jwk/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com
• 원시 엔드포인트: https://www.googleapis.com/service_accounts/v1/metadata/raw/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com

서비스 계정 키 나열

서비스 계정 키는 GCP Console, gcloud 도구, serviceAccount.keys.list() 메서드 또는 클라이언트 라이브러리 중 하나를 사용해 나열할 수 있습니다.

serviceAccount.keys.list() 메서드의 일반적인 용도는 서비스 계정 및 키를 감사하거나 서비스 계정을 관리하는 커스텀 도구를 만드는 것입니다.

특정 키가 속한 프로젝트를 확인하려는 경우 키를 JSON 파일로 다운로드한 후 해당 파일을 조사할 수 있습니다.

직접 만들지 않은 키가 나열될 수 있습니다. 이러한 키는 GCP에서 관리하는 키로서 App Engine, Compute Engine 등의 GCP 서비스에 사용됩니다. 사용자가 관리하는 키와 GCP에서 관리하는 키의 차이점에 대한 자세한 내용은 서비스 계정 이해를 참조하세요.

콘솔

1. GCP Console에서 IAM 및 관리자 페이지를 엽니다.

   IAM 및 관리자 페이지 열기

2. 프로젝트를 선택한 다음 계속을 클릭합니다.

3. 왼쪽 탐색 메뉴에서 서비스 계정을 클릭합니다. 모든 서비스 계정과 해당 키가 나열됩니다.

gcloud 명령어

gcloud iam service-accounts keys list 명령어를 실행하여 서비스 계정 키를 나열합니다.

명령어:

gcloud iam service-accounts keys list \
  --iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com

출력:

KEY_ID	CREATED_AT	EXPIRES_AT
8e6e3936d7024646f8ceb39792006c07f4a9760c	2016-01-26T21:01:42.000Z	2026-01-23T21:01:42.000Z
937c98f870f5c8db970af527aa3c12fd88b1c20a	2016-01-26T20:55:40.000Z	2026-01-23T20:55:40.000Z

REST API

serviceAccount.keys.list()를 호출하여 서비스 계정 키를 나열합니다.

요청:

POST https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys

응답:

{
    "keys": [
    {
        "name": "projects/PROJECT-ID/serviceAccounts/[e-mail]/keys/90c48f61c65cd56224a12ab18e6ee9ca9c3aee7c",
        "validAfterTime": "2016-01-25T18:38:09.000Z",
        "validBeforeTime": "2026-01-22T18:38:09.000Z",
        "keyAlgorithm": "KEY_ALG_RSA_2048"
    },
    {
        "name": "projects/PROJECT-ID/serviceAccounts/[e-mail]/keys/e5e3800831ac1adc8a5849da7d827b4724b1fce8",
        "validAfterTime": "2016-01-25T13:43:27.000Z",
        "validBeforeTime": "2016-01-26T13:43:27.000Z",
        "keyAlgorithm": "KEY_ALG_RSA_2048"
    },
    {
        "name": "projects/PROJECT-ID/serviceAccounts/[e-mail]/keys/b97699f042b8eee6a846f4f96259fbcd13e2682e",
        "validAfterTime": "2016-01-26T13:28:27.000Z",
        "validBeforeTime": "2016-01-27T13:28:27.000Z",
        "keyAlgorithm": "KEY_ALG_RSA_2048"
    }]
}

C#

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 C# 설정 안내를 따르세요. 자세한 내용은 Cloud IAM C# API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

using System;
using System.Collections.Generic;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class ServiceAccountKeys
{
    public static IList<ServiceAccountKey> ListKeys(string serviceAccountEmail)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        var response = service.Projects.ServiceAccounts.Keys
            .List($"projects/-/serviceAccounts/{serviceAccountEmail}")
            .Execute();
        foreach (ServiceAccountKey key in response.Keys)
        {
            Console.WriteLine("Key: " + key.Name);
        }
        return response.Keys;
    }
}

Go

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 Cloud IAM Go API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// listKey lists a service account's keys.
func listKeys(w io.Writer, serviceAccountEmail string) ([]*iam.ServiceAccountKey, error) {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return nil, fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return nil, fmt.Errorf("iam.New: %v", err)
	}

	resource := "projects/-/serviceAccounts/" + serviceAccountEmail
	response, err := service.Projects.ServiceAccounts.Keys.List(resource).Do()
	if err != nil {
		return nil, fmt.Errorf("Projects.ServiceAccounts.Keys.List: %v", err)
	}
	for _, key := range response.Keys {
		fmt.Fprintf(w, "Listing key: %v", key.Name)
	}
	return response.Keys, nil
}

자바

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하여 Cloud IAM 빠른 시작의 자바 설정 안내를 따르세요. 자세한 내용은 Cloud IAM 자바 API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

public List<ServiceAccountKey> listKeys(String serviceAccountEmail) throws IOException {

  List<ServiceAccountKey> keys =
      service
          .projects()
          .serviceAccounts()
          .keys()
          .list("projects/-/serviceAccounts/" + serviceAccountEmail)
          .execute()
          .getKeys();

  for (ServiceAccountKey key : keys) {
    System.out.println("Key: " + key.getName());
  }
  return keys;
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 Cloud IAM Python API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

import os

from google.oauth2 import service_account
import googleapiclient.discovery

def list_keys(service_account_email):
    """Lists all keys for a service account."""

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ['GOOGLE_APPLICATION_CREDENTIALS'],
        scopes=['https://www.googleapis.com/auth/cloud-platform'])

    service = googleapiclient.discovery.build(
        'iam', 'v1', credentials=credentials)

    keys = service.projects().serviceAccounts().keys().list(
        name='projects/-/serviceAccounts/' + service_account_email).execute()

    for key in keys['keys']:
        print('Key: ' + key['name'])

서비스 계정 키 받기

서비스 계정 키에 대한 비공개 키 데이터는 키를 처음 만들 때만 가져올 수 있습니다.

ID, 알고리즘, 공개 키 데이터 등 기본적인 키 정보는 projects.serviceAccounts.keys.get() REST API 메서드를 사용해 가져올 수 있습니다. 여기에서는 GCP Console 또는 gcloud 명령줄 도구가 지원되지 않습니다.

서비스 계정 키 삭제

서비스 계정 키는 GCP Console, gcloud 도구, serviceAccount.keys.delete() 메서드 또는 클라이언트 라이브러리를 사용해 삭제할 수 있습니다.

키를 삭제하면 애플리케이션에서 더 이상 해당 키를 사용하여 Cloud Platform 리소스에 액세스할 수 없습니다. 보안을 위해 서비스 계정 키를 정기적으로 순환하는 방법이 권장됩니다. 키를 순환하려면 새 키를 만들고 애플리케이션에서 새 키를 사용하도록 전환한 후 이전 키를 삭제합니다. serviceAccount.keys.create() 메서드와 serviceAccount.keys.delete() 메서드를 함께 사용하면 순환을 자동화할 수 있습니다.

콘솔

1. GCP Console에서 IAM 및 관리자 페이지를 엽니다.

   IAM 및 관리자 페이지 열기

2. 프로젝트를 선택한 다음 계속을 클릭합니다.

3. 왼쪽 탐색 메뉴에서 서비스 계정을 클릭합니다. 모든 서비스 계정과 해당 키가 나열됩니다.

4. 원하는 서비스 계정의 이메일을 클릭하여 키를 확인합니다.

5. 키 목록에서 삭제할 키마다 삭제 를 클릭합니다.

GCLOUD 명령어

gcloud iam service-accounts keys delete 명령어를 실행하여 서비스 계정 키를 삭제합니다.

명령어:

gcloud iam service-accounts keys delete [KEY-ID] \
  --iam-account [SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com

출력:

Deleted key [8e6e3936d7024646f8ceb39792006c07f4a9760c] for
service account [[e-mail]]

REST API

요청:

DELETE https://iam.googleapis.com/v1/projects/[PROJECT-ID]/serviceAccounts/[SA-NAME]@[PROJECT-ID].iam.gserviceaccount.com/keys/[KEY-ID]

C#

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 C# 설정 안내를 따르세요. 자세한 내용은 Cloud IAM C# API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

using System;
using Google.Apis.Auth.OAuth2;
using Google.Apis.Iam.v1;
using Google.Apis.Iam.v1.Data;

public partial class ServiceAccountKeys
{
    public static void DeleteKey(string fullKeyName)
    {
        var credential = GoogleCredential.GetApplicationDefault()
            .CreateScoped(IamService.Scope.CloudPlatform);
        var service = new IamService(new IamService.Initializer
        {
            HttpClientInitializer = credential
        });

        service.Projects.ServiceAccounts.Keys.Delete(fullKeyName).Execute();
        Console.WriteLine("Deleted key: " + fullKeyName);
    }
}

Go

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 Go 설정 안내를 따르세요. 자세한 내용은 Cloud IAM Go API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

import (
	"context"
	"fmt"
	"io"

	"golang.org/x/oauth2/google"
	iam "google.golang.org/api/iam/v1"
)

// deleteKey deletes a service account key.
func deleteKey(w io.Writer, fullKeyName string) error {
	client, err := google.DefaultClient(context.Background(), iam.CloudPlatformScope)
	if err != nil {
		return fmt.Errorf("google.DefaultClient: %v", err)
	}
	service, err := iam.New(client)
	if err != nil {
		return fmt.Errorf("iam.New: %v", err)
	}

	_, err = service.Projects.ServiceAccounts.Keys.Delete(fullKeyName).Do()
	if err != nil {
		return fmt.Errorf("Projects.ServiceAccounts.Keys.Delete: %v", err)
	}
	fmt.Fprintf(w, "Deleted key: %v", fullKeyName)
	return nil
}

자바

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하여 Cloud IAM 빠른 시작의 자바 설정 안내를 따르세요. 자세한 내용은 Cloud IAM 자바 API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

public void deleteKey(String fullKeyName) throws IOException {

  service.projects().serviceAccounts().keys().delete(fullKeyName).execute();

  System.out.println("Deleted key: " + fullKeyName);
}

Python

이 샘플을 시도해 보기 전에 클라이언트 라이브러리를 사용하는 Cloud IAM 빠른 시작의 Python 설정 안내를 따르세요. 자세한 내용은 Cloud IAM Python API 참조 문서를 확인하세요.

GitHub에서 보기 의견 보내기

import os

from google.oauth2 import service_account
import googleapiclient.discovery

def delete_key(full_key_name):
    """Deletes a service account key."""

    credentials = service_account.Credentials.from_service_account_file(
        filename=os.environ['GOOGLE_APPLICATION_CREDENTIALS'],
        scopes=['https://www.googleapis.com/auth/cloud-platform'])

    service = googleapiclient.discovery.build(
        'iam', 'v1', credentials=credentials)

    service.projects().serviceAccounts().keys().delete(
        name=full_key_name).execute()

    print('Deleted key: ' + full_key_name)