驗證服務對服務

如果架構使用多項服務，這些服務可能需要以非同步或同步方式互相通訊。其中許多服務可能不公開，因此需要憑證才能存取。

注意： 如果兩個服務位於相同區域，則服務對服務流量不會產生網路費用。

如要進行非同步通訊，可以使用下列 Google Cloud 服務：

• Cloud Tasks：適用於一對一非同步通訊
• Pub/Sub：用於一對多、一對一和多對一非同步通訊
• Cloud Scheduler：用於定期排定的非同步通訊
• Eventarc：用於事件型通訊

在上述所有情況下，所使用的服務會根據您設定的配置，管理與接收服務的互動。

但如果是「同步」通訊，服務會使用端點網址，透過 HTTP 直接呼叫其他服務。在這種情況下，您應確保每項服務只能向特定服務提出要求。舉例來說，如果您有 login 服務，則應該可以存取 user-profiles 服務，但無法存取 search 服務。

在這種情況下，Google 建議您使用 IAM 和服務身分，並根據各項服務的使用者自行管理服務帳戶，授予執行工作所需的最低權限。

此外，要求必須提供呼叫服務的身分證明。如要這麼做，請設定呼叫服務，在要求中加入 Google 簽署的 OpenID Connect ID 權杖。

設定服務帳戶

注意： 如果沒有要使用的服務帳戶，可以建立新的服務帳戶。

如要設定服務帳戶，請將呼叫服務的服務帳戶設為接收服務的主體，藉此設定接收服務接受來自呼叫服務的要求。接著，您會將 Cloud Run 叫用者 (roles/run.invoker) 角色授予該服務帳戶。如要執行這兩項工作，請按照適當分頁中的指示操作：

主控台使用者介面

1. 前往 Google Cloud 控制台

   前往 Google Cloud 控制台

2. 選取接收的服務。

3. 按一下右上角的 [Show Info Panel] (顯示資訊面板)，顯示「Permissions」(權限) 分頁。

4. 按一下「Add principal」(新增主體)。

   1. 輸入呼叫服務的身分。這通常是電子郵件地址，預設為 [e-mail]。

   2. 從「Select a role」(選取角色) 下拉式選單中選取「Cloud Run Invoker」角色。

   3. 按一下 [儲存]。

gcloud

使用 gcloud run services add-iam-policy-binding 指令：

gcloud run services add-iam-policy-binding RECEIVING_SERVICE \
  --member='serviceAccount:CALLING_SERVICE_IDENTITY' \
  --role='roles/run.invoker'

其中 RECEIVING_SERVICE 是接收服務的名稱，CALLING_SERVICE_IDENTITY 則是服務帳戶的電子郵件地址，預設為 [e-mail]。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。

在 Terraform 設定中，將下列內容新增至 google_cloud_run_v2_service 資源：

resource "google_cloud_run_v2_service" "public" {
  name     = "public-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      # TODO<developer>: replace this with a public service container
      # (This service can be invoked by anyone on the internet)
      image = "us-docker.pkg.dev/cloudrun/container/hello"

      # Include a reference to the private Cloud Run
      # service's URL as an environment variable.
      env {
        name  = "URL"
        value = google_cloud_run_v2_service.private.uri
      }
    }
    # Give the "public" Cloud Run service
    # a service account's identity
    service_account = google_service_account.default.email
  }
}

將 us-docker.pkg.dev/cloudrun/container/hello 替換為容器映像檔的參照。

下列 Terraform 程式碼會將初始服務設為公開。

data "google_iam_policy" "public" {
  binding {
    role = "roles/run.invoker"
    members = [
      "allUsers",
    ]
  }
}

resource "google_cloud_run_service_iam_policy" "public" {
  location = google_cloud_run_v2_service.public.location
  project  = google_cloud_run_v2_service.public.project
  service  = google_cloud_run_v2_service.public.name

  policy_data = data.google_iam_policy.public.policy_data
}

下列 Terraform 程式碼會建立第二個 Cloud Run 服務，並設為私人。

resource "google_cloud_run_v2_service" "private" {
  name     = "private-service"
  location = "us-central1"

  deletion_protection = false # set to "true" in production

  template {
    containers {
      // TODO<developer>: replace this with a private service container
      // (This service should only be invocable by the public service)
      image = "us-docker.pkg.dev/cloudrun/container/hello"
    }
  }
}

將 us-docker.pkg.dev/cloudrun/container/hello 替換為容器映像檔的參照。

下列 Terraform 程式碼會建立服務帳戶。

