什么是 Bearer 令牌？API 访问与机密处理

Scrapeless Web Unlocker 使用 Scrapeless API key 通过其文档化的请求认证方法进行工作，这与目标服务的 bearer 凭证是分离的。

Bearer 令牌是一种基于持有的凭证

bearer 令牌是一种凭证，持有该令牌的一方可以通过出示令牌本身来使用它，而无需单独证明对绑定到该令牌的加密密钥的持有。 OAuth bearer token usage standard 为通过 HTTP 访问受保护资源定义了这一特性。因此“持有”本身非常敏感：获得有效令牌的人可能能够行使该令牌所赋予的访问权限。

bearer 一词并不意味着无限制访问。资源服务器仍然要判断令牌对所请求资源是否有效、是否已过期或被撤销，以及该操作是否被允许。一个令牌可以被限制在很窄的作用域和预期受众内。保护机密和执行这些约束是互补的控制措施，而不是可以互相替代的选项。

一个常见的用法是：API 请求在 Authorization 字段中使用 Bearer 方案，后跟访问凭证。请遵循资源服务关于放置和验证的精确约定。一个被某服务接受的令牌，不应被假定在另一个服务中同样有效，即使它们属于同一个组织或者都暴露出类似的 HTTP 端点。

Bearer、OAuth 与 JWT 描述的是不同层次

Bearer 描述凭证如何被使用，OAuth 描述授权框架，而 JWT 描述结构化令牌格式。这些概念经常一起出现，但并不是同义词。OAuth 可以签发被作为 bearer 凭证呈现的访问令牌，而这些令牌可以是不透明字符串或结构化值。客户端不应仅因为访问令牌来自 OAuth 就推断其格式。

JWT 以定义好的表示方式承载声明，其安全属性由所选 JOSE 机制和验证规则决定。 JSON Web Token specification 并不会让每个 JWT 都成为 OAuth 访问令牌。身份断言、短期应用断言和访问凭证即使编码看起来相似，也可能需要不同的验证方式。

对令牌进行解码并不等同于验证它。可读的声明并不能证明签发方是可信的、完整性保护是正确的，或者资源服务器是预期受众。绝不要仅因为令牌负载可以解析为 JSON 就接受它。令牌验证必须遵循具体的应用配置文件和授权服务器约定。

签发与资源访问是分离的步骤

令牌签发发生在授权系统的策略之下，而资源访问发生在服务评估携带令牌的请求时。 OAuth token issuance framework 定义了获取访问凭证的角色和授权方式。提供方也可以为其自有凭证使用单独文档化的签发机制。资源服务器的接受策略必须与产生该凭证的机制相匹配。

访问令牌应只被发送到其预期的资源服务。刷新令牌属于授权服务器的 token 接口，不应发送到普通业务端点。客户端密钥仅用于受支持场景下对客户端进行认证，不能替代用户的资源访问令牌。将这些值区分开，可以防止调试会话演变成跨服务凭证泄露。

权限决策还可能依赖于令牌所代表的用户或租户。对于超出该作用域的对象，即使凭证本身仍然有效，请求也必须被拒绝。对象级授权属于服务器端逻辑。客户端能够构造 URL 或猜测对象标识符，并不能证明调用方可以读取该对象。

验证预期的签发方、资源和权限

资源服务器需要确认凭证对该请求是否处于激活状态并且相关。对于结构化访问令牌，这可能涉及检查完整性保护、受信任签发方、预期受众、有效时间以及授权声明。对于不透明令牌，服务器可以使用自身的查找机制或受支持的验证接口。使用提供方的配置文件，而不是把一个不完整的通用检查清单拼成自定义验证器。

该 OAuth 令牌内省机制 定义了受保护资源服务查询令牌信息的方法，包括它是否处于激活状态。内省是一种经过授权的服务器交互，而不是邀请任意客户端把机密粘贴到公共令牌解码网站。让验证流量保持在受信任的授权架构之内。

