为一个服务账号创建短期有效凭据

本页面介绍了如何为服务账号创建短期有效的凭据,以便用于模拟服务账号。根据您创建的令牌类型,短期有效的令牌提供与服务账号关联的身份(对于 ID 令牌)或权限(对于访问令牌)。

如果您的系统架构要求您使用一系列令牌生成调用,您可以使用由多个服务账号组成的委托链。在大多数情况下,本页面所述的直接方法就足够了。

须知事项

创建短期有效的访问令牌

大多数 Google API 都接受使用访问令牌进行身份验证。使用服务账号模拟生成访问令牌时,访问令牌没有刷新令牌,这意味着当令牌失效时,您必须重复模拟过程来生成新的令牌。

如需了解详情,请参阅访问令牌

如需创建短期有效的访问令牌,请完成以下任务:

提供所需权限

直接请求涉及两种身份:请求凭据的调用方以及为其创建凭据的服务账号。设置权限的方式取决于调用方是以服务账号身份还是以 Google 账号身份进行身份验证。

如果您要在本地开发环境中运行此页面上的 REST 或 gcloud CLI 命令,调用方可以由用户凭据表示。对于自动化工作负载(例如在 Compute Engine 上运行的应用),调用方必须由服务账号表示。

服务账号

当调用应用使用服务账号作为其身份时,涉及以下主账号:

  • 调用方服务账号 (CALLER_SA)

    此服务账号代表调用应用,该应用发出对短期有效凭据的请求。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需授予 CALLER_SAPRIV_SA 创建短期有效凭据的权限,请在 PRIV_SA 上授予 CALLER_SA Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方服务账号的电子邮件地址 CALLER_SA

    例如 demo@my-project.iam.gserviceaccount.com

  7. 选择 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
  8. 点击保存,向服务账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_SA:表示请求短期令牌的应用的服务账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_SA 授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_SA 是创建短期令牌的服务账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

用户凭据

如果您想使用 Google Cloud CLI 生成短期有效的令牌,或者希望从本地开发环境生成短期有效的令牌,则可以使用用户账号生成令牌。通常,您可以使用自己的 Google 账号。

如果您使用用户账号生成短期有效的令牌,则涉及以下身份:

  • 调用方 Google 账号 (CALLER_ACCOUNT)

    此用户账号用于为具有权限的服务账号生成短期有效的凭据。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需使 CALLER_ACCOUNT 可以为 PRIV_SA 创建短期有效凭据,请向 CALLER_ACCOUNT 授予 PRIV_SA 的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方 Google 账号的电子邮件地址 CALLER_ACCOUNT

    例如 username@google.com

  7. 选择 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
  8. 点击保存,向用户账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_ACCOUNT:用于请求短期令牌的用户账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_ACCOUNT 授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        },
        {
          "role": "roles/iam.serviceAccountTokenCreator",
          "members": [
            "user:CALLER_ACCOUNT"
          ]
        }
      ]
    }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_ACCOUNT 是创建短期令牌的用户账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "user:CALLER_ACCOUNT"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

生成访问令牌

您可以使用 gcloud CLI、REST API 或 Cloud 客户端库和 Google API 客户端库生成 OAuth 2.0 访问令牌。

如果您使用 REST API,并且您的系统配置为允许延长令牌生命周期,则可以创建一个生命周期长于默认值的令牌。Google Cloud CLI 不支持为令牌设置生命周期。

以下示例适合在本地开发环境中使用;调用方必须由用户账号(而不是服务账号)表示。

为服务账号生成 OAuth 2.0 访问令牌:

