集成应用的前端

本页面介绍了如何将应用的前端与 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. 在 Sign up 网址（注册网址）字段中输入注册页面的网址。

验证用户的注册信息

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

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

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

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

如果您刚开始使用 JWT，请参阅 JWT 简介。

添加登录网址

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

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

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

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

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

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

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

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

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

   2. 在 Enable SSO login?（启用单点登录吗？）下方，选择 Yes（是）。

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

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

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

验证 JWT

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

下表列出了：

• 涉及使用 JWT 发送 HTTP 请求的事件。
• 涉及的 HTTP 请求的类型。
• 是否必须验证 JWT。

事件	HTTP 请求类型	需要进行 JWT 验证
注册新客户	POST	是
客户登录（不使用单点登录）	GET	否
使用 SSO 登录客户	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，表示用户是该结算帐号下项目的 Editor (Entitlement Manager)，而不是 Billing Administrator。

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

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

验证载荷

收到 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 包含您尚未遇到的新字段就将它视为无效。

使用 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 以获取基本用户信息。这将返回一个 ID，它应与 JWT 中的 user_identity 字段匹配。

为您的客户创建服务账号

预览

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

如果您的产品需要服务帐号，您可以与合作伙伴工程师合作，执行以下操作：

• 为您的客户预配服务帐号，以及
• 为您的客户设置一个服务帐号管理页面，以便向服务帐号授予所需的 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	为客户提供用于返回到管理控制台的链接。您必须向合作伙伴工程师注册域名才能使用此参数。