要创建测试环境,请在KWS中创建 产品,然后将家长验证服务链接到该产品,如下所示。
设置你的产品
在KWS开发者门户的 操作面板(Dashboard) 选项卡中,点击右上角的 添加产品(Add product) 按钮:
[(w:700)](add_product_highlighted.png)输入 产品名称(Product name),然后点击 添加产品(Add product):
[(w:700)](add_product_prodname.png)该产品现在存在于你的测试环境中。系统将提示你填写产品详细信息。
输入以下 基本信息(Basic information) 并同意服务条款:
[(w:700)](product_submit_highlighted.png)产品名称(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:
在 家长验证服务(Parent Verification Service) 视图中,输入 成功验证的webhook地址。这是KWS发送确认成功验证的webhook的地方。
重要提示:请勿在webhook URL中添加任何可能被网络攻击者利用的敏感信息(例如,可被轻易迭代的数字ID)。签名算法中故意未添加URL,以便在请求URL可能被修改时,在逆向代理服务器/负载平衡器等背后的服务中更容易进行签名验证。
复制以下数值,以便在你的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库实现的不一致产生的签名不匹配。
删除产品
如需从你的组织中删除一款 产品:
在KWS开发者门户的 仪表板 中,找到所需的产品。
点击 删除。
当某个 产品 被删除时:
开发者门户中应用于该产品的所有品牌都会被删除。
所有与该产品相关的服务都会被禁用。