Apache Oltu 1.0.2 介绍与入门指南

⚠️ 安全警示：Apache Oltu 已退役，请勿用于任何新项目。 Oltu 于 2018-03 作出退役决议、2018-07 完成向 Apache Attic 的迁移；最后版本 1.0.2 停在 2016-04-22，此后至今零安全维护、零补丁发布。存量系统建议尽快评估迁移到仍在活跃维护的 OAuth 库（如 Spring Security OAuth2 及各类 OpenID Connect 实现）。 本文仅面向存量系统的维护与理解场景；文中实测代码仅用于验证 1.0.2 的 API 行为，不构成使用推荐。

目标：介绍已退役的 Apache Oltu——OAuth 协议的轻量 Java 实现库；覆盖项目定位与退役状态（含漏洞库核查结论）、模块组成、Maven 坐标，以及在 JDK 11 + Maven 环境下构造授权 URL、请求并解析访问令牌的两例上手实测。覆盖范围：定位 / 模块 / 坐标为官方信息调研核实；上手两例为 Ubuntu 22.04 环境实测（2026-10-15），命令与输出均为真实记录。信息核实边界：Attic 时间线与漏洞库核查（NVD / OSV / Snyk）于 2026-10-15 完成；API 行为结论以本文实测为准，协议细节以 RFC 6749 为准。

一、环境信息

操作系统：Ubuntu 22.04（x86_64）
JDK：OpenJDK 11.0.32.1（openjdk-11-jdk-headless）
构建工具：Apache Maven 3.6.3
Mock 服务：python3 http 服务，监听 127.0.0.1:8080（仅本地联调用）
Maven 仓库：中央仓库直连较慢，在 settings.xml 中配置国内加速仓库（maven.aliyun.com/repository/public）后，依赖秒级拉齐
被测版本：org.apache.oltu.oauth2:org.apache.oltu.oauth2.client:1.0.2（终版）
实测时间：2026-10-15（编译时间戳为 UTC，对应北京时间当日凌晨）

二、定位与退役状态

2.1 项目定位（Attic 页面原文）

"Oltu is an OAuth protocol implementation in Java. It also covers others 'OAuth family' related implementations such as JWT, JWS and OpenID Connect. Originally known as Amber."

Apache Oltu 是 OAuth 协议的 Java 实现库，覆盖 OAuth 1.0a / 2.0 两个协议世代，并涉及 OAuth 家族相关实现（JWT、JWS、OpenID Connect）；
前身名为 Amber；
特点是轻量、无框架绑定：以本文实测的 oauth2 client 为例，除 JDK 外仅传递依赖 common 与 org.json 一个第三方库（见 4.1 依赖树），引入成本极低；
按角色拆分模块（client / 授权服务器 / 资源服务器 / 公共模块等，见 3.1 节），可按需取用。

2.2 Attic 时间线

"Oltu became a Top Level Project in January 2013 (board_minutes_2013_01_16.txt), retired in March 2018 (board_minutes_2018_03_21.txt) and the move to the Attic was completed in July 2018 (ATTIC-168)."

时间	事件
2013-01	成为 Apache 顶级项目（TLP，董事会 2013-01-16 会议纪要）
2016-04-22	终版 1.0.2 发布（Snyk 实测 published 日期）
2018-03	董事会作出退役决议（2018-03-21 会议纪要）
2018-07	向 Apache Attic 的迁移完成（工单 ATTIC-168）

即：终版发布两年后即退役，自 2018-07 起项目进入只读归档状态，不再有任何官方修复。

2.3 漏洞库核查结论（2026-10-15，重要）

为给「存量系统能否继续使用」提供事实依据，本文当日对三个权威漏洞库做了核查：

NVD：keywordSearch=oltu、keywordSearch=Apache Oltu，以及按 CPE cpe:2.3:a:apache:oltu 精确匹配（virtualMatchString），三次查询返回均 totalResults: 0（API 本身可用性已用其他关键词对照验证）；
OSV.dev：对 org.apache.oltu.oauth2:org.apache.oltu.oauth2.common、org.apache.oltu.oauth2.authzserver、org.apache.oltu.openidconnect 下的 client 等 Maven 坐标逐一查询，均无记录；
Snyk：org.apache.oltu.oauth2:org.apache.oltu.oauth2.client 包页显示 "No direct vulnerabilities have been found for this package"；0.31 / 1.0.0 / 1.0.1 / 1.0.2 各版本均为 0 漏洞，Latest version 1.0.2（published 22 Apr 2016）。