resource "google_service_account" "default" {
  account_id   = "cloud-run-interservice-id"
  description  = "Identity used by a public Cloud Run service to call private Cloud Run services."
  display_name = "cloud-run-interservice-id"
}

下列 Terraform 程式碼只會將叫用權限授予呼叫服務帳戶，讓第二項服務成為私人服務。

data "google_iam_policy" "private" {
  binding {
    role = "roles/run.invoker"
    members = [
      "serviceAccount:${google_service_account.default.email}",
    ]
  }
}

resource "google_cloud_run_service_iam_policy" "private" {
  location = google_cloud_run_v2_service.private.location
  project  = google_cloud_run_v2_service.private.project
  service  = google_cloud_run_v2_service.private.name

  policy_data = data.google_iam_policy.private.policy_data
}

取得並設定 ID 權杖

將適當角色授予呼叫服務帳戶後，請按照下列步驟操作：

1. 使用下列任一方法，擷取 Google 簽署的 ID 權杖。將目標對象宣告 (aud) 設為接收服務的網址或設定的自訂目標對象。如果您未使用自訂目標對象，即使向特定流量標記提出要求，aud 值也必須維持服務網址。

   注意： aud 值目前不支援自訂網域。

2. 在向接收服務發出的要求中，將上一步擷取的 ID 權杖新增至下列其中一個標頭：

   • Authorization: Bearer ID_TOKEN 標頭。
   • X-Serverless-Authorization: Bearer ID_TOKEN 標頭。如果應用程式已使用 Authorization 標頭進行自訂授權，則可使用這個標頭。這會在將權杖傳遞至使用者容器之前移除簽章。
   注意： 如果同時提供這兩個標頭，系統只會檢查 X-Serverless-Authorization 標頭。

如要瞭解本頁未說明的其他 ID 權杖取得方式，請參閱「取得 ID 權杖的方法」。

使用驗證程式庫

取得及設定 ID 權杖程序的方法之一，是使用驗證程式庫。只要程式庫可以取得服務帳戶的驗證憑證，這段程式碼就能在任何環境中運作，包括 Google Cloud以外的環境。如要使用這個方法，請下載服務帳戶金鑰檔案，並將環境變數 GOOGLE_APPLICATION_CREDENTIALS 設為服務帳戶金鑰檔案的路徑。詳情請參閱「服務帳戶金鑰」。

注意： 如未妥善管理服務帳戶金鑰，可能會產生安全性風險，請盡可能 選用比服務帳戶金鑰還要安全的替代方案。如果一定要使用服務帳戶金鑰進行驗證，您有責任保護私密金鑰的安全，並執行「 管理服務帳戶金鑰的最佳做法」一文所述的其他作業。假如無法建立服務帳戶金鑰，可能是因為貴組織已停用這項功能。詳情請參閱「 管理預設採用安全設定的組織資源」。

如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「外部來源憑證的安全規定」一節。

這段程式碼不接受使用者帳戶的驗證憑證。

Node.js

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// Example: https://my-cloud-run-service.run.app/books/delete/12345
// const url = 'https://TARGET_HOSTNAME/TARGET_URL';

// Example (Cloud Run): https://my-cloud-run-service.run.app/
// const targetAudience = 'https://TARGET_AUDIENCE/';

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 Run uses your service's hostname as the `audience` value
    # audience = 'https://my-cloud-run-service.run.app/'
    # For Cloud Run, `endpoint` is the URL (hostname + path) receiving the request
    # endpoint = 'https://my-cloud-run-service.run.app/my/awesome/url'

    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 {
	// Example `audience` value (Cloud Run): https://my-cloud-run-service.run.app/
	// (`targetURL` and `audience` will differ for non-root URLs and 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`.
  //
  // Example `audience` value (Cloud Run): https://my-cloud-run-service.run.app/
  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();
  }
}

使用中繼資料伺服器

如果因故無法使用驗證程式庫，您可以在容器於 Cloud Run 執行時，從 Compute 中繼資料伺服器擷取 ID 權杖。請注意，這個方法不適用於 Google Cloud以外的環境，包括本機。

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

其中 AUDIENCE 是您叫用的服務網址，或設定的自訂目標對象。

下表摘要說明中繼資料查詢要求的主要部分：

元件	說明
根網址	所有中繼資料值都定義為下列根網址下方的子路徑： http://metadata.google.internal/computeMetadata/v1
要求標頭	每項要求都必須包含下列標頭： Metadata-Flavor: Google 此標頭指示是在擷取中繼資料值的意圖之下傳送要求，而非隨意從不安全的來源傳送，並允許中繼資料伺服器傳回您要求的資料。如未提供這個標頭，中繼資料伺服器會拒絕要求。 注意：先前，要求中必須包含 X-Google-Metadata-Request: True 標頭。這兩個標頭仍受支援，但建議您使用 Metadata-Flavor 標頭，而非 X-Google-Metadata-Request: True 標頭。

