整合應用程式的前端

本頁說明如何整合應用程式前端與 Cloud Marketplace，讓客戶從 Cloud Marketplace 前往您的產品時，享有流暢的使用體驗。

整體來說，您必須提供註冊網址來處理使用者帳戶的建立作業，然後在網路控制台中管理這些帳戶。此外，您也必須提供使用者登入的網址。您也可以選擇整合單一登入 (SSO)。

使用 Producer Portal 整合應用程式前端

如要從單一位置存取所有必要資訊，以便整合應用程式前端與 Cloud Marketplace，可以使用 Producer Portal 的「前端整合」部分。

Producer Portal 的直接連結如下：

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

如要存取「前端整合」部分，請按照下列步驟操作：

1. 在產品清單中，按一下產品的名稱。

2. 在產品的「總覽」頁面中，前往「技術整合」專區，然後按一下「前端整合」。

新增註冊網址

使用者從 Cloud Marketplace 購買您的產品時，您必須為他們建立產品帳戶。如要這麼做，您必須建立註冊頁面，在系統中設定及核准使用者帳戶。您可以將頁面設為註冊頁面，讓使用者在系統中註冊帳戶，也可以設為自動核准帳戶的頁面。

建立註冊頁面後，請在 Producer Portal 中新增：

1. 在產品清單中，按一下產品的名稱。

2. 在產品的「總覽」頁面中，前往「技術整合」專區，然後按一下「前端整合」。

3. 在「註冊網址」欄位中輸入註冊頁面的網址。

驗證使用者的註冊資訊

如果使用者尚未在您的系統中建立帳戶，必須點選 Cloud Marketplace 中的「使用 YOUR_COMPANY_NAME 註冊」按鈕。使用者點選按鈕後， Google Cloud 會傳送 HTTP POST 要求到您的註冊頁面，並在 x-gcp-marketplace-token 參數中傳送 JSON Web Token (JWT)。JWT 含有使用者的「採購帳戶 ID」，可用於識別他們的 Google Cloud 使用者身分，以及代表 Google 帳戶 ID 的「模糊處理 ID」。您必須同時使用採購帳戶 ID 和模糊處理 ID，將使用者的 Google 帳戶連結至他們在您系統中的帳戶。

驗證 JWT 後，註冊頁面必須將帳戶核准要求傳送至 Partner Procurement API，如後端整合步驟所述。

如要進一步瞭解 JWT 酬載和驗證方式，請參閱下方的「驗證 JWT」。

如果您是第一次使用 JWT，請參閱 JWT 簡介。

新增登入網址

您必須指定應用程式登入頁面的網址。

如要在 Producer Portal 中輸入應用程式登入頁面的網址，請按照下列步驟操作：

1. 在產品清單中，按一下產品的名稱。

2. 在產品的「總覽」頁面中，前往「技術整合」專區，然後按一下「前端整合」。

3. 在「登入網址」欄位中輸入應用程式登入頁面的網址。

(選用) 為客戶啟用單一登入 (SSO)

如要在 Producer Portal 中啟用單一登入：

1. 在產品清單中，按一下產品的名稱。

   1. 在產品的「總覽」頁面中，前往「技術整合」專區，然後按一下「前端整合」。

   2. 在「是否啟用單一登入 (SSO)？」下方，選取「是」。

驗證客戶的單一登入資訊

當顧客使用單一登入登入應用程式時， Google Cloud 會傳送 HTTP POST 要求到應用程式的登入頁面，並附上 JSON Web Token (JWT)，格式與使用者首次註冊應用程式時傳送的 JWT 相同。

如要進一步瞭解 JWT 酬載和驗證方式，請參閱下方的「驗證 JWT」。

驗證 JWT

部分程序 (例如註冊新客戶或使用單一登入服務登入客戶) 會傳送 HTTP POST 要求，其中包含您可能需要驗證的 JSON Web Token (JWT)。

下表列出：

• 涉及使用 JWT 傳送 HTTP 要求的事件。
• 涉及的 HTTP 要求類型。
• 是否必須驗證 JWT。

JWT 酬載

JWT 酬載的格式如下：

標題

{
  "alg": "RS256",
  "kid": "KEY_ID"
}

其中：

• alg 一律為 RS256。
• kid 表示用於保護 JWT 的金鑰 ID。請在酬載中利用這個金鑰 ID 從 iss 屬性內的 JSON 物件尋找金鑰。

酬載

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID
  }
}

其中：

• sub 是使用者的 Google 帳戶 ID。您必須利用這個 ID 將使用者的 Google 帳戶連結至他們在您系統中的帳戶。
• iss 用於識別 JWT 的寄件者。iss 聲明中的網址會連結至 Google 提供的公開金鑰。
• exp 表示憑證過期時間，會設為憑證傳送後的 5 分鐘。
• aud 是託管產品的網域，例如 example.com。

