集成应用的前端

本页面介绍了如何将应用的前端与 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

注意： 如果您没有看到该链接或无法访问该网址，请确认您已选择正确的项目。如果您仍然无法访问该网址，请通过 Partner Support Desk 寻求帮助，并在说明中添加“Marketplace”一词。如需详细了解 Partner Support Desk，请参阅请求有关 Cloud Marketplace 的帮助。

要访问前端集成部分，请执行以下操作：

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

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

添加您的注册网址

当用户从 Cloud Marketplace 购买您的产品时，您必须为他们创建一个产品帐号。为此，您必须创建一个注册页面，以便在您的系统中设置和批准用户的帐号。您可以将页面设置为注册页面（用户可以在该页面上注册您系统中的帐号），也可以设置为自动批准帐号的页面。

注意 ：设置注册页面时，请确保用户无需先输入用户名和密码即可访问页面。

创建注册页面后，将其添加到 Producer Portal 中：

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

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

3. 在注册网址字段中输入注册页面的网址。

验证用户的注册信息

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

注意 ：单个用户可能具有多个采购帐号 ID，也可能多个用户共享一个通用的采购帐号 ID，具体取决于用户或其组织配置 Google Cloud 使用情况的方式。

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

如需详细了解 JWT 载荷以及如何验证，请参阅下面的验证 JWT。

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

添加您的登录网址

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

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

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

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

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

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

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

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

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

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

验证客户的单点登录登录信息

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

如需详细了解 JWT 载荷以及如何验证，请参阅下面的验证 JWT。

验证 JWT

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

下表列出了：

• 涉及通过 JWT 发送 HTTP 请求的事件。
• 所涉及的 HTTP 请求的类型。
• 您是否必须验证 JWT。

事件	HTTP 请求类型	需要进行 JWT 验证
注册新客户	POST	是
客户登录（不使用单点登录）	GET	否
客户登录（使用单点登录）	POST	是

JWT 载荷

JWT 有效负载格式如下：

标头

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

其中：

• alg 始终为 RS256。
• kid 表示用于保护 JWT 的密钥 ID。使用密钥 ID 从载荷的 iss 属性中的 JSON 对象查找密钥。

载荷

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/[e-mail]",
  "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，表示用户是该结算帐号下的项目的编辑者 (Entitlement Manager)，而不是结算管理员。

  注意 ：如果您已启用单点登录 (SSO)，则具有 account_admin 角色的用户还必须具有 project_editor 角色。

• user_identity 是用户的经过混淆处理的 GAIA ID，可用于启动 OpenID Connect。

同一产品的多个订单的载荷

预览 — Multiple orders of the same product

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

如果您启用了同一产品的多个订单，则载荷会包含一个额外的 orders 对象。这包括与每个订单的许可 ID 对应的唯一订单 ID。确保应用的登录页面可以响应这个新的 orders 字段。

{
  "iss": "https://www.googleapis.com/robot/v1/metadata/x509/[e-mail]",
  "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/[e-mail]

5. 确认 sub 不为空。

注意 ：由于我们可能会向 JWT 添加新字段，因此您不应仅仅因为 JWT 包含您尚未遇到的新字段就认为 JWT 无效。

使用 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 项目，并且客户可以返回您的控制台。

网址参数列表

以下是您可以发送到服务帐号管理页面的网址参数列表：

参数	说明
service-name	这是必填项。 这是您提供给合作伙伴工程师的服务名称。
service-account-email	这是必填项。 这是您为客户创建的服务账号的电子邮件地址。
single	如果为 true，则表示您的产品需要访问单个项目。
hints=project-id-1	设置您希望服务账号访问的项目。使用英文逗号分隔项目。
filter=role1	将授予服务账号的角色限制为提供给合作伙伴工程师的一部分角色。使用过滤条件时排除 roles/。
redirect	为客户提供用于返回到管理控制台的链接。您必须向合作伙伴工程师注册域名才能使用此参数。