Quarkus中实现OAuth 1.0a对接Twitter API v1.1的入门方案咨询

核心前提先理清 #

• Twitter API v1.1 仅支持 OAuth 1.0a 鉴权，和 Quarkus 内置 OIDC 适配的 OAuth2/OIDC 协议族逻辑完全不兼容，不需要强行改造现有 OIDC 配置，单独实现一套请求签名逻辑即可，不会和项目现有鉴权体系冲突。
• OAuth 1.0a 和 OAuth2 Bearer Token 逻辑差异极大：不存在长效令牌一次校验全程通行的逻辑，每一次发往 Twitter v1.1 的请求都需要单独生成签名，放到请求头中携带，别拿 OIDC 的实现思路硬套。

具体实现步骤 #

1. 提前准备好核心凭证 #

先从 Twitter 开发者后台拿到 v1.1 应用的4个必填参数，后续所有签名都依赖这四个值：

• Consumer Key（也叫API Key）
• Consumer Secret（也叫API Key Secret）
• Access Token
• Access Token Secret

2. 引入成熟依赖，别手搓签名算法 #

OAuth 1.0a 的签名、编码规则细节非常多，自己从零写很容易踩坑，直接用成熟的第三方客户端库效率最高。Quarkus 项目优先选和 JAX-RS/REST Client 兼容性好的库，比如 ScribeJava，只需要引单个依赖，不需要额外带一堆冗余组件：

<!-- Maven 依赖 -->
<dependency>
    <groupId>com.github.scribejava</groupId>
    <artifactId>scribejava-apis</artifactId>
    <version>选当前公开稳定版即可</version>
</dependency>

如果不想额外引入第三方库，也可以直接抽离 Twitter 官方开源的 v1.1 SDK 里的签名工具类，逻辑是通用的。

3. 对接 Quarkus REST Client 实现无感知签名 #

不要在每个业务调用点单独写签名逻辑，直接实现一个 Quarkus REST Client 的全局请求过滤器，所有打向 Twitter v1.1 域名的请求自动完成签名拼接，业务层调用时和普通内部接口没有区别。
核心过滤器代码参考：

@Provider
@TwitterApi // 自定义绑定注解，只给Twitter对应的REST Client加这个过滤器
public class TwitterOAuth1RequestFilter implements ClientRequestFilter {
    // 从配置文件注入四个密钥，绝对不要硬编码在代码里
    @ConfigProperty(name = "twitter.v1.consumer-key")
    String consumerKey;
    @ConfigProperty(name = "twitter.v1.consumer-secret")
    String consumerSecret;
    @ConfigProperty(name = "twitter.v1.access-token")
    String accessToken;
    @ConfigProperty(name = "twitter.v1.access-token-secret")
    String accessTokenSecret;

    @Override
    public void filter(ClientRequestContext requestContext) throws IOException {
        // 初始化签名工具，固定用HMAC-SHA1算法，是Twitter v1.1要求的签名算法
        OAuth10aService service = new ServiceBuilder(consumerKey)
                .apiSecret(consumerSecret)
                .accessToken(accessToken)
                .tokenSecret(accessTokenSecret)
                .build(TwitterApi.instance());
        OAuthRequest oauthRequest = new OAuthRequest(
                Verb.valueOf(requestContext.getMethod()),
                requestContext.getUri().toString()
        );
        // 把query参数加入签名参数集合，注意JSON请求体的字段不需要参与签名
        requestContext.getUri().getQueryParams().forEach((k, v) -> oauthRequest.addQuerystringParameter(k, v.get(0)));
        service.signRequest((OAuth1AccessToken) service.getAccessToken(), oauthRequest);
        // 把生成好的Authorization头塞回请求
        requestContext.getHeaders().add("Authorization", oauthRequest.getHeaders().get("Authorization"));
    }
}

必踩坑点提前避 #

• 签名的参数编码必须严格遵循 RFC3986 规范，JDK 自带的URLEncoder默认会把空格转成+，不符合要求，必须替换成%20，所有参数名、参数值都要做编码后再参与基串拼接，这是90%的401错误的诱因。
• 签名必须携带两个动态参数：oauth_timestamp（当前秒级时间戳，和Twitter服务器时间差不能超过5分钟，生产环境记得开服务器时间同步）、oauth_nonce（每次请求生成的唯一随机字符串，防重放），上面用的ScribeJava会自动生成这两个参数，不用自己写。
• 如果是application/json类型的POST请求，请求体里的JSON字段绝对不要加入签名参数集合，只有URL上的query参数、OAuth协议自带的几个固定参数参与签名，多带任何参数都会导致签名校验失败。
• 别浪费时间尝试把OAuth 1.0a逻辑适配到Quarkus内置OIDC模块里，OIDC的令牌校验、刷新、会话续期逻辑完全不适配OAuth1.0a，硬改的工作量是写过滤器的十倍以上。

快速验证方式 #

第一次对接先调最简单的凭证校验接口GET /1.1/account/verify_credentials.json，这个接口不需要额外传业务参数，签名正确就会返回当前认证用户的信息，调通这个接口之后再开发其他业务逻辑，不要一开始就调试发推、上传媒体这类带复杂请求体的接口，出问题很难排查。
如果遇到401错误，按顺序排查三个点即可：四个密钥有没有复制错误带多余空格、服务器时间是否和标准时间同步、签名参数有没有多带/漏带。

内容的提问来源于stack exchange，提问作者xantrus