注意： ID 權杖是 JSON Web Token (JWT)，會在建立後約一小時過期。如果從中繼資料伺服器擷取權杖，您一律會取得有效權杖。如果您選擇自行快取權杖，可以解碼權杖並查看 exp 時間，確認是否需要重新整理權杖。

如要瞭解使用這項服務對服務驗證技術的應用程式端對端逐步操作說明，請參閱保護 Cloud Run 服務教學課程。

從 Google Cloud外部使用 Workload Identity Federation

如果環境使用的識別資訊提供者支援Workload Identity Federation，您可以使用下列方法，從 Google Cloud外部安全地向 Cloud Run 服務進行驗證：

1. 按照本頁「設定服務帳戶」一節的說明設定服務帳戶。

2. 按照「設定 Workload Identity Federation」一文所述，為識別資訊提供者設定 Workload Identity Federation。

3. 請按照「授予外部身分模擬服務帳戶的權限」一節的操作說明操作。

4. 使用 REST API 取得短期權杖，但不要呼叫 generateAccessToken 來取得存取權杖，而是呼叫 generateIdToken 來取得 ID 權杖。

   例如，使用 cURL：

   ID_TOKEN=$(curl -0 -X POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/SERVICE_ACCOUNT:generateIdToken \
     -H "Content-Type: text/json; charset=utf-8" \
     -H "Authorization: Bearer $STS_TOKEN" \
     -d @- <<EOF | jq -r .token
     {
         "audience": "SERVICE_URL"
     }
   EOF
   )
   echo $ID_TOKEN

   其中 SERVICE_ACCOUNT 是 workload identity pool 設定存取的服務帳戶電子郵件地址，SERVICE_URL 則是您叫用的 Cloud Run 服務網址。即使向特定流量標記提出要求，這個值仍應保持為服務的網址。$STS_TOKEN 是您在 Workload Identity Federation 操作說明中，上一個步驟收到的 Security Token Service 權杖。

您可以使用 Authorization: Bearer ID_TOKEN 標頭或 X-Serverless-Authorization: Bearer ID_TOKEN 標頭，在向服務提出的要求中加入上一個步驟的 ID 權杖。如果同時提供這兩個標頭，系統只會檢查 X-Serverless-Authorization 標頭。

從 Google Cloud外部使用下載的服務帳戶金鑰

如果 Workload Identity Federation 不適用於您的環境，可以使用下載的服務帳戶金鑰，從Google Cloud外部進行驗證。請按照前文所述，更新用戶端程式碼，改用驗證程式庫。詳情請參閱「服務帳戶金鑰」。

注意： 如未妥善管理服務帳戶金鑰，可能會產生安全性風險，請盡可能 選用比服務帳戶金鑰還要安全的替代方案。如果一定要使用服務帳戶金鑰進行驗證，您有責任保護私密金鑰的安全，並執行「 管理服務帳戶金鑰的最佳做法」一文所述的其他作業。假如無法建立服務帳戶金鑰，可能是因為貴組織已停用這項功能。詳情請參閱「 管理預設採用安全設定的組織資源」。

如果您是從外部來源取得服務帳戶金鑰，必須先驗證金鑰，才能使用。詳情請參閱「外部來源憑證的安全規定」一節。

您可以使用自行簽署的 JWT 取得 Google 簽署的 ID 權杖，但這個方法相當複雜，且可能容易出錯。基本步驟如下：

1. 自行簽署服務帳戶 JWT，並將 target_audience 宣告設為接收服務的網址或設定的自訂目標對象。如果不使用自訂網域，即使向特定流量標記提出要求，target_audience 值也應維持服務網址。

2. 將自行簽署的 JWT 換成 Google 簽署的 ID 權杖，其中 aud 宣告應設為上述網址。

3. 使用 Authorization: Bearer ID_TOKEN 標頭或 X-Serverless-Authorization: Bearer ID_TOKEN 標頭，在向服務提出的要求中加入 ID 權杖。如果同時提供這兩個標頭，系統只會檢查 X-Serverless-Authorization 標頭。

接收已驗證的要求

在接收私人服務中，您可以剖析授權標頭，接收不記名權杖傳送的資訊。

Python

from flask import Request

from google.auth.exceptions import GoogleAuthError
from google.auth.transport import requests
from google.oauth2 import id_token


