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

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

注意：如果您的应用在本地或其他云服务商上运行，您可以使用工作负载身份联合向外部身份授予访问权限，而无需使用服务帐号密钥。某些客户端库可以使用应用默认凭据 (ADC) 自动为外部身份生成凭据。

如需了解详情，请参阅您的身份提供商的文档：

• 自动生成 Amazon Web Services (AWS) 凭据
• 自动生成 Microsoft Azure 凭据
• 为支持 OpenID Connect (OIDC) 的身份提供商自动生成凭据

自动查找凭据

如果您的应用在 Google Cloud 环境中运行，并且您已经向该环境附加服务帐号，则您的应用可以检索该服务帐号的凭据。然后，应用可以使用这些凭据来调用 Google Cloud API。

您可以将服务帐号附加到许多不同 Google Cloud 服务的资源，包括 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 库。要运行此示例，您必须安装 Cloud Storage 客户端库。

C#

在 GitHub 上查看

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

在 GitHub 上查看

// 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)
	}
	defer storageClient.Close()

	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

在 GitHub 上查看

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

在 GitHub 上查看

// 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

在 GitHub 上查看

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

/**
 * Authenticate to a cloud client library using a service account implicitly.
 *
 * @param string $projectId The Google project ID.
 */
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

在 GitHub 上查看

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

在 GitHub 上查看

# 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

手动传递凭据

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

创建服务帐号

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

Cloud Console

创建服务帐号：

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

   转到“创建服务帐号”
2. 选择一个项目。

3. 在服务帐号名称字段中，输入一个名称。 Cloud Console 会根据此名称填充服务帐号 ID 字段。

   在服务帐号说明字段中，输入说明。例如，Service account for quickstart。

4. 点击创建并继续。

5. 点击选择角色字段。

   在快速访问下，点击基本，然后点击所有者。

   注意：角色字段会影响您的服务帐号可以访问项目中的哪些资源。您可以撤消这些角色或稍后授予其他角色。在生产环境中，请勿授予 Owner、Editor 或 Viewer 角色。应授予满足您的需求的预定义角色或自定义角色。
6. 点击继续。

7. 点击完成以完成服务帐号的创建过程。

   不要关闭浏览器窗口。您将在下一步骤中用到它。

创建服务帐号密钥：

1. 在 Cloud Console 中，点击您创建的服务帐号的电子邮件地址。
2. 点击密钥。
3. 依次点击添加密钥和创建新密钥。
4. 点击创建。JSON 密钥文件将下载到您的计算机上。
5. 点击关闭。

命令行

您可以使用本地机器上的 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"

   注意：--role 标志会影响您的服务帐号可以访问项目中的哪些资源。您可以撤消这些角色或稍后授予其他角色。在生产环境中，请勿授予 Owner、Editor 或 Viewer 角色。请改为授予满足您需求的预定义角色或自定义角色。

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

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

注意：创建服务帐号后，您需要将服务帐号密钥下载到运行应用的机器。您可以使用 GOOGLE_APPLICATION_CREDENTIALS 环境变量或编写代码来将服务帐号密钥传递给客户端库。

通过环境变量传递凭据

通过设置环境变量 GOOGLE_APPLICATION_CREDENTIALS 向应用代码提供身份验证凭据。此变量仅适用于当前的 Shell 会话。如果您希望变量应用于未来的 Shell 会话，请在 shell 启动文件中设置变量，例如在 ~/.bashrc 或 ~/.profile 文件中。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

例如：

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

对于 PowerShell：

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

例如：

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

对于命令提示符：

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

将 KEY_PATH 替换为包含您的服务帐号密钥的 JSON 文件的路径。

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

使用代码传递凭据

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

C#

在 GitHub 上查看

        // 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

在 GitHub 上查看

// 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)
	}
	defer client.Close()
	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

在 GitHub 上查看

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

在 GitHub 上查看

// 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

在 GitHub 上查看

namespace Google\Cloud\Samples\Auth;

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

/**
 * Authenticate to a cloud client library using a service account explicitly.
 *
 * @param string $projectId           The Google project ID.
 * @param string $serviceAccountPath  Path to service account credentials JSON.
 */
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

在 GitHub 上查看

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

在 GitHub 上查看

# 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 错误。

后续步骤

• 查看使用和管理服务帐号的最佳做法
• 详细了解保护服务帐号的最佳做法
• 了解如何向 Google Cloud API 验证身份
• 了解如何以最终用户身份进行身份验证
• 了解如何使用 API 密钥

自行试用

如果您是 Google Cloud 新手，请创建一个帐号来评估我们的产品在实际场景中的表现。新客户还可获享 $300 赠金，用于运行、测试和部署工作负载。

免费开始使用