结论与正确解读：

截至 2026-10-15，NVD / OSV / Snyk 三个漏洞库均未收录任何针对 Apache Oltu 的 CVE 编号；调研中核查过的网传疑似编号，经 NVD 按 cveId 精确查询确认分属 Irssi 与 Apache Airflow 项目，与 Oltu 无关；
因此「勿用于新项目」的依据不是已知 CVE 列表，而是：项目 2018 年入 Attic 后已无官方维护，终版 1.0.2 停在 2016-04-22——未来若发现任何安全问题，将不会有官方补丁；这个「零维护」风险只会随时间增大；
换句话说：Oltu 当前「无已知漏洞」不等于「安全」，只等于「无人再为它做安全工作」。存量系统的正确动作是规划迁移，而不是以「查不到漏洞」为由继续新增依赖。

2.4 终版发行物（archive.apache.org 实测）

https://archive.apache.org/dist/oltu/ 下按组件发行，顶层目录：

org.apache.oltu.commons/  org.apache.oltu.jose/
org.apache.oltu.oauth2/   org.apache.oltu.parent-1/  org.apache.oltu.parent/

其中 org.apache.oltu.oauth2/ 下的 oauth2 组件 source-release 版本序列为 0.31 → 1.0.0 → 1.0.1 → 1.0.2，即 1.0.2 为终版（此后再无发布）。

三、模块组成与核心概念

3.1 模块组成（以发行物与实测为准）

模块	说明
org.apache.oltu.oauth2.client	OAuth 2.0 客户端（本文实测对象）
org.apache.oltu.oauth2.common	公共模块（client 的传递依赖；封装请求/响应消息模型与参数）
org.apache.oltu.oauth2.authzserver	授权服务器（Authorization Server）侧组件
org.apache.oltu.openidconnect	OpenID Connect 相关模块
org.apache.oltu.jose	JOSE 家族（JWT / JWS）组件
org.apache.oltu.commons / parent / parent-1	公共组件与构建父级

说明：完整模块矩阵以 archive.apache.org 发行物与项目存档文档为准；本文实测仅覆盖 oauth2 client 一条链路。

3.2 核心概念（以 client 侧为例）

OAuthClientRequest：请求构造器，链式 API——
- authorizationLocation(...)：构建「授权端点」跳转 URL（authorization code 流第一步），buildQueryMessage() 生成查询串形式；
- tokenLocation(...)：构建「令牌端点」请求，buildBodyMessage() 生成 application/x-www-form-urlencoded 表单体；
OAuthClient + URLConnectionClient：请求执行器，把构造好的请求发往目标端点并取回响应（基于 JDK 的 URLConnection）；
OAuthJSONAccessTokenResponse：令牌端点的 JSON 响应解析器，可读取 access_token / token_type / expires_in / refresh_token 等字段；
GrantType：授权类型枚举（如 GrantType.AUTHORIZATION_CODE）；1.0.2 中需显式设置，详见 4.4 节。

四、安装与上手实测（JDK 11 + Maven）

4.1 Maven 坐标与依赖树

pom.xml 依赖坐标（实测解析成功）：

<dependency>
    <groupId>org.apache.oltu.oauth2</groupId>
    <artifactId>org.apache.oltu.oauth2.client</artifactId>
    <version>1.0.2</version>
</dependency>

mvn dependency:tree 真实输出：

demo:oltu-demo:jar:1.0.0
\- org.apache.oltu.oauth2:org.apache.oltu.oauth2.client:jar:1.0.2:compile
   +- org.apache.oltu.oauth2:org.apache.oltu.oauth2.common:jar:1.0.2:compile
   |  +- org.json:json:jar:20140107:compile

除 JDK 外只有 org.json 一个第三方传递依赖——印证 Oltu「轻量」的定位。编译实测输出：

[INFO] Compiling 1 source file to /root/oltu-demo/target/classes
[INFO] BUILD SUCCESS
[INFO] Total time:  12.777 s
[INFO] Finished at: 2026-10-14T19:34:34Z

