為叫用進行驗證 (第 1 代)

如要叫用已通過驗證的 Cloud Run 函式，基礎主體必須符合下列規定：

• 有權叫用函式。
• 在函式叫用時提供 ID 權杖。

什麼是本金？如「保護 Cloud Run 函式安全」一文所述，Cloud Run 函式支援兩種不同的身分，也稱為主體：

• 服務帳戶：這類特殊帳戶可做為非人員的身分，例如函式、應用程式或 VM。讓您驗證這些非人身分。
• 使用者帳戶：這類帳戶代表使用者，可以是個別 Google 帳戶持有人，也可以是 Google 控制實體 (例如 Google 群組) 的成員。

如要進一步瞭解基本 IAM 概念，請參閱 IAM 總覽。

如要叫用經過驗證的 Cloud Run 函式，主體必須具備叫用者 IAM 權限：

• cloudfunctions.functions.invoke。這通常是透過叫用者角色。

如要授予這些權限，請使用 add-invoker-policy-binding 指令，如「驗證函式對函式的呼叫」一文所示。

如要建立、更新函式或對函式執行其他管理動作，主體必須具備適當的角色。角色包含權限，可定義主體可執行的動作。詳情請參閱「使用 IAM 授權存取權」。

呼叫函式可能會增加複雜度。事件驅動函式只能由訂閱的事件來源叫用，但HTTP 函式可由不同類型的身分叫用，且來源位置不同。呼叫者可能是測試函式的開發人員，也可能是想使用函式的其他函式或服務。根據預設，這些身分必須在要求中提供 ID 權杖，才能驗證身分。此外，使用的帳戶也必須具備適當權限。

進一步瞭解如何產生及使用 ID 權杖。

注意： 所有函式都可以使用 call API 叫用。您應該只將這個 API 用於測試。請勿在正式環境中使用。

驗證範例

本節將提供幾個不同的範例，說明如何驗證呼叫。

範例 1：驗證開發人員測試

開發人員需要建立、更新及刪除函式的存取權，而這項權限是透過一般 (IAM) 程序授予。

但開發人員可能需要叫用函式進行測試。如要使用 curl 或類似工具叫用函式，請注意下列事項：

• 將包含叫用權限的角色指派給 Cloud Run 函式使用者帳戶。

  • cloudfunctions.functions.invoke。這通常是透過叫用者角色。根據預設，「Cloud Run 函式管理員」和「Cloud Run 函式開發人員」角色具有這項權限。請參閱 Cloud Run Functions IAM 角色，取得完整的角色清單和相關聯的權限。

• 如果您是使用本機電腦工作，請初始化 Google Cloud CLI，設定指令列存取權。

• 請在 Authorization 標頭中，以 Google 產生的 ID 權杖形式，提供驗證憑證給要求。舉例來說，如要使用 gcloud 取得 ID 權杖，請執行下列指令：

  curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
    https://FUNCTION_URL

  其中 FUNCTION_URL 是函式的網址。從Google Cloud 控制台的 Cloud Run 函式頁面擷取這個網址，或執行 gcloud functions describe 指令，如「Google Cloud CLI 部署指令」範例的第一個步驟所示。

只要帳戶對要叫用的函式具有 cloudfunctions.functions.invoke 權限，您就能使用 gcloud 建立的權杖，在任何專案中叫用 HTTP 函式。在開發方面，請使用 gcloud 產生的 ID 權杖。不過請注意，這類權杖缺少目標對象聲明，因此容易受到中繼攻擊。在正式版環境中，請使用為服務帳戶核發的 ID 權杖，並指定適當的目標對象。這種做法可限制權杖只能用於預期服務，進而提升安全性。

一如往常，我們建議您分配開發及使用函式所需的最低權限組合。請確保函式的 IAM 政策僅限於最少數量的使用者和服務帳戶。

範例 2：驗證函式對函式的呼叫

建構連線到多個函式的服務時，最好確保每個函式都只能對其他函式的特定子集傳送要求。舉例來說，如果您有 login 函式，應該可以存取 user profiles 函式，但可能無法存取 search 函式。

如要將接收函式設定為接受來自特定呼叫函式的要求，您必須在接收函式中，將適當的叫用者角色授予呼叫函式的服務帳戶。叫用者角色為 Cloud Run 函式叫用者 (roles/cloudfunctions.invoker)：

控制台

使用 Cloud Run functions Invoker：

1. 前往 Google Cloud 控制台：

   前往 Google Cloud 控制台

