Session Token

Shoplazza 后台中的嵌入式应用使用 OAuth 和 session token 进行身份验证。本指南适用于嵌入式应用的开发。

Session token 的工作原理

Session token 也称为 JSON web token（JWT），用于让您的应用对客户端与后端之间发出的请求进行身份验证。Session token 中还包含当前使用您的嵌入式应用的商家信息。

使用 session token 的身份验证流程

当您的嵌入式应用首次加载时，处于未认证状态，此时会向用户提供应用的前端代码。应用会向用户渲染一个界面骨架或加载画面。

前端代码加载完成后，应用会调用 Shoplazza App Bridge action 获取 session token。在向后端发起任何 HTTPS 请求时，应用会在授权请求头中携带该 session token。

使用 session token 的请求流程

Session token 使用您的应用与 Shoplazza 之间的共享密钥进行签名，以便您的后端验证请求是否有效。

Session token 的有效期

Session token 的有效期为一分钟。每次请求时必须通过 Shoplazza App Bridge 重新获取 session token，以确保不使用过期的 token。

Session token 的结构

Session token 由 header、payload 和签名三部分组成。如需交互式示例，可参考 JWT.io，在那里您可以尝试为各部分设置不同的值。Shoplazza 建议您在 JWT.io 上测试时使用测试应用的凭证。

Header
Header 中的值是固定的，不会更改。

{
  "alg": "HS256",
  "typ": "JWT"
}

alg：用于编码 JWT 的算法。
typ：session token 用于声明媒体类型的（type）header 参数。

Payload

{
  "iss": "<shop-name.myshoplaza.com/admin>",
  "dest": "<shop-name.myshoplaza.com>",
  "aud": "<app client id>",
  "sub": "<user ID>",
  "exp": "<time in seconds>",
  "nbf": "<time in seconds>",
  "iat": "<time in seconds>",
  "jti": "<random UUID>",
  "sid": "<session ID>",
  "locale": "zh-CN",
  "account":"[email protected]"
}

iss：商店的后台域名。
dest：商店的域名。
aud：接收方应用的 API key。
sub：session token 的目标用户。
exp：session token 过期的时间（秒）。
nbf：session token 生效的时间（秒）。
iat：session token 签发的时间（秒）。
jti：安全随机 UUID。
sid：每个用户和应用的唯一 session ID。
locale：商店的语言区域（语言和地区），例如 zh-CN 表示中文。
account：用户登录账号。

Payload 示例

{
  "locale": "zh-CN",
  "account": "[email protected]",
  "dest": "test.myshoplaza.com",
  "sid": "MTY0MDIyMzE5MHxRaHMzanN1OF9leGdWQTNYZmdqS2tvcnQ0UXpmVlhrZVlhZlJSSG1URTBnOUY4WFNVdl9BVWVmNHozbkVnYU5yc3NwRG9MZFptSGs9fPCmLb7qbttCuZl79rEcRKho9lRqTLZsvs_OESW0um8I",
  "aud": "825a8255676252ee1053073b2b42528c763fd011972ad2803036aea89882920c",
  "exp": 1640331670,
  "jti": "1cf4b3dd-6ccc-4978-9c5a-ad9cee17d4a7",
  "iat": 1640331610,
  "iss": "https://test.myshoplaza.com/admin",
  "nbf": 1640331610,
  "sub": "dafd283d-1274-4412-b86d-21a68ab1172f"
}

在后端验证 session token

后端在信任请求之前，必须对每个请求验证 session token。验证使用签发 token 时所用的同一个客户端密钥（CLIENT_SECRET）。

从 Authorization: Bearer <token> 请求头读取 token。
用 CLIENT_SECRET 以 HS256 算法验证签名和 exp 过期时间。
从已验证的 payload 中读取店铺和用户信息，而不是从请求参数中读取。

示例（Node.js，jsonwebtoken）：

const jwt = require("jsonwebtoken");

function verifySessionToken(req, res, next) {
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith("Bearer ")) {
    return res.status(401).json({ error: "Missing session token" });
  }

  const token = authHeader.replace("Bearer ", "");

  try {
    // jwt.verify 会校验签名和 exp 过期时间
    const decoded = jwt.verify(token, CLIENT_SECRET, { algorithms: ["HS256"] });
    req.session = {
      shop: decoded.dest, // 店铺域名——可信
      userId: decoded.sub, // 用户 ID
      locale: decoded.locale,
      account: decoded.account,
    };
    next();
  } catch (err) {
    return res.status(401).json({ error: "Invalid session token" });
  }
}

店铺应从已验证的 dest 字段解出，而不是从 shop URL 参数获取。URL 参数可被伪造，已验证的 token 不能。

使用该中间件的完整实战教程，见嵌入店铺后台。

Session token 的工作原理​

使用 session token 的身份验证流程​

使用 session token 的请求流程​

Session token 的有效期​

Session token 的结构​

在后端验证 session token​