（时间戳为 UTC，对应北京时间 2026-10-15 03:34。）

4.2 实测一：构造授权 URL（authorization code 流第一步）

核心代码（取值沿用 RFC 6749 §4.1.1 示例）：

OAuthClientRequest authReq = OAuthClientRequest
    .authorizationLocation("https://auth.example.com/authorize")
    .setClientId("s6BhdRkqt3")
    .setRedirectURI("https://client.example.com/cb")
    .setResponseType("code")
    .setScope("read")
    .buildQueryMessage();
System.out.println("[TEST1] getLocationUri() = " + authReq.getLocationUri());

真实输出：

[TEST1] getLocationUri() = https://auth.example.com/authorize?scope=read&response_type=code&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb&client_id=s6BhdRkqt3

要点：

参数顺序由 Oltu 内部 map 决定（本例为 scope、response_type、redirect_uri、client_id），与书写顺序无关；
参数值自动做了 URL 编码（redirect_uri 中的 :// 编码为 %3A%2F%2F），可直接用于拼装浏览器跳转地址。

4.3 实测二：请求令牌并解析（本地 mock token endpoint）

mock 服务：本地以 python3 http 服务监听 127.0.0.1:8080，对 POST /token 固定返回 RFC 6749 §5.1 示例 JSON：

{"access_token":"2YotnFZFEjr1zCsicMWpAA","token_type":"example","expires_in":3600,"refresh_token":"tGzv3JOkF0XG5Qx2","example_parameter":"example_value"}

核心代码：

// 1. 构造令牌请求（表单体）
OAuthClientRequest tokenReq = OAuthClientRequest
    .tokenLocation("http://127.0.0.1:8080/token")
    .setClientId("s6BhdRkqt3")
    .setClientSecret("gX1fBat3bV")
    .setCode("SplxlOBeZQQYbYS6WxSbIA")
    .setRedirectURI("https://client.example.com/cb")
    .setGrantType(GrantType.AUTHORIZATION_CODE)   // 1.0.2 必须显式设置
    .buildBodyMessage();

// 2. 发送并解析（注意：不是 OAuth.JSONResponse 写法）
OAuthClient client = new OAuthClient(new URLConnectionClient());
OAuthJSONAccessTokenResponse token =
    client.accessToken(tokenReq, OAuthJSONAccessTokenResponse.class);

System.out.println("[TEST2] access_token  = " + token.getAccessToken());
System.out.println("[TEST2] token_type    = " + token.getTokenType());
System.out.println("[TEST2] expires_in    = " + token.getExpiresIn());
System.out.println("[TEST2] refresh_token = " + token.getRefreshToken());

真实输出（含 mock 服务端日志）：

[TEST2] token request body = code=SplxlOBeZQQYbYS6WxSbIA&grant_type=authorization_code&client_secret=gX1fBat3bV&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb&client_id=s6BhdRkqt3
[TEST2] access_token  = 2YotnFZFEjr1zCsicMWpAA
[TEST2] token_type    = example
[TEST2] expires_in    = 3600
[TEST2] refresh_token = tGzv3JOkF0XG5Qx2
[TEST2] raw body      = {"access_token":"2YotnFZFEjr1zCsicMWpAA","token_type":"example","expires_in":3600,"refresh_token":"tGzv3JOkF0XG5Qx2","example_parameter":"example_value"}
=== MOCK LOG ===
MOCK /token received Content-Type: application/x-www-form-urlencoded
MOCK /token received body: code=SplxlOBeZQQYbYS6WxSbIA&grant_type=authorization_code&client_secret=gX1fBat3bV&redirect_uri=https%3A%2F%2Fclient.example.com%2Fcb&client_id=s6BhdRkqt3

4.4 实测结论与 API 注意点

