创建测试环境

介绍如何在测试环境中为你的产品创建家长验证服务

要创建测试环境,请在KWS中创建 产品,然后将家长验证服务链接到该产品,如下所示。

设置你的产品

  1. 在KWS开发者门户的 操作面板(Dashboard) 选项卡中,点击右上角的 添加产品(Add product) 按钮:

  2. 输入 产品名称(Product name),然后点击 添加产品(Add product)

    该产品现在存在于你的测试环境中。系统将提示你填写产品详细信息。

  3. 输入以下 基本信息(Basic information) 并同意服务条款:

    • 产品名称(Product name)

    • 产品URL(Product URLs) - 根据验证要求,KWS在发送给家长请求验证的电子邮件中将提供这些URL的链接:

      • 隐私政策 - 你的组织的隐私政策。

      • 客户支持/常见问题 - 你的组织的客户支持/常见问题链接。

设置服务

接受服务条款后,服务的细节信息才会变成可编辑状态。这些信息由重定向URL和webhook设置组成:

创建重定向URL

输入 重定向URL。这是KWS会在验证成功或最终失败后将家长重定向到的URL。其格式如下:

https://your.domain.com/your/path?status=...&externalPayload=...

其中:

  • externalPayload 是传递给initiate的可选externalPayload。

  • status 是一个采用了URL编码方式的JSON对象,表示验证返回的状态:

verified: boolean,
transactionId: string,
errorCode: string | null,

注意:重定向URL中的信息没有签名,用户可能会修改。该信息只能用于演示目的,不能用于确定验证结果。你应该使用webhook来确定结果。

如果未配置URL,KWS将在其控件中显示成功/失败页面。

设置webhook

KWS会通过webhook调用通知你的系统事件。请按照以下步骤设置webhook:

  1. 家长验证服务(Parent Verification Service) 视图中,输入 成功验证的webhook地址。这是KWS发送确认成功验证的webhook的地方。

    重要提示:请勿在webhook URL中添加任何可能被网络攻击者利用的敏感信息(例如,可被轻易迭代的数字ID)。签名算法中故意未添加URL,以便在请求URL可能被修改时,在逆向代理服务器/负载平衡器等背后的服务中更容易进行签名验证。

  2. 复制以下数值,以便在你的webhook配置中使用:

    • Webhook密码 - 这是Webhook密钥,用于对负载进行签名,确保它是来自KWS的真实调用。

    • 服务API主机URL

    • 服务控件URL

POST正文结构

所有webhook调用都是HTTPS POST,并且采用了通用的结构,以便封装特定于事件的负载:

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Body
{
  "name": "webhook-name",
  "time": "ISO8601 timestamp",
  "orgId": "uuid",
  "productId": "uuid" | null,     // Future webhooks may apply at org level
  "environmentId": "uuid" | null,
  "payload": { ... type-specific payload ... }
}

签名

签名是十六进制格式(小写)的HMAC_SHA256哈希,其中密钥是你在Webhook设置中提供的 Webhook密码

签名使用 x-kws-signature 标头,通过以下格式发送:

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

当前仅包含一个v1签名,但在以下情况下,标头可能包含多个签名:

  • 支持签名密钥轮换(将在过渡期内为之前和当前密钥发送签名)。

  • 签名算法变更(在过渡期内,v2签名将与v1签名一起发送)。

生成v1签名的算法是签名标头中包含的时间戳的HMAC_SHA256,后跟一个句点("."),之后是原始请求正文。HMAC应该使用webhook的密钥进行初始化。

例如:

const timestamp = /* 取自标头的 ‘t=' 的提取值 */;
const body = /* 原始请求正文,UTF-8 字符串 */;
const secretKey = /* 在开发者门户中输入的密钥 */;
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(`${timestamp}.${body}`)
  .digest('hex');

注意:使用原始POST正文非常重要。不要试图解析和重新字符串化JSON,因为这可能会导致JSON库实现的不一致产生的签名不匹配。

删除产品

如需从你的组织中删除一款 产品

  1. 在KWS开发者门户的 仪表板 中,找到所需的产品。

  2. 点击 删除

当某个 产品 被删除时:

  • 开发者门户中应用于该产品的所有品牌都会被删除。

  • 所有与该产品相关的服务都会被禁用。