一个激活的令牌仍然可能不具备执行特定操作所需的权限。在代码和诊断中区分令牌有效性与资源授权。经过脱敏的日志可以记录签发方标识符、路由、状态以及请求关联值，而不保留凭证本身。这样既为运维人员提供有用线索，又避免日志阅读者继承受保护 API 的访问权限。

在凭证整个生命周期中保护它们

持有者凭证在传输、存储、使用和销毁阶段都需要保护。只通过预期的安全连接发送它们，并避免将其放入 URL，除非服务明确要求受保护的连接参数。URL 可能出现在浏览器历史记录、代理日志、分析数据以及共享截图中。凭证生命周期很短这一点，并不能让疏忽泄露变得无害。

不要把机密放入源代码仓库、示例文件和普通应用遥测中。部署时的机密存储可以将凭证注入到需要它的进程中。限制可以读取该值的人员和组件，并在记录请求诊断前对其进行遮蔽。环境变量是一种传递机制，本身不是完整的访问控制或保留策略。

客户端应用需要明确的威胁模型，因为浏览器代码不可能对其用户或在该环境中运行的脚本永久保守机密。某些架构中，服务器组件可以降低令牌的直接暴露，但它也会引入自身的会话与请求保护需求。根据应用的安全设计来选择存储和会话模式，而不是把某一种存储位置视为天然安全。

不要猜测地解读被拒绝的凭证

已认证请求被拒绝时，应根据端点文档化的状态与错误字段来解读。缺失或无效的凭证，与凭证被接受但权限范围不足并不相同。保持这些差异体现在结果状态中，避免应用把权限拒绝展示成空集合。在决定需要关注哪一个凭证之前，先检查是哪一个服务产生了该响应。

不要把有效令牌粘贴进支持工单来证明它存在。共享经过脱敏的请求细节，并在调查需要访问账户时使用提供方的安全支持流程。如果凭证暴露，其所有者应遵循签发方的吊销或更换流程，并检查该值被存储在何处。删除某个本地副本并不会移除日志或共享产物中保留的副本。

在威胁模型中，仅基于持有的访问方式不足以应对风险时，发送方约束机制可以增加证明要求。 OAuth DPoP 将受支持令牌的使用绑定到加密密钥和请求证明上。它是一个独立的受支持机制，而不是附加在普通持有者请求上的任意额外请求头。客户端和服务端都必须实现相应的约定。

Scrapeless 密钥与目标令牌必须保持分离

该 Scrapeless API key requirements 为每个产品指定了认证方法。Web Unlocker REST 请求在文档所述的 x-api-token 字段中直接使用原始密钥，而不是臆测使用 Bearer 方案。通过浏览器连接参数传递的密钥同样是机密，当连接 URL 被记录或共享时需要进行遮蔽。

该 API authentication concepts 有助于区分这些方案，而 Scrapeless pricing 关心的是服务用量。有效的账户凭证、已启用的产品、充足的余额以及访问目标资源的权限是彼此独立的条件。分别对它们进行诊断，而不是把每一次失败都当成格式错误的 bearer 字符串。

为工作流构建凭证清单

凭证清单应标明每个机密的签发方、预期接收方、允许的操作、存储位置和所有者。在提供方有定义的情况下，包含到期或吊销行为。避免把原始值复制进清单；使用标识符和机密存储引用来描述。目标是在不创建另一个敏感数据存储的前提下，让权限边界变得清晰可见。

对于一个假设的报表工具来说，一份凭证可能授权该工具自身的数据服务账户，而另一份则代表用户批准的资源授权。这些值需要不同的受众和销毁规则。测试应确认错误的凭证会被拒绝，并且日志始终保持脱敏。清晰的清单有助于在将更多提供方加入工作流时更容易保持这种区分。

结论

不记名令牌之所以强大，是因为只要持有就足以出示其访问权限。请将签发方、预期接收方、权限范围和存储边界明确化，并使用服务的实际令牌约定来验证凭证。将目标访问令牌与平台 API 密钥分开，使一个集成不会暴露原本为另一个集成准备的权限。