oltu 1.0.2 client 在 JDK 11 上可正常编译运行（本文实测一次编译通过）；
buildBodyMessage 生成 application/x-www-form-urlencoded 的 POST 表单体（mock 服务端日志佐证）；
OAuthJSONAccessTokenResponse 正确解析 access_token / token_type / expires_in / refresh_token；对响应中的额外字段（如示例的 example_parameter）不报错，可经 getParam(...) 读取；
token_type 为非标准值（本例为 "example"）时，1.0.2 客户端不做校验、照常接受——对接真实服务时请自行核对 token_type 语义；
⚠️ API 坑（重要）：1.0.2 没有 OAuthClient.accessToken(msg, OAuth.JSONResponse) 这种写法（出自 Amber 时代或 0.31 时期的旧资料），1.0.2 的实际 API 是泛型方法 client.accessToken(request, OAuthJSONAccessTokenResponse.class)；同时 grant_type 必须显式 setGrantType(GrantType.AUTHORIZATION_CODE)——只设置 code / redirect_uri 等字段时，请求体中不会出现 grant_type 参数；
环境坑实录：实验主机未安装 curl，mock 端与客户端之间的联通性直接由 Java 侧请求结果验证；结束 mock 进程时不要用 pkill -f mock_server.py 这类模糊匹配——它会匹配到包含同字符串的当前 shell 自身导致误杀（实测 exit 143），请先 pgrep 核对 PID 再精确 kill。

五、适用场景与局限

适用场景（仅存量视角）：

正在维护依赖 Oltu 1.0.x 的存量 Java 系统：理解其 API 行为、排查兼容性问题、评估迁移工作量时参考本文；
阅读遗留代码时，对照 3.1 节模块划分与 3.2 节「请求构造 → 发送 → 响应解析」调用链；
短期内无法立即迁移的系统：本文实测结论可作为其当前运行行为的对照基准。

局限与不适用：

请勿用于任何新项目：2018 年起零维护，1.0.2 停在 2016-04-22，未来发现的安全问题不会有官方修复；
协议实现停留在 OAuth 2.0 早期世代，未跟进后续最佳实践；新项目应选择活跃维护的 OAuth 2.0 / OpenID Connect 库（如 Spring Security OAuth2 及各类 OIDC 实现），并按当前规范实施；
客户端对 token_type 等字段不做严格校验（见 4.4 节），继续使用需自行加严校验；
官方支持渠道已随退役关闭，问题排查只能依赖存档文档、源码与社区历史资料。

六、常见问题

Q1：编译报错，找不到 OAuth.JSONResponse？ 1.0.2 没有这个写法（属旧资料遗留）。请改用泛型方法： new OAuthClient(new URLConnectionClient()).accessToken(request, OAuthJSONAccessTokenResponse.class)。

Q2：令牌请求里没有 grant_type 参数？ 需要显式 .setGrantType(GrantType.AUTHORIZATION_CODE)；1.0.2 不会根据其他字段自动补 grant_type。

Q3：授权 URL 的参数顺序和文档示例不一致？ 参数顺序由 Oltu 内部 map 决定（实测为 scope、response_type、redirect_uri、client_id），语义不受顺序影响，属正常现象。

Q4：令牌响应里有非标准字段会解析失败吗？ 不会。实测对额外字段不报错，可通过 getParam("字段名") 读取（见 4.3 节 example_parameter）。

Q5：token_type 不是 "Bearer" 会不会报错？ 实测对非标准值（如 "example"）不校验、照常接受。这意味着客户端侧的 token_type 校验需自行实现。

Q6：Maven 拉取 1.0.2 很慢怎么办？ 中央仓库直连较慢时，可在 settings.xml 配置国内加速仓库（如 maven.aliyun.com/repository/public）；1.0.2 坐标在主流仓库均可用。

Q7：还能继续用在生产吗？ 存量系统短期可运行（本文实测编译运行正常），但项目已零安全维护；「漏洞库查不到记录」不代表安全（见 2.3 节解读）。建议制定迁移计划，逐步切换到活跃维护的 OAuth 2.0 / OpenID Connect 库。

参考链接

Attic 项目页（时间线权威来源）：https://attic.apache.org/projects/oltu.html
发行物归档：https://archive.apache.org/dist/oltu/
oauth2 组件归档（0.31 ~ 1.0.2）：https://archive.apache.org/dist/oltu/org.apache.oltu.oauth2/
NVD 漏洞库检索：https://services.nvd.nist.gov/rest/json/cves/2.0
OSV.dev 查询接口：https://api.osv.dev/v1/query
Snyk 包页（检索 org.apache.oltu.oauth2:org.apache.oltu.oauth2.client）：https://security.snyk.io/
RFC 6749（OAuth 2.0 授权框架，本文示例值来源）：https://datatracker.ietf.org/doc/html/rfc6749