2. 按一下接收函式旁邊的核取方塊，(請勿點選函式本身)。

3. 按一下畫面頂端的「權限」。「權限」面板隨即開啟。

4. 按一下「新增主體」。

5. 在「New principals」(新增主體) 欄位中，輸入呼叫函式的身分。 這應該是服務帳戶電子郵件地址。

6. 從「Select a role」(請選擇角色) 下拉式選單中，選取「Cloud Functions > Cloud Functions Invoker」(Cloud Functions > Cloud Functions 叫用者) 角色。

7. 按一下 [儲存]。

gcloud

使用 gcloud functions add-invoker-policy-binding 指令：

gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \
  --member='serviceAccount:CALLING_FUNCTION_IDENTITY'

add-invoker-policy-binding 指令會新增叫用者角色 IAM 政策繫結，允許指定成員 (主體) 叫用指定函式。Google Cloud CLI 會自動偵測函式產生作業，並新增正確的叫用者角色 (第 1 代為 cloudfunctions.invoker)。

更改下列內容：

• RECEIVING_FUNCTION：接收函式的名稱。
• CALLING_FUNCTION_IDENTITY：呼叫函式身分，即服務帳戶電子郵件地址。

由於這會叫用接收函式，因此呼叫函式也必須提供 Google 簽署的 ID 權杖進行驗證。這個過程分為兩步驟：

1. 建立 Google 簽署的 ID 權杖，並將目標對象欄位 (aud) 設定為接收函式的網址。

2. 在向函式提出要求的 Authorization: Bearer ID_TOKEN 標頭中加入 ID 符記。

目前最簡單可靠的管理方式，就是使用驗證程式庫產生及採用這個權杖，如下所示。

產生 ID 權杖

本節說明產生主體呼叫函式所需 ID 權杖的幾種方式。

您可以在沒有 ID 權杖的情況下進行未經驗證的存取，但必須啟用這項功能。詳情請參閱「使用 IAM 授權存取權」。

注意： ID 權杖也包含所代表身分的相關資訊。如要存取這項資訊，可以使用廣泛可用的程式庫。

透過程式產生權杖

下列程式碼產生 ID 權杖後，會代表您使用該權杖呼叫 Cloud Run 函式。只要程式庫可以取得驗證憑證，這段程式碼就能在任何環境中運作，包括支援本機應用程式預設憑證的環境。

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */

// Cloud Functions uses your function's url as the `targetAudience` value
// const targetAudience = 'https://project-region-projectid.cloudfunctions.net/myFunction';
// For Cloud Functions, endpoint (`url`) and `targetAudience` should be equal
// const url = targetAudience;


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

async function request() {
  console.info(`request ${url} with target audience ${targetAudience}`);
  const client = await auth.getIdTokenClient(targetAudience);

  // Alternatively, one can use `client.idTokenProvider.fetchIdToken`
  // to return the ID Token.
  const res = await client.fetch(url);
  console.info(res.data);
}

request().catch(err => {
  console.error(err.message);
  process.exitCode = 1;
});

Python

import urllib

import google.auth.transport.requests
import google.oauth2.id_token


def make_authorized_get_request(endpoint, audience):
    """
    make_authorized_get_request makes a GET request to the specified HTTP endpoint
    by authenticating with the ID token obtained from the google-auth client library
    using the specified audience value.
    """

    # Cloud Functions uses your function's URL as the `audience` value
    # audience = https://project-region-projectid.cloudfunctions.net/myFunction
    # For Cloud Functions, `endpoint` and `audience` should be equal

    req = urllib.request.Request(endpoint)

    auth_req = google.auth.transport.requests.Request()
    id_token = google.oauth2.id_token.fetch_id_token(auth_req, audience)

    req.add_header("Authorization", f"Bearer {id_token}")
    response = urllib.request.urlopen(req)

    return response.read()

Go

import (
	"context"
	"fmt"
	"io"

	"google.golang.org/api/idtoken"
)

