集成应用的前端

本页介绍了如何将应用的前端与 Cloud Marketplace 集成，以便客户在从 Cloud Marketplace 转到您的产品时获得流畅的体验。

概括来讲，您必须提供注册网址来处理创建用户账号的操作，然后在 Web 控制台中管理这些账号。您还必须提供一个供用户登录的网址。（可选）您可以集成单点登录 (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. 在 Sign up 网址（注册网址）字段中输入注册页面的网址。

验证用户的注册信息

如果用户尚未在您的系统中建立账号，则必须点击 Cloud Marketplace 中的 Register with YOUR_COMPANY_NAME 按钮。用户点击该按钮后，Google Cloud 会向您的注册页面发送一个 HTTP POST 请求，并在 x-gcp-marketplace-token 参数中发送一个 JSON Web 令牌 (JWT)。JWT 包含用户的采购账号 ID（用于将该用户标识为 Google Cloud 用户）和经过混淆处理的 ID（表示其 Google 账号 ID）。您必须同时使用采购账号 ID 和经过混淆处理的 ID 将用户的 Google 账号与用户在您系统中的账号相关联。

验证 JWT 后，您的注册页面必须向 Partner Procurement API 发送账号批准请求，如后端集成步骤中所述。

如需详细了解 JWT 载荷及其验证方法，请参阅下文中的验证 JWT。

如果您不熟悉 JWT，请参阅 JWT 简介。

添加登录网址

您必须指定应用的登录页面的网址。

如需在 Producer Portal 中输入应用登录页面的网址，请执行以下操作：

1. 在产品列表中，点击您的产品的名称。

2. 在您产品的概览页面上，前往技术集成部分，然后点击前端集成。

3. 在 Login 网址（登录网址）字段中输入应用的登录页面的网址。

（可选）为您的客户启用单点登录 (SSO)

如需在 Producer Portal 中启用单点登录，请执行以下操作：

1. 在产品列表中，点击您的产品的名称。

   1. 在您产品的概览页面上，转到技术集成部分，然后点击前端集成。

   2. 在要启用单点登录吗？下，选择是。

验证客户的 SSO 登录信息

当客户使用 SSO 登录您的应用时，Google Cloud 会向应用的登录页面发送 HTTP POST 请求，其中包含格式与用户首次注册应用时发送的 JWT 相同的 JSON Web 令牌 (JWT)。

如需详细了解 JWT 载荷及其验证方法，请参阅下文中的验证 JWT。

验证 JWT

某些流程（例如注册新客户或使用 SSO 登录客户）会向您发送包含 JSON Web 令牌 (JWT) 的 HTTP POST 请求，您可能需要对该令牌进行验证。

下表列出了：

• 涉及发送包含 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，表示用户是购买产品的结算账号的 Billing Account Administrator（Order Administrator），或者

  • project_editor，表示用户是该结算账号下的项目的 Editor（使用权管理员），但不是 Billing Administrator。

• 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 角色和原因：服务账号所需的 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 项目，并且客户可以返回您的控制台。

网址参数列表

下面列出了您可以发送到服务账号管理页面的网址参数：