主题
9.3 JoyInside H5端授权接入(前端)
概述
厂商通过跳转 JoyInside H5 授权页,引导用户完成京东账号登录授权,获取用户开放标识(openUid),建立厂商用户与 JoyInside 用户的映射关系。
与小程序半屏授权方式不同,H5 授权页适用于 App 内嵌 WebView、独立浏览器、或其他非微信小程序环境。
安全提示: Token 获取接口涉及
accessKeySecret,必须在服务端完成,不能暴露在客户端代码中。
接入流程
接入方式
通过 URL 跳转到 H5 授权页,所有参数通过 Query String 传递。
页面地址
| 环境 | 地址 |
|---|---|
| 正式环境 | https://tachat-h5.jd.com/JoyInside/authLoading |
示例
https://tachat-h5.jd.com/JoyInside/authLoading?token=eyJhbGciOi...&vendorId=100189&vendorUid=user_123&redirectUrl=https%3A%2F%2Fyour-app.com%2Fcallback代码示例
Web/H5:
js
const params = new URLSearchParams({
token: 'your_access_token', // 从服务端获取的 accessToken
vendorId: '100189', // 厂商ID(JoyInside 分配)
vendorUid: 'your_user_id', // 厂商侧用户唯一标识
redirectUrl: 'https://your-app.com/callback' // 授权完成后的回调地址
});
window.location.href = `https://tachat-h5.jd.com/JoyInside/authLoading?${params.toString()}`;App WebView:
kotlin
// Android
webView.loadUrl("https://tachat-h5.jd.com/JoyInside/authLoading?token=...&vendorId=...&vendorUid=...&redirectUrl=...")swift
// iOS
let url = URL(string: "https://tachat-h5.jd.com/JoyInside/authLoading?token=...&vendorId=...&vendorUid=...&redirectUrl=...")!
webView.load(URLRequest(url: url))入参(Query String)
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| token | String | 是 | JoyInside accessToken,由服务端调用 /auth/getToken 获取 |
| vendorId | String | 是 | 厂商在 JoyInside 的唯一标识,由平台分配 |
| vendorUid | String | 是 | 厂商侧用户唯一标识,最大长度 128 字符 |
| redirectUrl | String | 是 | 授权完成后的跳转地址,需 URL 编码。其域名必须提前报备给 JoyInside,详见 redirectUrl 域名报备 |
缺少任何必填参数,授权页会直接展示错误提示(缺少必要参数: xxx),停留在页面且不提供重试按钮。
redirectUrl 域名报备
授权页在建立绑定关系时,会从 redirectUrl 中提取 host(如 your-app.com)提交给服务端做白名单校验。校验不通过时返回错误码 40326,用户停留在授权页看到「回调地址不合法」,不会发生任何跳转。
这一层校验的目的是防止 redirectUrl 被伪造:若不加限制,攻击者只要把 redirectUrl 换成自己的域名,就能把用户的 openUid 引流出去。
因此接入前需把回调域名报备给 JoyInside(联系技术支持)。注意:
- 报备的是 host,不是完整 URL。
https://your-app.com/callback?id=1只需要报备your-app.com。 - host 包含端口号,带非默认端口的地址(如
https://your-app.com:8080/callback)需要报备your-app.com:8080。 - 若
redirectUrl不是合法 URL(被截断、缺少协议头、含非法字符等),授权页会提交空串,同样会被拒绝并返回 40326。这也是必须做 URL 编码的原因之一。
返回数据
授权完成后,页面跳转至 redirectUrl,结果参数附加在 URL 的 Query String 中。
授权成功
跳转地址示例:
https://your-app.com/callback?success=true&openUid=ou_a1b2c3d4e5f6| 参数 | 类型 | 说明 |
|---|---|---|
| success | String | "true" |
| openUid | String | 用户开放ID,用于后续设备绑定等操作 |
授权失败
跳转地址示例:
https://your-app.com/callback?success=false&code=40315&message=Token无效| 参数 | 类型 | 说明 |
|---|---|---|
| success | String | "false" |
| code | String | 错误码(参见错误码表) |
| message | String | 错误信息(中文描述) |
注意(错误处理分三类):
- 网络异常 / 服务端无业务错误码(登录校验阶段与绑定阶段均适用):停留在授权页展示错误信息,并提供「重试」按钮,不跳转。
- 回调域名未报备(错误码
40326):停留在授权页展示「回调地址不合法」,不跳转、不提供重试按钮(重试也不会通过,需要先完成域名报备)。- 其他业务错误码:直接跳转
redirectUrl,通过 Query String 返回success=false&code=xxx&message=xxx。
接收回调示例
js
// 在 redirectUrl 对应的页面中解析参数
const params = new URLSearchParams(window.location.search);
const success = params.get('success');
const openUid = params.get('openUid');
if (success === 'true') {
console.log('授权成功,openUid:', openUid);
// 将 openUid 发送到厂商服务端,用于设备绑定等操作
} else {
const code = params.get('code');
const message = params.get('message');
console.log('授权失败:', code, message);
}Token 获取(服务端)
此接口必须由厂商服务端调用。
接口信息
| 项目 | 说明 |
|---|---|
| 请求方式 | POST |
| 接口地址 | https://api.joyinside.com/auth/getToken |
请求参数
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| accessKeyId | String | 是 | 访问密钥ID |
| accessTimestamp | String | 是 | 13位毫秒时间戳 |
| accessNonce | String | 是 | 唯一随机串(UUID) |
| accessVersion | String | 是 | 固定值 V2 |
| accessSign | String | 是 | HMAC-MD5 签名 |
| vendorId | String | 是 | 厂商标识 |
签名算法
- 取以下四个参数,key 转小写后按字母顺序排列并拼接:
accesskeyid={值}&accessnonce={值}&accesstimestamp={值}&accessversion={值} - 使用
accessKeySecret作为密钥,对拼接字符串进行 HMAC-MD5 签名 - 签名结果为 32 位小写十六进制字符串
签名示例(Node.js)
js
const crypto = require('crypto')
const accessKeyId = '您的accessKeyId'
const accessKeySecret = '您的accessKeySecret'
const params = {
accessVersion: 'V2',
accessTimestamp: String(Date.now()),
accessNonce: crypto.randomUUID(),
accessKeyId: accessKeyId
}
// key 转小写 → 按字母排序 → 拼接
const signStr = Object.keys(params)
.map(k => [k.toLowerCase(), params[k]])
.sort((a, b) => a[0].localeCompare(b[0]))
.map(([k, v]) => `${k}=${v}`)
.join('&')
// HMAC-MD5 签名
const accessSign = crypto
.createHmac('md5', accessKeySecret)
.update(signStr)
.digest('hex')响应示例
json
{
"code": 0,
"msg": null,
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
"expireIn": 7200,
"refreshToken": "eyJhbGciOiJIUzI1NiJ9...",
"refreshExpireIn": 604800
}错误码
| 错误码 | 说明 | 处理建议 |
|---|---|---|
| 40310 | 签名验证失败 | 检查签名算法和密钥 |
| 40311 | 请求已过期 | 检查 timestamp 是否在 5 分钟有效期内 |
| 40312 | 重复请求 | 使用新的 nonce 重新请求 |
| 40313 | 参数校验失败 | 检查参数格式和必填项 |
| 40314 | 厂商未授权 | 联系运营开通权限 |
| 40315 | Token 无效 | 重新获取 Token |
| 40316 | Token 已过期 | 重新获取 Token |
| 40317 | Token 已撤销 | 重新获取 Token |
| 40318 | Token 格式错误 | 检查 Token 格式 |
| 40320 | 设备不存在 | 检查 deviceId 是否正确 |
| 40321 | 设备已绑定 | 引导用户先解绑设备 |
| 40322 | 用户标识不存在 | 检查 vendorUid 是否正确 |
| 40323 | 用户标识映射失败 | 请稍后重试或联系技术支持 |
| 40324 | 服务已过期 | 联系运营续费 |
| 40325 | 厂商不存在 | 检查 vendorId 是否正确 |
| 40326 | 回调地址不合法 | redirectUrl 的域名未报备,联系技术支持添加回调域名白名单 |
错误码在页面上的表现
| 错误类型 | 页面行为 |
|---|---|
40326 回调地址不合法 | 停留在授权页展示错误信息,不跳转,不提供重试按钮 |
| 其他业务错误码(40310–40325) | 跳转 redirectUrl,返回 success=false&code=xxx&message=xxx |
| 网络异常(无业务错误码) | 停留在授权页展示错误信息,提供重试按钮 |
接入准备
| 项目 | 说明 | 获取方式 |
|---|---|---|
| accessKeyId | 访问密钥ID | 联系技术支持 |
| accessKeySecret | 访问密钥密文(仅服务端使用) | 联系技术支持 |
| vendorId | 厂商唯一标识 | 联系技术支持 |
注意事项
accessKeySecret仅在服务端使用,泄露后请立即联系技术支持重新生成- Token 有效期 2 小时,建议服务端缓存并通过 refreshToken 续期(7 天有效)
- 签名中的 timestamp 有效期为前后 5 分钟,请确保服务器时间准确
- 同一 vendorId 下 vendorUid 必须唯一,建议直接使用厂商侧用户ID
redirectUrl必须进行 URL 编码(encodeURIComponent),否则参数可能被截断redirectUrl的域名(host)必须提前报备,否则授权页返回 40326「回调地址不合法」,用户停留在页面无法完成授权,详见 redirectUrl 域名报备- 授权页会自动处理登录态:未登录时跳转京东登录页,登录完成后自动回到授权流程
- 授权页需在支持 Cookie 的浏览器环境中使用(京东登录态依赖 Cookie)
更多信息
完整的服务端接入指南(含 Token 获取、签名算法、设备绑定等)请参阅 用户体系接入指南(后端)。