为确保开发者获取的 LinkedMall 资源安全可靠，所有接入 LinkedMall API的应用程序，在调用 API 时都必须先进行身份验证。

采用 OAuth 2.0 授权协议。

1. 卖家安装时，平台请求应用

在上述授权流程中，LinkedMall会重定向到应用的安装地址，即app_install_uri，重定向到该地址的时候，会额外携带以下参数：

请求示例：

https://awesomeapp.com/install?shop_id=2022927736662&client_id=382635552423&platform=linkedmall&timestamp=1646915676453&hmac=3766682300b57a855702e8729f91b9eb10d3fa662211415f4eac098730822e14e

2. 应用发起授权请求

请求授权接口动作由应用主动发起，具体来说就是拼接一个重定向地址，由浏览器发起重定向即可。

请求端点：https://linkedmall.store/openapi/oauth2/authorize

此请求包含的参数如下：

请求示例：

https://linkedmall.store/openapi/oauth2/authorize?client_id=9737261665284&response_type=code&scope=read_items%20read_orders&redirect_uri=https%3A%2F%2Fawesomeapp.com%2Foauth2%2Fcallback&state=rh8q7t7cge7637

3. 卖家确认授权，应用收到回调

在卖家确认授权之后，LinkedMall会回调应用，把授权码(code)信息带到应用这边，具体来说，LinkedMall会拼接一个重定向地址，由浏览器发起重定向，最终请求到应用这边。

请求参数如下：

请求示例：

https://awesomeapp.com/oauth2/callback?code=cn8a7t34t8t&shop_id=387266155522&timestamp=1646915676453&state=dh8q3287787c3&hmac=3766682300b57a855702e8729f91b9eb10d3fa662211415f4eac098730822e14e

4. 应用收到回调，进行验签

签名和验签相关内容参考下述 签名机制 小节。

5. 申请token

应用确认授权码回调准确无误之后，需要尽快申请token，因为授权码(code)的有效期只有几分钟。

请求端点：https://linkedmall.store/openapi/oauth2/token

请求参数如下：

请求示例：

curl -i -X POST https://linkedmall.store/openapi/oauth2/token \
  -H 'Content-Type:application/json' \
  -d '{"client_id": "9737261665284", "client_secret": "cno8份734xn3736c632", "grant_type": "authorization_code", "code": "cn8a7t34t8t"}'

返回参数如下：

返回示例：

{
  "access_token": "cn87g327CN7d73cj3hHx",
  "token_type": "bearer",
  "refresh_token": "xno87wh479tFxj8Hw22",
  "expires_in": 7200
}

6. 刷新token

颁发给应用的access_token有一个有效期，默认为2小时，应用自己需要确保：

• 在access_token过期之前，调用LinkedMall的刷新token接口，刷新access_token

请求端点：https://linkedmall.store/openapi/oauth2/token

请求参数如下：

请求示例：

curl -i -X POST https://linkedmall.store/openapi/oauth2/token \
  -H 'Content-Type:application/json' \
  -d '{"client_id": "9737261665284", "client_secret": "cno8份734xn3736c632", "grant_type": "refresh_token", "refresh_token": "xno87wh479tFxj8Hw22"}'

返回和上述申请token保持一致。

LinkedMall的签名步骤为：

• 把所有需要签名的参数，放入HashMap
• 把上述HashMap序列化为JSON格式字符串，根据key的字母表顺序排序
• 对上述字符串进行HMAC签名，得到hmac值

同样的，应用在验签的时候，重复上述步骤得到hmac值，与请求带过来的hmac值进行对比，如果不一致则说明请求非法。

Java加签示例

首先引入依赖：

<!-- https://mvnrepository.com/artifact/commons-codec/commons-codec -->
<dependency>
    <groupId>commons-codec</groupId>
    <artifactId>commons-codec</artifactId>
    <version>1.15</version>
</dependency>

使用Java实现上述签名过程的代码如下：

    private String hmac(String secret, String algo, Map<String, String> params) throws Exception {
        try {
            Mac mac = Mac.getInstance(algo);
            mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), algo));
            HmacUtils utils = new HmacUtils(algo, secret.getBytes(StandardCharsets.UTF_8));
            String json = OBJECT_MAPPER.writeValueAsString(params);
            return utils.hmacHex(json);
        } catch (NoSuchAlgorithmException | JsonProcessingException | InvalidKeyException e) {
            log.error("HMAC signing failed: {}", e.getMessage());
            throw new RuntimeException(e.getMessage());
        }
    }