gcloud

  1. 以调用方 Google 账号的身份登录 Google Cloud CLI。

    gcloud auth login CALLER_ACCOUNT
    
  2. 为服务账号生成令牌。

    gcloud auth print-access-token 命令可为服务账号生成 OAuth 2.0 访问令牌。

    在使用下面的命令数据之前,请先进行以下替换:

    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
      • 执行以下命令:

        Linux、macOS 或 Cloud Shell

        gcloud auth print-access-token --impersonate-service-account=PRIV_SA
        

        Windows (PowerShell)

        gcloud auth print-access-token --impersonate-service-account=PRIV_SA
        

        Windows (cmd.exe)

        gcloud auth print-access-token --impersonate-service-account=PRIV_SA
        

        您应该会收到类似如下所示的响应:

        WARNING: This command is using service account impersonation. All API calls will be executed as
        [my-sa@my-project.iam.gserviceaccount.com].
        ya29.c.b0AXv0zTPnzTnDV8F8Aj5Fgy46Yf2v_v8eZIoKq7xGpfbpXuy23aQ1693m3gAuE8AZga7w6kdagN7a9bfdDYbdeoGY0CMHOClsCwIdutL7k_RFC672lOCbUgF5hS8Iu2nCA8hle-11LJXBLmaxFmH08ZTBJLuDrWSNd8cYqGYFunSC1K1qLIPBF18tsa0hxVgKPucI8b1A9L8_MK1JGLGcr0n7-zY77_lmbcdODG3NmIbLOGWOutjJgqSO_YoeCKK2QTUZIp5PG7RkKlXWnmYJA9pEahzNoQrs5sWZctc2bia9af_ITzqqlXC9h1Kj5-me6e8rd734MJvpagqYazRk0gGWpMb03XmMGpgPc_FBp4pnX9rGOzW83SNpcDz8zeFO1Q0Bo3N7CuZougjRce0y8I2_4rtw5ME_nV3wrCWa..................................................................................................................................................................................................................................................................................................
        

REST

Service Account Credentials API 的 serviceAccounts.generateAccessToken 方法为服务账号生成 OAuth 2.0 访问令牌。

在使用任何请求数据之前,请先进行以下替换:

  • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
  • LIFETIME:访问令牌到期前的时间量(以秒为单位)。例如 300s

    默认情况下,令牌的最长生命周期为 1 小时(3600 秒)。如需将这些令牌的最长生命周期延长至 12 小时(43200 秒),请将服务账号添加到组织政策中(该政策包含 constraints/iam.allowServiceAccountCredentialLifetimeExtension 列表限制条件)。

HTTP 方法和网址:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:generateAccessToken

请求 JSON 正文:

{
  "scope": [
    "https://www.googleapis.com/auth/cloud-platform"
  ],
  "lifetime": "LIFETIME"
}

如需发送您的请求,请展开以下选项之一:

如果 generateAccessToken 请求成功,响应正文会包含一个 OAuth 2.0 访问令牌和一个到期时间。然后,便可以使用 accessToken 代表服务账号验证请求,直至到达 expireTime 时限:

{
  "accessToken": "eyJ0eXAi...NiJ9",
  "expireTime": "2020-04-07T15:01:23.045123456Z"
}

Go

您必须先为调用者 Google 账号设置应用默认凭据(您之前已为该账号授予模拟权限拥有服务账号所需的权限),然后才能使用此示例代码。

import (
	"context"
	"fmt"
	"io"
	"time"

	"golang.org/x/oauth2/google"
	"google.golang.org/api/impersonate"
	"google.golang.org/api/option"
)

// getAccessTokenFromImpersonatedCredentials uses a service account (SA1) to impersonate
// another service account (SA2) and obtain OAuth2 token for the impersonated account.
// To obtain a token for SA2, SA1 should have the "roles/iam.serviceAccountTokenCreator" permission on SA2.
func getAccessTokenFromImpersonatedCredentials(w io.Writer, impersonatedServiceAccount, scope string) error {
	// impersonatedServiceAccount := "name@project.service.gserviceaccount.com"
	// scope := "https://www.googleapis.com/auth/cloud-platform"

	ctx := context.Background()

	// Construct the GoogleCredentials object which obtains the default configuration from your
	// working environment.
	credentials, err := google.FindDefaultCredentials(ctx, scope)
	if err != nil {
		fmt.Fprintf(w, "failed to generate default credentials: %v", err)
		return fmt.Errorf("failed to generate default credentials: %w", err)
	}

	ts, err := impersonate.CredentialsTokenSource(ctx, impersonate.CredentialsConfig{
		TargetPrincipal: impersonatedServiceAccount,
		Scopes:          []string{scope},
		Lifetime:        300 * time.Second,
		// delegates: The chained list of delegates required to grant the final accessToken.
		// For more information, see:
		// https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-permissions
		// Delegates is NOT USED here.
		Delegates: []string{},
	}, option.WithCredentials(credentials))
	if err != nil {
		fmt.Fprintf(w, "CredentialsTokenSource error: %v", err)
		return fmt.Errorf("CredentialsTokenSource error: %w", err)
	}

	// Get the OAuth2 token.
	// Once you've obtained the OAuth2 token, you can use it to make an authenticated call.
	t, err := ts.Token()
	if err != nil {
		fmt.Fprintf(w, "failed to receive token: %v", err)
		return fmt.Errorf("failed to receive token: %w", err)
	}
	fmt.Fprintf(w, "Generated OAuth2 token with length %d.\n", len(t.AccessToken))

	return nil
}