// `makeGetRequest` makes a request to the provided `targetURL`
// with an authenticated client using audience `audience`.
func makeGetRequest(w io.Writer, targetURL string, audience string) error {
	// For Cloud Functions, endpoint (`serviceUrl`) and `audience` are the same.
	// Example `audience` value (Cloud Functions): https://<PROJECT>-<REGION>-<PROJECT_ID>.cloudfunctions.net/myFunction
	// (`targetURL` and `audience` will differ for GET parameters)
	ctx := context.Background()

	// client is a http.Client that automatically adds an "Authorization" header
	// to any requests made.
	client, err := idtoken.NewClient(ctx, audience)
	if err != nil {
		return fmt.Errorf("idtoken.NewClient: %w", err)
	}

	resp, err := client.Get(targetURL)
	if err != nil {
		return fmt.Errorf("client.Get: %w", err)
	}
	defer resp.Body.Close()
	if _, err := io.Copy(w, resp.Body); err != nil {
		return fmt.Errorf("io.Copy: %w", err)
	}

	return nil
}

Java

import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.auth.oauth2.IdTokenCredentials;
import com.google.auth.oauth2.IdTokenProvider;
import java.io.IOException;

public class Authentication {

  // makeGetRequest makes a GET request to the specified Cloud Run or
  // Cloud Functions endpoint `serviceUrl` (must be a complete URL), by
  // authenticating with an ID token retrieved from Application Default
  // Credentials using the specified `audience`.
  //
  // For Cloud Functions, endpoint (`serviceUrl`) and `audience` are the same.
  // Example `audience` value (Cloud Functions): https://project-region-projectid.cloudfunctions.net/myFunction
  public static HttpResponse makeGetRequest(String serviceUrl, String audience) throws IOException {
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
    if (!(credentials instanceof IdTokenProvider)) {
      throw new IllegalArgumentException("Credentials are not an instance of IdTokenProvider.");
    }
    IdTokenCredentials tokenCredential =
        IdTokenCredentials.newBuilder()
            .setIdTokenProvider((IdTokenProvider) credentials)
            .setTargetAudience(audience)
            .build();

    GenericUrl genericUrl = new GenericUrl(serviceUrl);
    HttpCredentialsAdapter adapter = new HttpCredentialsAdapter(tokenCredential);
    HttpTransport transport = new NetHttpTransport();
    HttpRequest request = transport.createRequestFactory(adapter).buildGetRequest(genericUrl);
    return request.execute();
  }
}

手動產生權杖

如果您要叫用函式，但基於某些原因無法使用驗證程式庫，可以透過兩種方式手動取得 ID 權杖：使用 Compute 中繼資料伺服器，或是建立自行簽署的 JWT 並換取 Google 簽署的 ID 權杖。

注意： 如要瞭解其他取得這個權杖的方式，請參閱「取得 ID 權杖的方法」。

使用中繼資料伺服器

您可以使用 Compute 中繼資料伺服器，擷取特定目標對象的 ID 權杖，如下所示：

curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE" \
     -H "Metadata-Flavor: Google"

將 AUDIENCE 替換為您要呼叫的函式網址。 如要擷取這個網址，請參閱上方的「驗證開發人員測試」一節。

注意： 這個方法不適用於本機。

使用自行簽署的 JWT 交換 Google 簽署的 ID 符記

1. 在接收函式中，將叫用者 (roles/cloudfunctions.invoker) 角色授予呼叫函式的服務帳戶。

2. 建立服務帳戶和金鑰，然後將內含私密金鑰的檔案 (JSON 格式) 下載至主機，呼叫函式或服務會從該主機發出要求。

3. 建立 JWT，並將標頭設為 {"alg":"RS256","typ":"JWT"}。酬載應包含設為接收函式網址的 target_audience 聲明，以及設為上述服務帳戶電子郵件地址的 iss 和 sub 聲明。也應包含 exp 和 iat 聲明。aud 聲明應設為 https://www.googleapis.com/oauth2/v4/token。

4. 使用上述下載的私密金鑰簽署 JWT。

5. 使用這個 JWT，將 POST 要求傳送至 https://www.googleapis.com/oauth2/v4/token。驗證資料必須包含在要求標頭和主體中。

   在標題中：

   Authorization: Bearer $JWT - where $JWT is the JWT you just created
   Content-Type: application/x-www-form-urlencoded
   

   在內文中：

   grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=$JWT
   

   將 $JWT 替換為您剛建立的 JWT

   這會傳回另一個 JWT，其中包含 Google 簽署的 id_token。

將 GET/POST 要求傳送至接收函式。在要求中，將 Google 簽署的 ID 權杖加入 Authorization: Bearer ID_TOKEN_JWT 標頭。

注意： Google 簽署的 ID 權杖會在最初產生要求的 1 小時後過期。

後續步驟

• 瞭解如何管理函式存取權。

• 如需其他產生 ID 權杖的方式，請參閱這篇文章。