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

本指南介绍了如何在 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#

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

此策略在测试和试验时非常有用，但可能很难分辨您的应用所用的凭据。我们建议明确指定应用应使用的凭据，如以下部分所述。

手动获取和提供服务帐号凭据

如果您在本地开发代码、在本地部署应用或者将应用部署到其他公有云，则可以手动创建和获取服务帐号凭据。

创建服务帐号

以下步骤介绍了如何创建服务帐号。但是，如下方限制访问权限部分所示，您应该限制对权限的访问，而不是设置所有者级层权限。

Cloud Console

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

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

  4. 从角色列表中，选择项目 > Owner。

    注意：角色字段会为您的服务帐号授予资源访问权限。您稍后可以使用 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 文件的路径。此变量仅适用于当前的 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 就能够隐式确定您的凭据（如上面的为应用提供凭据部分所述）。我们建议使用该方法，因为需要的代码较少。此外，通过使用环境变量，代码的可移植性更强，因为您可以在具有不同服务帐号的多个环境中运行相同的代码。

在代码中传递指向服务帐号密钥的路径

如以下代码示例中所示，您可以选择在代码中明确指向服务帐号文件。

必须安装 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

在 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#

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


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

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

'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: 'some-service-account@example.com',
  });
  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

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

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

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

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


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

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

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) 进行访问权限控制。创建服务帐号时，您可以选择一个 IAM 角色来限制访问权限。身份验证使用入门中的演示会指导您在创建服务帐号时选择 Owner 角色。您可以随时更改此值。如需了解详情，请参阅为服务帐号授予角色。

管理凭据的最佳做法

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

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

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

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

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

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

排查 API 错误

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

后续步骤