Java

您必须先为调用者 Google 账号设置应用默认凭据(您之前已为该账号授予模拟权限拥有服务账号所需的权限),然后才能使用此示例代码。


package com.google.cloud.auth.samples;

import com.google.auth.oauth2.GoogleCredentials;
import com.google.auth.oauth2.ImpersonatedCredentials;
import java.io.IOException;
import java.util.Arrays;
import java.util.List;

public class AccessTokenFromImpersonatedCredentials {

  public static void main(String[] args) throws IOException {
    // TODO(Developer): Replace the below variables before running the code.

    // Provide the scopes that you might need to request access to Google APIs,
    // depending on the level of access you need.
    // This example uses the cloud-wide scope and uses IAM to narrow the permissions.
    // https://cloud.google.com/docs/authentication/external/authorization-gcp
    // For more information, see: https://developers.google.com/identity/protocols/oauth2/scopes
    String scope = "https://www.googleapis.com/auth/cloud-platform";

    // The name of the privilege-bearing service account for whom the credential is created.
    String impersonatedServiceAccount = "name@project.service.gserviceaccount.com";

    getAccessToken(impersonatedServiceAccount, scope);
  }

  // Use a service account (SA1) to impersonate another service account (SA2) and obtain an ID token
  // for the impersonated account.
  // To obtain a token for SA2, SA1 should have the "roles/iam.serviceAccountTokenCreator"
  // permission on SA2.
  public static void getAccessToken(
      String impersonatedServiceAccount, String scope) throws IOException {

    // Construct the GoogleCredentials object which obtains the default configuration from your
    // working environment.
    GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

    // delegates: The chained list of delegates required to grant the final accessToken.
    // For more information, see:
    // https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-permissions
    // Delegate is NOT USED here.
    List<String> delegates = null;

    // Create the impersonated credential.
    ImpersonatedCredentials impersonatedCredentials =
        ImpersonatedCredentials.newBuilder()
            .setSourceCredentials(googleCredentials)
            .setTargetPrincipal(impersonatedServiceAccount)
            .setScopes(Arrays.asList(scope))
            .setLifetime(300)
            .setDelegates(delegates)
            .build();

    // Get the OAuth2 token.
    // Once you've obtained the OAuth2 token, you can use it to make an authenticated call.
    impersonatedCredentials.refresh();
    String accessToken = impersonatedCredentials.getAccessToken().getTokenValue();
    System.out.println("Generated access token.");
  }
}

Node.js

您必须先为调用者 Google 账号设置应用默认凭据(您之前已为该账号授予模拟权限拥有服务账号所需的权限),然后才能使用此示例代码。

/**
 * TODO(developer):
 *  Uncomment and replace these variables before running the sample.
 */
// const impersonatedServiceAccount = 'name@project.service.gserviceaccount.com';
// const scope = 'https://www.googleapis.com/auth/cloud-platform';

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

async function getAccessTokenFromImpersonatedCredentials() {
  const googleAuth = new GoogleAuth({
    scopes: scope,
  });
  // Construct the GoogleCredentials object which obtains the default configuration from your
  // working environment.
  const {credential} = await googleAuth.getApplicationDefault();

  // delegates: The chained list of delegates required to grant the final accessToken.
  // For more information, see:
  // https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-permissions
  // Delegate is NOT USED here.
  const delegates = [];

  // Create the impersonated credential.
  const impersonatedCredentials = new Impersonated({
    sourceClient: credential,
    delegates,
    targetPrincipal: impersonatedServiceAccount,
    targetScopes: [scope],
    lifetime: 300,
  });

  // Get the OAuth2 token.
  // Once you've obtained the OAuth2 token, you can use it to make an authenticated call
  // to the target audience.
  const resp = await impersonatedCredentials.getAccessToken();
  // Token is in resp.token.
  console.log('Generated OAuth2 token with length %s', resp.token.length);
}