def receive_request_and_parse_auth_header(request: Request) -> str:
    """Parse the authorization header, validate the Bearer token
    and decode the token to get its information.

    Args:
        request: Flask request object.

    Returns:
        One of the following:
        a) The email from the request's Authorization header.
        b) A welcome message for anonymous users.
        c) An error description.
    """
    auth_header = request.headers.get("Authorization")
    if auth_header:
        # Split the auth type and value from the header.
        auth_type, creds = auth_header.split(" ", 1)

        if auth_type.lower() == "bearer":
            # Find more information about `verify_token` function here:
            # https://google-auth.readthedocs.io/en/master/reference/google.oauth2.id_token.html#google.oauth2.id_token.verify_token
            try:
                decoded_token = id_token.verify_token(creds, requests.Request())
                return f"Hello, {decoded_token['email']}!\n"
            except GoogleAuthError as e:
                return f"Invalid token: {e}\n"
        else:
            return f"Unhandled header format ({auth_type}).\n"

    return "Hello, anonymous user.\n"

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.http.apache.v2.ApacheHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import java.util.Arrays;
import java.util.Collection;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestHeader;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
public class Authentication {
  @RestController
  class AuthenticationController {

    private final AuthenticationService authService = new AuthenticationService();

    @GetMapping("/")
    public ResponseEntity<String> getEmailFromAuthHeader(
        @RequestHeader(value = "Authorization", required = false) String authHeader) {
      String responseBody;
      if (authHeader == null) {
        responseBody = "Error verifying ID token: missing Authorization header";
        return new ResponseEntity<>(responseBody, HttpStatus.UNAUTHORIZED);
      }

      String email = authService.parseAuthHeader(authHeader);
      if (email == null) {
        responseBody = "Unauthorized request. Please supply a valid bearer token.";
        HttpHeaders headers = new HttpHeaders();
        headers.add("WWW-Authenticate", "Bearer");
        return new ResponseEntity<>(responseBody, headers, HttpStatus.UNAUTHORIZED);
      }

      responseBody = "Hello, " + email;
      return new ResponseEntity<>(responseBody, HttpStatus.OK);
    }
  }

  public class AuthenticationService {
    /*
     * Parse the authorization header, validate and decode the Bearer token.
     *
     * Args:
     *    authHeader: String of HTTP header with a Bearer token.
     *
     * Returns:
     *    A string containing the email from the token.
     *    null if the token is invalid or the email can't be retrieved.
     */
    public String parseAuthHeader(String authHeader) {
      // Split the auth type and value from the header.
      String[] authHeaderStrings = authHeader.split(" ");
      if (authHeaderStrings.length != 2) {
        System.out.println("Malformed Authorization header");
        return null;
      }
      String authType = authHeaderStrings[0];
      String tokenValue = authHeaderStrings[1];
      // Validate and decode the ID token in the header.
      if (!"bearer".equals(authType.toLowerCase())) {
        System.out.println("Unhandled header format: " + authType);
        return null;
      }

      // Get the service URL from the environment variable
      // set at the time of deployment.
      String serviceUrl = System.getenv("SERVICE_URL");
      // Define the expected audience as the Service Base URL.
      Collection<String> audience = Arrays.asList(serviceUrl);

      try {
        // Find more information about the verification process in:
        // https://developers.google.com/identity/sign-in/web/backend-auth#java
        // https://cloud.google.com/java/docs/reference/google-api-client/latest/com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier
        GoogleIdTokenVerifier verifier =
            new GoogleIdTokenVerifier.Builder(new ApacheHttpTransport(), new GsonFactory())
                .setAudience(audience)
                .build();
        GoogleIdToken googleIdToken = verifier.verify(tokenValue);

        // More info about the structure for the decoded ID Token here:
        // https://cloud.google.com/docs/authentication/token-types#id
        // https://cloud.google.com/java/docs/reference/google-api-client/latest/com.google.api.client.googleapis.auth.oauth2.GoogleIdToken
        // https://cloud.google.com/java/docs/reference/google-api-client/latest/com.google.api.client.googleapis.auth.oauth2.GoogleIdToken.Payload
        GoogleIdToken.Payload payload = googleIdToken.getPayload();
        if (!payload.getEmailVerified()) {
          System.out.println("Invalid token. Email wasn't verified.");
          return null;
        }
        System.out.println("Email verified: " + payload.getEmail());
        return payload.getEmail();

      } catch (Exception exception) {
        System.out.println("Ivalid token: " + exception);
      }
      return null;
    }
  }

  public static void main(String[] args) {
    SpringApplication.run(Authentication.class, args);
  }

後續步驟

• 進一步瞭解 ID 權杖驗證