3. 承运商API认证机制

在承运商集成场景中，API认证是保障数据传输安全的第一道防线。不同的承运商平台可能采用不同的认证机制，理解其原理、适用场景及安全传递方式，是成功调试与集成的关键前提。本章将系统对比三种主流认证方式，并给出请求头中安全传递凭证的最佳实践。

3.1 三种认证机制核心对比

3.2 认证机制

是最简单的认证方式，承运商平台为每个集成方分配一个唯一密钥。请求时需将密钥放入自定义请求头或查询参数中。

3.2.1 请求示例

GET /api/v1/shipments HTTP/1.1
Host: api.carrier.com
X-: c7f3a2b1d8e9f0a4b5c6d7e8f9a0b1c2
Content-Type: application/json

3.2.2 安全风险与规避

• 避免在URL中传递： 如 ?=xxx 会被日志、浏览器历史记录泄露。
• 使用自定义请求头： 推荐使用 X- 或 X- 头，避免被代理服务器误解析。
• 定期轮换： 设置密钥有效期（如90天），通过平台管理界面手动更新。
• 限制IP白名单： 配合服务端IP白名单降低泄露风险。

3.3 Bearer 认证机制

Bearer 是一种基于令牌的认证方式，客户端先通过身份验证获取一个临时令牌，后续请求在 Authorization 头中携带该令牌。令牌通常采用 JWT（JSON Web ）格式，包含用户身份、权限范围和过期时间。

3.3.1 获取令牌流程

1. 客户端向认证端点发送凭证（如用户名+密码或客户端ID+密钥）。
2. 认证服务器验证通过后，返回一个 access_（Bearer ）。
3. 客户端将令牌存储在内存或安全存储中，用于后续API调用。

3.3.2 请求示例

POST /api/v1/auth/ HTTP/1.1
Host: auth.carrier.com
Content-Type: application/json

{
  "username": "integration_user",
  "password": "s3cur3P@ss",
  "grant_type": "password"
}

// 响应
{
  "access_": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "_type": "Bearer",
  "expires_in": 3600
}

GET /api/v1/shipments HTTP/1.1
Host: api.carrier.com
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
Content-Type: application/json

3.4 OAuth 2.0 授权码流程

OAuth 2.0 是承运商开放平台最推荐的认证框架，尤其适合第三方应用代表用户访问资源。其核心是授权码（Authorization Code）流程，支持前端通道与后端通道分离，安全性最高。

3.4.1 授权码流程步骤详解

1. 客户端请求授权码： 用户浏览器或客户端重定向到承运商授权页面，附带 client_id、redirect_uri、scope 和 response_type=code。
2. 用户授权： 用户在承运商页面登录并确认授权范围。
3. 返回授权码： 承运商将授权码通过重定向发送到客户端的 redirect_uri。
4. 换取令牌： 客户端使用授权码 + client_secret 向令牌端点请求 access_ 和 refresh_。
5. 调用API： 客户端在请求头中携带 Authorization: Bearer <access_> 调用承运商资源API。

3.5 请求头中安全传递凭证的最佳实践

无论采用哪种认证机制，凭证在HTTP请求头中的传递方式直接影响安全性。以下是承运商集成中必须遵守的规范：

3.6 三种机制的选择决策树