getAccessTokenFromImpersonatedCredentials();

Python

您必须先为调用者 Google 账号设置应用默认凭据(您之前已为该账号授予模拟权限拥有服务账号所需的权限),然后才能使用此示例代码。

def accesstoken_from_impersonated_credentials(
    impersonated_service_account: str, scope: str
):
    from google.auth import impersonated_credentials
    import google.auth.transport.requests

    """
      Use a service account (SA1) to impersonate another service account (SA2)
      and obtain an ID token for the impersonated account.
      To obtain a token for SA2, SA1 should have the
      "roles/iam.serviceAccountTokenCreator" permission on SA2.

    Args:
        impersonated_service_account: The name of the privilege-bearing service account for whom the credential is created.
            Examples: name@project.service.gserviceaccount.com

        scope: Provide the scopes that you might need to request to access Google APIs,
            depending on the level of access you need.
            For this example, we use the cloud-wide scope and use IAM to narrow the permissions.
            https://cloud.google.com/docs/authentication#authorization_for_services
            For more information, see: https://developers.google.com/identity/protocols/oauth2/scopes
    """

    # Construct the GoogleCredentials object which obtains the default configuration from your
    # working environment.
    credentials, project_id = google.auth.default()

    # Create the impersonated credential.
    target_credentials = impersonated_credentials.Credentials(
        source_credentials=credentials,
        target_principal=impersonated_service_account,
        # delegates: The chained list of delegates required to grant the final accessToken.
        # For more information, see:
        # https://cloud.google.com/iam/docs/create-short-lived-credentials-direct#sa-credentials-permissions
        # Delegate is NOT USED here.
        delegates=[],
        target_scopes=[scope],
        lifetime=300,
    )

    # Get the OAuth2 token.
    # Once you've obtained the OAuth2 token, use it to make an authenticated call
    # to the target audience.
    request = google.auth.transport.requests.Request()
    target_credentials.refresh(request)
    # The token field is target_credentials.token.
    print("Generated OAuth2 token.")

创建 OpenID Connect (OIDC) ID 令牌

ID 令牌遵循 OpenID Connect (OIDC) 规范。只有少量服务和应用接受 ID 令牌。

如需了解详情,请参阅 ID 令牌对 Cloud Run 或 Cloud Functions 上托管的应用的身份验证

如需创建 ID 令牌,请完成以下任务:

  • 为调用方提供所需的权限

    使用 Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator) 创建 ID 令牌。该角色与您用于其他令牌类型的角色不同。

  • 生成 ID 令牌

提供所需权限

直接请求涉及两种身份:请求凭据的调用方以及为其创建凭据的服务账号。设置权限的方式取决于调用方是以服务账号身份还是以 Google 账号身份进行身份验证。

如果您要在本地开发环境中运行此页面上的 REST 或 gcloud CLI 命令,调用方可以由用户凭据表示。对于自动化工作负载(例如在 Compute Engine 上运行的应用),调用方必须由服务账号表示。

服务账号

当调用应用使用服务账号作为其身份时,涉及以下主账号:

  • 调用方服务账号 (CALLER_SA)

    此服务账号代表调用应用,该应用发出对短期有效凭据的请求。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需授予 CALLER_SAPRIV_SA 创建短期有效凭据的权限,请在 PRIV_SA 上授予 CALLER_SA Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方服务账号的电子邮件地址 CALLER_SA

    例如 demo@my-project.iam.gserviceaccount.com

  7. 选择 Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator)。
  8. 点击保存,向服务账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_SA:表示请求短期令牌的应用的服务账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountOpenIdTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_SA 授予 Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountOpenIdTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_SA 是创建短期令牌的服务账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountOpenIdTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

用户凭据

如果您想使用 Google Cloud CLI 生成短期有效的令牌,或者希望从本地开发环境生成短期有效的令牌,则可以使用用户账号生成令牌。通常,您可以使用自己的 Google 账号。

