以服务帐号身份进行身份验证

本主题介绍了如何以服务帐号身份对应用进行身份验证。 如需了解有关向 Google Cloud API 进行身份验证的一般信息（包括常见的身份验证场景和策略），请参阅身份验证概览。如需详细了解服务帐号，请参阅 Identity and Access Management 文档中的服务帐号。

自动查找凭据

如果您的应用在具有默认服务帐号的 Google Cloud 环境中运行，则应用可以检索服务帐号凭据以调用 Google Cloud API。此类环境包括 Compute Engine、Google Kubernetes Engine、App Engine、Cloud Run 和 Cloud Functions。我们建议使用此策略，因为这种做法比手动传递凭据更便捷、更安全。

此外，我们建议您在应用中使用 Google Cloud 客户端库。Google Cloud 客户端库使用名为“应用默认凭据”(ADC) 的库来自动查找您的服务帐号凭据。ADC 会按以下顺序查找服务帐号凭据：

  1. 如果设置了环境变量 GOOGLE_APPLICATION_CREDENTIALS，则 ADC 会使用该变量指向的服务帐号文件。

  2. 如果未设置环境变量 GOOGLE_APPLICATION_CREDENTIALS，则 ADC 会使用 Compute Engine、Google Kubernetes Engine、App Engine、Cloud Run 和 Cloud Functions 提供的默认服务帐号。

  3. 如果 ADC 无法使用上述任何凭据，则会引发错误。

以下代码示例展示了如何在应用代码中使用 ADC 库：

C#

public object AuthImplicit(string projectId)
{
    // If you don't specify credentials when constructing the client, the
    // client library will look for credentials in the environment.
    var credential = GoogleCredential.GetApplicationDefault();
    var storage = StorageClient.Create(credential);
    // Make an authenticated API request.
    var buckets = storage.ListBuckets(projectId);
    foreach (var bucket in buckets)
    {
        Console.WriteLine(bucket.Name);
    }
    return null;
}

Go


// implicit uses Application Default Credentials to authenticate.
func implicit() {
	ctx := context.Background()

	// For API packages whose import path is starting with "cloud.google.com/go",
	// such as cloud.google.com/go/storage in this case, if there are no credentials
	// provided, the client library will look for credentials in the environment.
	storageClient, err := storage.NewClient(ctx)
	if err != nil {
		log.Fatal(err)
	}

	it := storageClient.Buckets(ctx, "project-id")
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(bucketAttrs.Name)
	}

	// For packages whose import path is starting with "google.golang.org/api",
	// such as google.golang.org/api/cloudkms/v1, use NewService to create the client.
	kmsService, err := cloudkms.NewService(ctx)
	if err != nil {
		log.Fatal(err)
	}

	_ = kmsService
}

Java

static void authImplicit() {
  // If you don't specify credentials when constructing the client, the client library will
  // look for credentials via the environment variable GOOGLE_APPLICATION_CREDENTIALS.
  Storage storage = StorageOptions.getDefaultInstance().getService();

  System.out.println("Buckets:");
  Page<Bucket> buckets = storage.list();
  for (Bucket bucket : buckets.iterateAll()) {
    System.out.println(bucket.toString());
  }
}

Node.js

// Imports the Google Cloud client library.
const {Storage} = require('@google-cloud/storage');

// Instantiates a client. If you don't specify credentials when constructing
// the client, the client library will look for credentials in the
// environment.
const storage = new Storage();
// Makes an authenticated API request.
async function listBuckets() {
  try {
    const results = await storage.getBuckets();

    const [buckets] = results;

    console.log('Buckets:');
    buckets.forEach((bucket) => {
      console.log(bucket.name);
    });
  } catch (err) {
    console.error('ERROR:', err);
  }
}
listBuckets();

PHP

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

