为服务器到服务器的生产应用设置身份验证

本指南介绍了如何在 Google Cloud API 中为服务器到服务器生产应用设置身份验证和授权。身份验证过程用于确定客户的身份。授权是指确定通过身份验证的客户对特定资源具有哪些权限的过程。也就是说，身份验证可识别您的身份，授权决定了您可以执行的操作。如需详细了解支持的身份验证方法以及如何选择这些方法，请参阅身份验证概览。

Google 使用凭据来标识您的应用，以进行配额计算和结算。您的凭据还用于授予对 Google Cloud API、资源和功能的访问权限。

为应用提供凭据

自动查找凭据

Google Cloud 客户端库使用名为“应用默认凭据”(ADC) 的策略来查找应用的凭据。当您的代码使用客户端库时，该策略将按以下顺序检查您的凭据：

1. 首先，ADC 检查是否设置了环境变量 GOOGLE_APPLICATION_CREDENTIALS。如果设置了该变量，则 ADC 使用该变量指向的服务帐号文件。下一部分将介绍如何设置环境变量。

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

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

以下代码示例展示了该策略。该示例并未明确指定应用凭据。但是，只要设置了 GOOGLE_APPLICATION_CREDENTIALS 环境变量，或者只要应用在 Compute Engine、GKE、App Engine 或 Cloud Functions 上运行，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)
	}

	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();

try {
  // Makes an authenticated API request.
  const results = await storage.getBuckets();

  const [buckets] = results;

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

PHP

在 GitHub 上查看

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

在 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. 在服务帐号名称字段中，输入一个名称。

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

   注意：角色字段授权您的服务帐号资源访问权限。您稍后可以使用 Cloud Console 查看和更改此字段。如果您开发的是正式版应用，请指定比项目 > Owner 更为精细的权限。如需了解详情，请参阅为服务帐号授予角色。
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"

   注意：角色字段授权您的服务帐号资源访问权限。您稍后可以使用 Cloud Console 查看和更改此字段。如果您开发的是正式版应用，请指定比项目 > Owner 更为精细的权限。如需了解详情，请参阅向服务帐号授予角色。

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，向您的应用代码提供身份验证凭据。将 [PATH] 替换为包含您服务帐号密钥的 JSON 文件的路径，并将 [FILE_NAME] 替换为文件名。此变量仅适用于当前的 shell 会话，因此，如果您打开新的会话，请重新设置该变量。

Linux 或 macOS

export GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

例如：

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/[FILE_NAME].json"

Windows

使用 PowerShell：

$env:GOOGLE_APPLICATION_CREDENTIALS="[PATH]"

例如：

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\[FILE_NAME].json"

使用命令提示符：

set GOOGLE_APPLICATION_CREDENTIALS=[PATH]

完成上述步骤后，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)
	}
	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.