如果您使用用户账号生成短期有效的令牌,则涉及以下身份:

  • 调用方 Google 账号 (CALLER_ACCOUNT)

    此用户账号用于为具有权限的服务账号生成短期有效的凭据。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需使 CALLER_ACCOUNT 可以为 PRIV_SA 创建短期有效凭据,请向 CALLER_ACCOUNT 授予 PRIV_SA 的 Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方 Google 账号的电子邮件地址 CALLER_ACCOUNT

    例如 username@google.com

  7. 选择 Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator)。
  8. 点击保存,向用户账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_ACCOUNT:用于请求短期令牌的用户账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountOpenIdTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountOpenIdTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_ACCOUNT 授予 Service Account OpenID Connect Identity Token Creator 角色 (roles/iam.serviceAccountOpenIdTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        },
        {
          "role": "roles/iam.serviceAccountOpenIdTokenCreator",
          "members": [
            "user:CALLER_ACCOUNT"
          ]
        }
      ]
    }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_ACCOUNT 是创建短期令牌的用户账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountOpenIdTokenCreator",
            "members": [
              "user:CALLER_ACCOUNT"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

生成 ID 令牌

您可以使用 gcloud CLI、REST API 或 Cloud 客户端库和 Google API 客户端库生成 OpenID Connect (OIDC) ID 令牌。

以下示例适合在本地开发环境中使用;调用方必须由用户账号(而不是服务账号)表示。

OIDC ID 令牌的有效期为 1 小时(3600 秒)。

为服务账号生成 Google 签名的 OIDC ID 令牌:

gcloud

  1. 以调用方 Google 账号的身份登录 Google Cloud CLI。

    gcloud auth login CALLER_ACCOUNT
    
  2. 为服务账号生成令牌。

    gcloud auth print-identity-token 命令会为服务账号生成 OIDC ID 令牌。

    在使用下面的命令数据之前,请先进行以下替换:

    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • AUDIENCE_NAME:令牌的受众群体,通常是令牌将用于访问的应用或服务的网址。
      • 执行以下命令:

        Linux、macOS 或 Cloud Shell

        gcloud auth print-identity-token --impersonate-service-account=PRIV_SA --audiences="AUDIENCE_NAME"
        

        Windows (PowerShell)

        gcloud auth print-identity-token --impersonate-service-account=PRIV_SA --audiences="AUDIENCE_NAME"
        

        Windows (cmd.exe)

        gcloud auth print-identity-token --impersonate-service-account=PRIV_SA --audiences="AUDIENCE_NAME"
        

        您应该会收到类似如下所示的响应:

        WARNING: This command is using service account impersonation. All API calls will be executed as
        [my-sa@my-project.iam.gserviceaccount.com].
        eyJhbGciOiJSUzI1NiIsImtpZDNhMDg4ZDRmZmMjJkYTVmZTM5MDZjY2MiLCJ0eXAiOiJKV1QifQ.eyJhdWQiOiJ3d3cuZXhhbXBsJhenAiOiIxMTYzwNDYyMDk0ODIiLCJleHAiOjE2NTQ4ODU0MzEsImlhdCI6MTY1NDg4MTgzMSwiaXN6Ly9hY2NvdW50cy5nb29nbGUuY29tIiwic3ViIMDQ2MjA5NDgyIn0.F7mu8IHj5VQdu7ItFrnYAKyGd7YqXuOP_rFLc98q8BaFBycAF1zAQnSnwqnSUXba0UK9PDT_-IOry68qLwBObz4XlX9lk0ehpN0O0W9FcFToKLB6wefXXPd4h7xtuPe5KzmpSOqj2Qqv34HriGw00Nqd-oGSgNY_lZ4wGEf4rT4oQa_kEcrY57Q2G6pwd769BhgeFwoLi5aK_Cv2kvf_zfMszC-xlkP9zwWQ8XinJBwe-qcQBa4NTgrbueNtXsEjccBS366zmw
        

REST

Service Account Credentials API 的 serviceAccounts.generateIdToken 方法为服务账号生成 OIDC ID 令牌。

在使用任何请求数据之前,请先进行以下替换:

  • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
  • AUDIENCE_NAME:令牌的受众群体,通常是令牌将用于访问的应用或服务的网址。

HTTP 方法和网址:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:generateIdToken

请求 JSON 正文:

{
  "audience": "AUDIENCE_NAME",
  "includeEmail": "true"
}

如需发送您的请求,请展开以下选项之一:

如果 generateId 请求成功,则响应正文会包含一个有效期为 1 小时的 ID 令牌。然后,便可以使用 token 代表服务账号验证请求:

{
  "token": "eyJ0eXAi...NiJ9"
}

创建自签名 JSON Web 令牌 (JWT)

自签名 JSON Web 令牌 (JWT) 在各种场景中都很有用:

  • 向使用 API Gateway 部署的 API 进行身份验证。
  • 按照 Google 的身份验证指南中的说明验证对 Google API 的调用。
  • 在您自己的应用之间安全地进行通信。在此场景中,一个应用可对一个令牌签名,而在进行身份验证时,该令牌可以由另一个应用进行验证。
  • 通过签署包含有关用户、账号或设备的任意声明的 JWT,将服务账号视为身份提供方。

如需创建 JWT,请完成以下任务:

提供所需权限

直接请求涉及两种身份:请求凭据的调用方以及为其创建凭据的服务账号。设置权限的方式取决于调用方是以服务账号身份还是以 Google 账号身份进行身份验证。

如果您要在本地开发环境中运行此页面上的 REST 或 gcloud CLI 命令,调用方可以由用户凭据表示。对于自动化工作负载(例如在 Compute Engine 上运行的应用),调用方必须由服务账号表示。

服务账号

当调用应用使用服务账号作为其身份时,涉及以下主账号:

  • 调用方服务账号 (CALLER_SA)

    此服务账号代表调用应用,该应用发出对短期有效凭据的请求。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需授予 CALLER_SAPRIV_SA 创建短期有效凭据的权限,请在 PRIV_SA 上授予 CALLER_SA Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方服务账号的电子邮件地址 CALLER_SA

    例如 demo@my-project.iam.gserviceaccount.com

  7. 选择 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
  8. 点击保存,向服务账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_SA:表示请求短期令牌的应用的服务账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_SA 授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_SA 是创建短期令牌的服务账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

用户凭据

如果您想使用 Google Cloud CLI 生成短期有效的令牌,或者希望从本地开发环境生成短期有效的令牌,则可以使用用户账号生成令牌。通常,您可以使用自己的 Google 账号。

如果您使用用户账号生成短期有效的令牌,则涉及以下身份:

  • 调用方 Google 账号 (CALLER_ACCOUNT)

    此用户账号用于为具有权限的服务账号生成短期有效的凭据。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需使 CALLER_ACCOUNT 可以为 PRIV_SA 创建短期有效凭据,请向 CALLER_ACCOUNT 授予 PRIV_SA 的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方 Google 账号的电子邮件地址 CALLER_ACCOUNT

    例如 username@google.com

  7. 选择 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
  8. 点击保存,向用户账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_ACCOUNT:用于请求短期令牌的用户账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_ACCOUNT 授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        },
        {
          "role": "roles/iam.serviceAccountTokenCreator",
          "members": [
            "user:CALLER_ACCOUNT"
          ]
        }
      ]
    }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_ACCOUNT 是创建短期令牌的用户账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "user:CALLER_ACCOUNT"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