• roles 是代表使用者角色的字串陣列。可以是下列任一項：

  • account_admin，表示使用者是購買產品的帳單帳戶的帳單帳戶管理員 (訂單管理員)，或

  • project_editor，表示使用者是該帳單帳戶下專案的編輯者 (權利管理員)，但不是帳單管理員。

• user_identity 是使用者的模糊處理 GAIA ID，可用於啟動 OpenID Connect。

同一產品的多筆訂單的酬載

如果已啟用相同產品的多筆訂單，酬載會包含額外的 orders 物件。包括與每筆訂單的授權 ID 相對應的專屬訂單 ID。請確認應用程式的登入頁面可以回應這個新的 orders 欄位。

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com",
  "iat": CURRENT_TIME,
  "exp": CURRENT_TIME + 5 minutes,
  "aud": "PARTNER_DOMAIN_NAME",
  "sub": "PROCUREMENT_ACCOUNT_ID",
  "google": {
    "roles": [GCP_ROLE],
    "user_identity": USER_ID,
    "orders": [ORDER_ID1, ORDER_ID2]
  }
}

其中：

• ORDER_ID 是每個授權 ID 的專屬訂單 ID 清單，表示同一產品的不同方案。只有在啟用相同產品的多筆訂單時，這個欄位才會顯示。

如要進一步瞭解如何開啟相同產品的多筆訂單，請參閱「開啟相同產品的多筆訂單」。

驗證酬載

收到 JWT 時，您必須驗證下列事項：

1. 驗證 JWT 簽名是使用 Google 提供的公開金鑰。

2. 透過檢查 exp 要求，驗證 JWT 尚未過期。

3. 確認 aud 要求是產品的正確網域。

4. 確認 iss 聲明為 https://www.googleapis.com/robot/v1/metadata/x509/cloud-commerce-partner@system.gserviceaccount.com。

5. 確認 sub 並非空白。

使用 login_hint 啟動 Google 登入程序

如要讓使用者透過 OAuth 2.0 同意流程存取您的網站，可以使用酬載中的身分識別資訊，在重新導向前，透過使用者用於 Google Cloud 的 Google 帳戶初始化該流程。如要這麼做，請將 JWT 中提供的 user_identity 做為 login_hint。詳情請參閱 Google OAuth 2.0 說明文件。

使用者在網站上完成 OAuth 2.0 流程後，您應確認完成 OAuth 流程的使用者是否為預期對象。方法是使用 OAuth 2.0 存取權杖呼叫 Google UserInfo API，擷取使用者的基本資訊。這會傳回預期與 JWT 中的 user_identity 欄位相符的 ID。

為客戶建立服務帳戶

如果產品需要服務帳戶，您可以與合作夥伴工程師合作，完成下列事項：

• 為客戶佈建服務帳戶，以及
• 為客戶設定服務帳戶管理頁面，讓他們將必要的 Identity and Access Management (IAM) 角色授予服務帳戶。

您必須向客戶提供這個服務帳戶頁面的連結，通常是透過產品的管理控制台。

佈建服務帳戶

如要佈建服務帳戶，請與合作夥伴工程師聯絡，並提供下列資訊：

• 服務名稱：這是專屬產品 ID，可將你的產品與其他產品區分開來。建議使用產品上線時建立的服務名稱。

• 專案 ID：您在其中建立服務帳戶的專案 ID，這些服務帳戶會存取客戶的資源。您必須在單一專案中，建立產品使用的所有服務帳戶。

• 身分與存取權管理角色和理由：服務帳戶所需的 IAM 角色，以及這些角色為何必要。這項資訊會與客戶共用，並可能影響客戶是否授予服務帳戶存取權。

如要讓客戶在授予服務帳戶存取權後返回您的網站，請將管理控制台的網域名稱傳送給合作夥伴工程師。您可以傳送多個網域名稱，包括子網域，例如 staging.example.com。

將服務帳戶管理頁面整合至產品的控制台

合作夥伴工程師會建立服務帳戶管理頁面，讓客戶授予服務帳戶存取權。然後從控制台連結至該頁面。

合作夥伴工程師通知您服務帳戶管理頁面已準備就緒後，請在網址中新增參數，然後從控制台連結至該頁面。

您必須在網址中加入兩個參數：

• service-name：這是您提供給合作夥伴工程師的服務名稱。

• service-account-email：這是您為客戶建立的服務帳戶電子郵件地址。每位客戶都有專屬的服務帳戶。

以下範例顯示含有必要參數的網址：

https://console.cloud.google.com/marketplace-saas/service-account/service-name/service-account-email

您可以視顧客需求新增其他參數。例如：

https://console.google.com/marketplace-saas/service-account/service-name/service-account-email;single=true;redirect=https%3A%2F%2Fexample.com

網址的參數表示產品需要存取單一Google Cloud 專案，且顧客可以返回控制台。

網址參數清單

以下列出可傳送至服務帳戶管理頁面的網址參數：