function auth_cloud_implicit($projectId)
{
    $config = [
        'projectId' => $projectId,
    ];

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

def implicit():
    from google.cloud import storage

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    storage_client = storage.Client()

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

# project_id = "Your Google Cloud project ID"

require "google/cloud/storage"

# If you don't specify credentials when constructing the client, the client
# library will look for credentials in the environment.
storage = Google::Cloud::Storage.new project: project_id

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

手动传递凭据

如果您的应用在提供默认服务帐号的 Google Cloud 环境之外运行，则您需要手动创建一个服务帐号。然后，您可以创建一个或多个服务帐号密钥，这些密钥是与该服务帐号关联的凭据。您可以手动将服务帐号密钥传递到您的应用。

创建服务帐号

以下步骤介绍了如何创建服务帐号（如果您没有该帐号）：

Cloud Console

  1. 在 Cloud Console 中，转到创建服务帐号密钥页面。

    转到“创建服务帐号密钥”页面
  2. 从服务帐号列表中，选择新的服务帐号。
  3. 在服务帐号名称字段中，输入一个名称。

  4. 从角色列表中，选择项目 > 所有者。

  5. 点击创建。包含密钥的 JSON 文件就会下载到计算机。

命令行

您可以使用本地机器上的 Cloud SDK 或在 Cloud Shell 中运行以下命令。

  1. 创建服务帐号。将 NAME 替换为服务帐号的名称。

    gcloud iam service-accounts create NAME

  2. 向服务帐号授予权限。将 PROJECT_ID 替换为您的项目 ID。

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/owner"

  3. 生成密钥文件。将 FILE_NAME 替换为密钥文件的名称。 

    gcloud iam service-accounts keys create FILE_NAME.json --iam-account=NAME@PROJECT_ID.iam.gserviceaccount.com

通过环境变量传递凭据

通过设置环境变量 GOOGLE_APPLICATION_CREDENTIALS 向应用代码提供身份验证凭据。 将 [PATH] 替换为包含您的服务帐号密钥的 JSON 文件的路径。此变量仅适用于当前的 Shell 会话，因此，如果您打开新的会话，请重新设置该变量。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

例如：

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/my-key.json"

Windows

使用 PowerShell：

$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

例如：

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\my-key.json"

使用命令提示符：

set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

完成上述步骤后，ADC 会自动查找您的凭据，如上述部分所述。我们建议您使用 ADC，因为需要使用的代码更少且代码可在不同的环境中移植。

使用代码传递凭据

如以下示例中所示，您可以选择在代码中明确指向服务帐号文件。必须安装 Cloud Storage 客户端库才能运行以下示例。

C#

        // Some APIs, like Storage, accept a credential in their Create()
        // method.
        public object AuthExplicit(string projectId, string jsonPath)
        {
            // Explicitly use service account credentials by specifying
            // the private key file.
            var credential = GoogleCredential.FromFile(jsonPath);
            var storage = StorageClient.Create(credential);
            // Make an authenticated API request.
            var buckets = storage.ListBuckets(projectId);
            foreach (var bucket in buckets)
            {
                Console.WriteLine(bucket.Name);
            }
            return null;
        }
        // Other APIs, like Language, accept a channel in their Create()
        // method.
        public object AuthExplicit(string projectId, string jsonPath)
        {
            LanguageServiceClientBuilder builder = new LanguageServiceClientBuilder
            {
                CredentialsPath = jsonPath
            };

            LanguageServiceClient client = builder.Build();
            AnalyzeSentiment(client);
            return 0;
        }

Go


// explicit reads credentials from the specified path.
func explicit(jsonPath, projectID string) {
	ctx := context.Background()
	client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Buckets:")
	it := client.Buckets(ctx, projectID)
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(battrs.Name)
	}
}

Java

static void authExplicit(String jsonPath) throws IOException {
  // You can specify a credential file by providing a path to GoogleCredentials.
  // Otherwise credentials are read from the GOOGLE_APPLICATION_CREDENTIALS environment variable.
  GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream(jsonPath))
        .createScoped(Lists.newArrayList("https://www.googleapis.com/auth/cloud-platform"));
  Storage storage = StorageOptions.newBuilder().setCredentials(credentials).build().getService();

  System.out.println("Buckets:");
  Page<Bucket> buckets = storage.list();
  for (Bucket bucket : buckets.iterateAll()) {
    System.out.println(bucket.toString());
  }
}

Node.js

// Imports the Google Cloud client library.
const {Storage} = require('@google-cloud/storage');

// Instantiates a client. Explicitly use service account credentials by
// specifying the private key file. All clients in google-cloud-node have this
// helper, see https://github.com/GoogleCloudPlatform/google-cloud-node/blob/master/docs/authentication.md
// const projectId = 'project-id'
// const keyFilename = '/path/to/keyfile.json'
const storage = new Storage({projectId, keyFilename});

// Makes an authenticated API request.
async function listBuckets() {
  try {
    const [buckets] = await storage.getBuckets();

    console.log('Buckets:');
    buckets.forEach((bucket) => {
      console.log(bucket.name);
    });
  } catch (err) {
    console.error('ERROR:', err);
  }
}
listBuckets();

PHP

namespace Google\Cloud\Samples\Auth;

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

function auth_cloud_explicit($projectId, $serviceAccountPath)
{
    # Explicitly use service account credentials by specifying the private key
    # file.
    $config = [
        'keyFilePath' => $serviceAccountPath,
        'projectId' => $projectId,
    ];
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

def explicit():
    from google.cloud import storage

    # Explicitly use service account credentials by specifying the private key
    # file.
    storage_client = storage.Client.from_service_account_json(
        'service_account.json')

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

# project_id = "Your Google Cloud project ID"
# key_file   = "path/to/service-account.json"
require "google/cloud/storage"

# Explicitly use service account credentials by specifying the private key
# file.
storage = Google::Cloud::Storage.new project: project_id, keyfile: key_file

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

管理凭据的最佳做法

凭据提供对敏感数据的访问权限。以下做法有助于保护对凭据的访问权限。

  • 请勿在源代码中嵌入与身份验证相关的密钥，如 API 密钥、OAuth 令牌和服务帐号密钥。您可以使用指向应用源代码之外的凭据的环境变量，如 Cloud Key Management Service。

  • 在不同场景（如测试和生产环境）下创建和使用不同的凭据。

  • 仅通过安全通道（如 HTTPS）传输凭据，以防止第三方拦截您的凭据。切勿以明文形式传输凭据或将凭据作为网址的一部分进行传输。

  • 切勿将长期有效的凭据嵌入客户端应用。例如，不要将服务帐号密钥嵌入移动应用。第三方可能会检查客户端应用，轻松找到凭据并使用。

  • 如果您不再需要令牌，请撤消令牌。

排查 API 错误

如需详细了解如何对失败的 API 请求进行问题排查，请参阅 Cloud API 错误。

后续步骤