生成 JWT

生成自签名 JWT:

REST

Service Account Credentials API 的 serviceAccounts.signJwt 方法使用服务账号的系统管理私钥来对 JWT 进行签名。

在使用任何请求数据之前,请先进行以下替换:

  • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
  • JWT_PAYLOAD:需要签名的 JWT 载荷,它是一个包含 JWT 声明集的 JSON 对象。包含您所需用例必需的且满足您要调用的服务验证要求必需的声明。如果您要调用 Google API,请参阅 Google 的身份验证指南了解声明要求。

    exp(到期时间)声明不得超过未来 12 小时。如果您要调用 Google API,则 exp 声明必须设置为不超过未来 1 小时。

    以下示例载荷包含调用 Google API 的声明,其中 EXP 是表示到期时间的整数时间戳:

    { \"iss\": \"PRIV_SA\", \"sub\": \"PRIV_SA\", \"aud\": \"https://firestore.googleapis.com/\", \"iat\": 1529350000, \"exp\": EXP }

HTTP 方法和网址:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:signJwt

请求 JSON 正文:

{
  "payload": "JWT_PAYLOAD"
}

如需发送您的请求,请展开以下选项之一:

如果 signJwt 请求成功,则响应正文会包含已签名的 JWT 以及用于签署 JWT 的签名密钥 ID。您可以将 signedJwt 值用作不记名令牌,以代表服务账号直接验证请求。令牌在请求中指定的到期时间内有效:

{
  "keyId": "42ba1e...fc0a",
  "signedJwt": "eyJ0eXAi...NiJ9"
}

创建自签名二进制对象 (blob)

自签名二进制对象 (blob) 用于传输二进制数据,其传输方法使数据来源可知(因为 blob 是自签名的)。blob 可用于创建签名,这是各种身份验证流程(包括签名网址)所需的 Cloud Storage 对象。如需了解签名,请参阅 Cloud Storage 文档

如需创建自签名二进制对象,请完成以下任务:

提供所需权限

直接请求涉及两种身份:请求凭据的调用方以及为其创建凭据的服务账号。设置权限的方式取决于调用方是以服务账号身份还是以 Google 账号身份进行身份验证。

如果您要在本地开发环境中运行此页面上的 REST 或 gcloud CLI 命令,调用方可以由用户凭据表示。对于自动化工作负载(例如在 Compute Engine 上运行的应用),调用方必须由服务账号表示。

服务账号

当调用应用使用服务账号作为其身份时,涉及以下主账号:

  • 调用方服务账号 (CALLER_SA)

    此服务账号代表调用应用,该应用发出对短期有效凭据的请求。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需授予 CALLER_SAPRIV_SA 创建短期有效凭据的权限,请在 PRIV_SA 上授予 CALLER_SA Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方服务账号的电子邮件地址 CALLER_SA

    例如 demo@my-project.iam.gserviceaccount.com

  7. 选择 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
  8. 点击保存,向服务账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_SA:表示请求短期令牌的应用的服务账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=serviceAccount:CALLER_SA --role=roles/iam.serviceAccountTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "serviceAccount:CALLER_SA"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwXhCB4eyjY=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_SA 授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_SA 是创建短期令牌的服务账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "serviceAccount:CALLER_SA"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

用户凭据

如果您想使用 Google Cloud CLI 生成短期有效的令牌,或者希望从本地开发环境生成短期有效的令牌,则可以使用用户账号生成令牌。通常,您可以使用自己的 Google 账号。

如果您使用用户账号生成短期有效的令牌,则涉及以下身份:

  • 调用方 Google 账号 (CALLER_ACCOUNT)

    此用户账号用于为具有权限的服务账号生成短期有效的凭据。

  • 具有权限的服务账号 (PRIV_SA)

    此服务账号会被授予短期有效令牌所需的 IAM 角色。这是为其创建短期有效令牌的服务账号。

如需使 CALLER_ACCOUNT 可以为 PRIV_SA 创建短期有效凭据,请向 CALLER_ACCOUNT 授予 PRIV_SA 的 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

PRIV_SA 上授予所需的角色:

控制台

  1. 在 Google Cloud 控制台中,转到服务账号页面。

    转到“服务账号”

  2. 选择一个项目。
  3. 点击具有权限的服务账号 PRIV_SA 的电子邮件地址。
  4. 点击权限标签页。
  5. 有权访问此服务账号的主账号下,点击 授予访问权限
  6. 输入调用方 Google 账号的电子邮件地址 CALLER_ACCOUNT

    例如 username@google.com

  7. 选择 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。
  8. 点击保存,向用户账号授予角色。

gcloud

gcloud iam service-accounts add-iam-policy-binding 命令可向服务账号授予角色。

在使用下面的命令数据之前,请先进行以下替换:

  • PRIV_SA:生成令牌的具有权限的服务账号的电子邮件地址。
  • CALLER_ACCOUNT:用于请求短期令牌的用户账号的电子邮件地址。

执行以下命令:

Linux、macOS 或 Cloud Shell

gcloud iam service-accounts add-iam-policy-binding PRIV_SA \
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (PowerShell)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA `
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

Windows (cmd.exe)

gcloud iam service-accounts add-iam-policy-binding PRIV_SA ^
    --member=user:CALLER_ACCOUNT --role=roles/iam.serviceAccountTokenCreator --format=json

您应该会收到类似如下所示的响应:

Updated IAM policy for serviceAccount [PRIV_SA].
{
  "bindings": [
    {
      "members": [
        "user:CALLER_ACCOUNT"
      ],
      "role": "roles/iam.serviceAccountTokenCreator"
    }
  ],
  "etag": "BwX1ZbefjXU=",
  "version": 1
}

REST

  1. 读取 PRIV_SA 的允许政策:

    serviceAccounts.getIamPolicy 方法可获取服务账号的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA:getIamPolicy

    请求 JSON 正文:

    {
      "options": {
        "requestedPolicyVersion": POLICY_VERSION
      }
    }
    

    如需发送您的请求,请展开以下选项之一:

    您应该收到类似以下内容的 JSON 响应:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        }
      ]
    }
    

    如果您尚未为服务账号授予任何角色,则响应将只包含 etag 值。请在下一步中添加该 etag 值。

  2. 修改允许政策以向 CALLER_ACCOUNT 授予 Service Account Token Creator 角色 (roles/iam.serviceAccountTokenCreator)。

    例如,如需修改上一步中的示例响应,请添加以下内容:

    {
      "version": 1,
      "etag": "BwWKmjvelug=",
      "bindings": [
        {
          "role": "roles/serviceAccountAdmin",
          "members": [
            "user:admin@example.com"
          ]
        },
        {
          "role": "roles/iam.serviceAccountTokenCreator",
          "members": [
            "user:CALLER_ACCOUNT"
          ]
        }
      ]
    }
    
  3. 写入更新后的允许政策:

    serviceAccounts.setIamPolicy 方法会为服务账号设置更新后的允许政策。

    在使用任何请求数据之前,请先进行以下替换:

    • PROJECT_ID:您的 Google Cloud 项目 ID。项目 ID 是字母数字字符串,例如 my-project
    • PRIV_SA:为其创建短期令牌且具有相应权限的服务账号的电子邮件地址。
    • POLICY_VERSION:要返回的政策版本。请求应指定最新的政策版本,即政策版本 3。如需了解详情,请参阅在获取政策时指定政策版本
    • POLICY:您要设置的政策的 JSON 格式。如需详细了解政策的格式,请参阅政策参考

      例如,要设置上一步中显示的允许政策,请将 POLICY 替换为以下内容,其中 CALLER_ACCOUNT 是创建短期令牌的用户账号:

      {
        "version": 1,
        "etag": "BwWKmjvelug=",
        "bindings": [
          {
            "role": "roles/serviceAccountAdmin",
            "members": [
              "user:admin@example.com"
            ]
          },
          {
            "role": "roles/iam.serviceAccountTokenCreator",
            "members": [
              "user:CALLER_ACCOUNT"
            ]
          }
        ]
      }
      

    HTTP 方法和网址:

    POST https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/PRIV_SA

    请求 JSON 正文:

    {
      "policy": POLICY
    }
    

    如需发送您的请求,请展开以下选项之一:

    响应包含更新后的允许政策。

生成自签名 blob

为服务账号生成自签名 blob:

REST

Service Account Credentials API 的 serviceAccounts.signBlob 方法使用服务账号的系统管理私钥来对 blob 进行签名。

在使用任何请求数据之前,请先进行以下替换:

  • PRIV_SA:为其创建短期令牌的具有权限的服务账号的电子邮件地址。
  • BLOB_PAYLOAD:Base64 编码的字节串。例如,VGhlIHF1aWNrIGJyb3duIGZveCBqdW1wZWQgb3ZlciB0aGUgbGF6eSBkb2cu

HTTP 方法和网址:

POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/PRIV_SA:signBlob

请求 JSON 正文:

{
  "payload": "BLOB_PAYLOAD"
}

如需发送您的请求,请展开以下选项之一:

如果 signBlob 请求成功,则响应正文会包含已签名的 blob 以及用于签署 blob 的签名密钥 ID。您可以将 signedBlob 值用作不记名令牌,以代表服务账号直接验证请求。在服务账号的系统管理私钥到期之前,该令牌有效。此密钥的 ID 是响应中 keyId 字段的值。

{
  "keyId": "42ba1e...fc0a",
  "signedBlob": "eyJ0eXAi...NiJ9"
}