try {
  const [buckets] = await storage.getBuckets();

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

PHP

在 GitHub 上查看

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

在 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

在 Compute Engine、Kubernetes Engine、App Engine 柔性环境和 Cloud Functions 上获取凭据

如果您的应用在 Compute Engine、GKE、App Engine 柔性环境或 Cloud Functions 上运行，您无需创建自己的服务帐号。Compute Engine 包含为您自动创建的默认服务帐号，如果需要，您可以为每个实例分配不同的服务帐号。创建新实例时，该实例会自动启用，以默认服务帐号身份运行，并具有一组默认的授权权限。如需了解详情，请参阅 Compute Engine 默认服务帐号。

设置好服务帐号后，ADC 可以隐式查找您的凭据，而您无需更改您的代码，如上一部分中所述。如果您要专门使用 Compute Engine 凭据，可以明确执行此操作，如以下代码示例所示。

必须安装 Cloud Storage 客户端库才能运行以下示例。

C#

在 GitHub 上查看

        // Some APIs, like Storage, accept a credential in their Create()
        // method.
        public object AuthExplicitComputeEngine(string projectId)
        {
            // Explicitly request service account credentials from the compute
            // engine instance.
            GoogleCredential credential =
                GoogleCredential.FromComputeCredential();
            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 AuthExplicitComputeEngine(string projectId)
        {
            LanguageServiceClientBuilder builder = new LanguageServiceClientBuilder
            {
                ChannelCredentials = GoogleCredential
                .FromComputeCredential()
                .ToChannelCredentials()
            };

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

Go

在 GitHub 上查看

// explicitDefault finds the default credentials.
//
// It is very uncommon to need to explicitly get the default credentials in Go.
// Most of the time, client libraries can use Application Default Credentials
// without having to pass the credentials in directly. See implicit above.
func explicitDefault(projectID string) {
	ctx := context.Background()

	creds, err := google.FindDefaultCredentials(ctx, storage.ScopeReadOnly)
	if err != nil {
		log.Fatal(err)
	}
	client, err := storage.NewClient(ctx, option.WithCredentials(creds))
	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

在 GitHub 上查看

static void authCompute() {
  // Explicitly request service account credentials from the compute engine instance.
  GoogleCredentials credentials = ComputeEngineCredentials.create();
  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 上查看

'use strict';

const {auth, Compute} = require('google-auth-library');

/**
 * This example directly instantiates a Compute client to acquire credentials.
 * Generally, you wouldn't directly create this class, rather call the
 * `auth.getClient()` method to automatically obtain credentials.
 */
async function main() {
  const client = new Compute({
    // Specifying the serviceAccountEmail is optional. It will use the default
    // service account if one is not defined.
    serviceAccountEmail: '[e-mail]',
  });
  const projectId = await auth.getProjectId();
  const url = `https://dns.googleapis.com/dns/v1/projects/${projectId}`;
  const res = await client.request({url});
  console.log(res.data);
}

main().catch(console.error);

PHP

在 GitHub 上查看

namespace Google\Cloud\Samples\Auth;

// Imports GCECredentials and the Cloud Storage client library.
use Google\Auth\Credentials\GCECredentials;
use Google\Cloud\Storage\StorageClient;

function auth_cloud_explicit_compute_engine($projectId)
{
    $gceCredentials = new GCECredentials();
    $config = [
        'projectId' => $projectId,
        'credentialsFetcher' => $gceCredentials,
    ];
    $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_compute_engine(project):
    from google.auth import compute_engine
    from google.cloud import storage

    # Explicitly use Compute Engine credentials. These credentials are
    # available on Compute Engine, App Engine Flexible, and Container Engine.
    credentials = compute_engine.Credentials()

    # Create the client using the credentials and specifying a project ID.
    storage_client = storage.Client(credentials=credentials, project=project)

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

Ruby

在 GitHub 上查看

require "googleauth"
require "google/cloud/env"
require "google/cloud/storage"

# Explicitly use Compute Engine credentials and a project ID to create a new
# Cloud Storage client. These credentials are available on Compute Engine,
# App Engine Flexible, and Container Engine.
storage = Google::Cloud::Storage.new project: Google::Cloud.env.project_id,
                                     keyfile: Google::Auth::GCECredentials.new

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

在 App Engine 标准环境中获取凭据

如果您的应用在 App Engine 标准环境中运行，您可以使用 App Engine App Identity API 来获取凭据。

设置好服务帐号后，ADC 可以隐式查找您的凭据，而您无需更改您的代码，如上一部分中所述。如果您要专门使用 App Engine 凭据，则可以明确执行此操作，具体如以下代码示例所示。

必须安装 Cloud Storage 客户端库才能运行以下示例。

PHP

在 GitHub 上查看

namespace Google\Cloud\Samples\Auth;

// Imports AppIdentityCredentials and the Cloud Storage client library.
use Google\Auth\Credentials\AppIdentityCredentials;
use Google\Cloud\Storage\StorageClient;

function auth_cloud_explicit_app_engine($projectId)
{
    # Learn more about scopes at https://cloud.google.com/storage/docs/authentication#oauth-scopes
    $scope = 'https://www.googleapis.com/auth/devstorage.read_only';
    $gaeCredentials = new AppIdentityCredentials($scope);
    $config = [
        'projectId' => $projectId,
        'credentialsFetcher' => $gaeCredentials,
    ];
    $storage = new StorageClient($config);

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

Go

在 GitHub 上查看

// explicitDefault finds the default credentials.
//
// It is very uncommon to need to explicitly get the default credentials in Go.
// Most of the time, client libraries can use Application Default Credentials
// without having to pass the credentials in directly. See implicit above.
func explicitDefault(projectID string) {
	ctx := context.Background()

	creds, err := google.FindDefaultCredentials(ctx, storage.ScopeReadOnly)
	if err != nil {
		log.Fatal(err)
	}
	client, err := storage.NewClient(ctx, option.WithCredentials(creds))
	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

在 GitHub 上查看

static void authAppEngineStandard() throws IOException {
  // Explicitly request service account credentials from the app engine standard instance.
  GoogleCredentials credentials = AppEngineCredentials.getApplicationDefault();
  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());
  }
}

Python

在 GitHub 上查看

def explicit_app_engine(project):
    from google.auth import app_engine
    import googleapiclient.discovery

    # Explicitly use App Engine credentials. These credentials are
    # only available when running on App Engine Standard.
    credentials = app_engine.Credentials()

    # Explicitly pass the credentials to the client library.
    storage_client = googleapiclient.discovery.build(
        'storage', 'v1', credentials=credentials)

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

限制访问权限

请仅授予应用与适用的 Google Cloud API、功能或资源进行交互所需的授权权限。Google Cloud 使用 Cloud Identity and Access Management (Cloud IAM) 进行访问权限控制。 创建服务帐号时，您可以选择 Cloud IAM 角色以限制访问权限。身份验证使用入门中的演示会指导您在创建服务帐号时选择 Owner 角色。您可以随时更改此值。如需了解详情，请参阅为服务帐号授予角色。

管理凭据的最佳做法

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

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

• 在不同情况下使用不同的凭据，如在测试环境和生产环境中。

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

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

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

排查 API 错误

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

后续步骤

• 了解身份验证使用入门。
• 了解如何以最终用户身份设置身份验证。
• 了解如何使用 API 密钥。