JumpServer 集成应用 API 实战：使用 Java 调用 account-secret 接口查询 PAM 资产账号密码
发布时间：2026/9/10 11:46:31 作者：尧图编辑部 阅读量：1,286
JumpServer 集成应用 API 实战使用 Java 调用 account-secret 接口查询 PAM 资产账号密码【免费下载链接】jumpserverJumpServer is an open-source Privileged Access Management (PAM) platform that provides DevOps and IT teams with on-demand and secure access to SSH, RDP, Kubernetes, Database and RemoteApp endpoints through a web browser.项目地址: https://gitcode.com/GitHub_Trending/ju/jumpserver本指南围绕 JumpServer 开源堡垒机PAM 平台提供的集成应用账号密码查询接口展开以仓库内 Java SDK 示例 及其配套 使用说明 为骨架深入讲解GET /api/v1/accounts/integration-applications/account-secret/接口的请求参数、响应格式与 HMAC-SHA256 签名认证流程。读完本文你将能够在 Java 11 环境中独立编写调用该接口的客户端、理解签名串的构造规则与密钥获取方式并掌握接口背后的源码级鉴权与审计机制从而安全地在自有业务系统中实现按需取密。1. 接口简介该 API 提供 PAM特权访问管理资产账号密码查询服务支持 RESTful 风格调用并以 JSON 格式返回数据。它的典型应用场景是外部业务系统或内部自动化平台以集成应用身份向 JumpServer 申请某个资产账号的密码用于自动化运维、第三方编排工具联动等场景无需人工登录 Web 控制台。接口的能力由 IntegrationApplicationViewSet 中的get_account_secret动作提供路由注册于 apps/accounts/urls.py对应源码片段为router.register(rintegration-applications, api.IntegrationApplicationViewSet, integration-apps)。2. 环境要求在开始编码之前请确保你的运行环境满足以下条件Java 11示例代码使用java.net.http.HttpClient该 API 自 Java 11 起正式引入因此低于 Java 11 的版本无法直接运行。JDK 内置模块java.net.http、javax.crypto用于 HMAC-SHA256 计算均为 JDK 标准库无需额外引入第三方依赖。3. 接口使用说明3.1 请求方式GET /api/v1/accounts/integration-applications/account-secret/接口仅支持GET方法查询参数通过 URL Query String 传递。3.2 请求参数参数名类型必填说明assetstr是资产名称accountstr是账号名称进阶说明来自源码虽然原文档仅列出asset与account两个参数但结合 IntegrationAccountSecretSerializer 的实现可以确认接口同时支持更精确的asset_id与account_idUUID 类型。校验规则为当传入account_id时直接放行否则要求asset/asset_id至少提供一个、account/account_id至少提供一个否则返回 400 错误 At least one of the following fields must be provided。若需要精确定位资产与账号建议优先使用 ID 参数避免同名资产造成歧义。3.3 响应示例请求成功后返回 HTTP 200 与 JSON 数据{ id: 72b0b0aa-ad82-4182-a631-ae4865e8ae0e, secret: 123456 }字段含义id集成应用请求方的 IDsecret目标资产账号的密码明文。3.4 注意事项从 get_account_secret 实现 可以看到当账号不存在时接口会抛出JMSException返回 Not found / Account not found 错误响应中的secret是否返回明文受系统安全配置SECURITY_DISABLE_VIEW_SECRET控制当该配置为真时接口返回secret: null源码注释为根据配置决定是否返回密码。这意味着即使客户端签名合法管理员仍可通过全局安全策略禁止密码外泄每次成功查询都会写入一条IntegrationApplicationLog审计记录字段包含来源 IP、应用名称、账号名称(用户名)、资产名称(地址)实现取密行为全链路可追溯。4. Java 完整示例代码仓库中提供了开箱即用的 demo.java下面分段讲解其核心逻辑。4.1 常量与入口private static final String API_URL System.getenv().getOrDefault(API_URL, http://127.0.0.1:8080); private static final String KEY_ID System.getenv().getOrDefault(API_KEY_ID, 72b0b0aa-ad82-4182-a631-ae4865e8ae0e); private static final String KEY_SECRET System.getenv().getOrDefault(API_KEY_SECRET, 6fuSO7P1m4cj8SSlgaYdblOjNAmnxDVD7tr8); private static final String ORG_ID System.getenv().getOrDefault(ORG_ID, 00000000-0000-0000-0000-000000000002); public static void main(String[] args) throws Exception { APIClient client new APIClient(); String result client.getAccountSecret(ubuntu_docker, root); System.out.println(result); }四个关键值均支持通过环境变量覆盖便于在测试与生产环境间切换而无需改代码API_KEY_ID与API_KEY_SECRET即文档 FAQ 中提到的 KEY_ID / KEY_SECRETORG_ID用于多租户组织隔离场景默认值为00000000-0000-0000-0000-000000000002入口方法演示了查询资产ubuntu_docker下账号root的密码。4.2 构造请求 URLString queryString asset URLEncoder.encode(asset, StandardCharsets.UTF_8) account URLEncoder.encode(account, StandardCharsets.UTF_8); String url API_URL /api/v1/accounts/integration-applications/account-secret/? queryString;参数必须使用URLEncoder做 UTF-8 编码避免资产名/账号名中包含特殊字符如空格、、时破坏 URL 语义。4.3 构造签名串这是整个调用流程中最关键的一步String date ZonedDateTime.now().format(DateTimeFormatter.RFC_1123_DATE_TIME); String requestTarget get /api/v1/accounts/integration-applications/account-secret/? queryString; String signingString (request-target): requestTarget \n accept: application/json\n date: date \n x-jms-org: ORG_ID;签名串由四个以换行符拼接的header: value行组成行含义(request-target)小写 HTTP 方法 空格 带查询串的请求路径accept必须为application/jsondate当前 UTC 时间格式为 RFC 1123HTTP 标准日期格式x-jms-org组织 ID其中date必须是当前时间服务端会校验时间窗口防止重放攻击(request-target)必须与实际请求的 URL 完全一致含查询参数顺序否则签名校验失败。4.4 计算 HMAC-SHA256 签名private String sign(String data, String key) throws Exception { Mac mac Mac.getInstance(HmacSHA256); SecretKeySpec secretKeySpec new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), HmacSHA256); mac.init(secretKeySpec); byte[] rawHmac mac.doFinal(data.getBytes(StandardCharsets.UTF_8)); return Base64.getEncoder().encodeToString(rawHmac); }以KEY_SECRET作为密钥对签名串计算 HMAC-SHA256并将结果进行Base64 编码后放入Authorization头。4.5 组装并发送请求HttpRequest request HttpRequest.newBuilder() .uri(URI.create(url)) .header(Accept, application/json) .header(Date, date) .header(X-JMS-ORG, ORG_ID) .header(X-Source, jms-pam) .header(Authorization, Signature keyId\ KEY_ID \,algorithm\hmac-sha256\,headers\(request-target) accept date x-jms-org\,signature\ signature \) .build();Authorization头携带四要素keyId即 KEY_ID服务端据此查找集成应用algorithmhmac-sha256与签名算法一致headers参与签名的头部清单与签名串中的行一一对应signatureBase64 编码后的 HMAC 值。额外说明X-Source: jms-pam头对应服务端 ServiceAuthentication 中的source jms-pam常量标识请求来源为 PAM 集成应用。HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); if (response.statusCode() 200) { return response.body(); } else { System.err.println(API request failed: response.statusCode()); return null; }发送请求后状态码为 200 时直接返回 JSON 响应体否则打印失败状态码。5. 签名认证原理源码级解析示例代码中的签名过程并非 JumpServer 自创协议而是遵循标准的 HTTP 签名规范服务端通过 SignatureAuthentication 系列类完成验签。其核心调用链如下查找应用ServiceAuthentication.get_object(key_id)通过IntegrationApplication.objects.filter(idkey_id, is_activeTrue)查询集成应用应用不存在或未激活则认证失败。取回密钥fetch_user_data返回(应用对象, 应用secret)即用于验签的 HMAC 密钥。IP 白名单校验is_ip_allow会校验请求来源 IP 是否落在应用配置的ip_group内默认[*]表示不限制超出白名单直接拒绝——这也是 IntegrationApplicationSerializer 中ip_group字段的意义。时间戳防重放date头参与签名服务端校验时间有效性防止旧请求重放。服务端验签通过后request.user即为该集成应用对象get_account_secret中执行service.get_account(**serializer.data)完成资产账号检索与密码返回。此外应用创建时通过instance.refresh_secret()自动生成初始secret且 refresh_secret 动作 支持随时轮换密钥secret的查看get_once_secret还需要额外通过 MFA 用户确认UserConfirmation.require(ConfirmType.MFA)体现了最小权限与动态凭证的安全设计。6. API Key 的获取Q: API Key 如何获取A:在 JumpServer Web 控制台进入PAM → 应用管理创建一个集成应用系统会为其生成一对KEY_ID与KEY_SECRETKEY_ID应用唯一标识即签名头中的keyIdKEY_SECRET签名密钥请妥善保管泄露等同于账号密码可被任意读取。创建应用时还可配置关联账号accounts字段应用可查询的账号范围访问 IP 白名单ip_group字段限制哪些来源 IP 可以使用该密钥启用状态is_active停用后签名认证将直接失败。安全建议生产环境务必通过环境变量注入 KEY_SECRET避免硬编码进源码或仓库并定期使用应用管理中的刷新密钥功能轮换密钥。7. 常见问题FAQQ: 请求返回 401 / 签名校验失败怎么办A: 按以下顺序排查确认(request-target)中的路径与查询参数和实际请求 URL 完全一致方法必须是小写get确认date为当前 UTC 时间RFC 1123 格式服务器与客户端时钟偏差过大也会导致失败确认Authorization头中headers字段与签名串行数、顺序一致确认 KEY_ID / KEY_SECRET 与 PAM 应用管理中的一致且应用处于启用状态确认客户端出口 IP 在应用的ip_group白名单内。Q: 返回 200 但 secret 为 nullA: 系统安全策略SECURITY_DISABLE_VIEW_SECRET被开启时接口会隐藏密码明文需要管理员调整该全局配置。Q: 查询的账号不存在A: 接口返回 Not found 错误请检查资产名称/账号名称拼写或改用asset_id/account_id精确定位。Q: 使用其它语言如何实现A: 签名协议与语言无关仓库为每种语言都提供了等价示例可参考 curl、Go、Node.js、Python 的完整实现。8. 版本历史版本号变更内容日期1.0.0初始版本2025-02-119. 延伸阅读若希望深入理解接口背后的完整实现推荐阅读以下仓库文件接口服务端实现apps/accounts/api/account/application.py参数校验逻辑apps/accounts/serializers/account/service.py路由注册apps/accounts/urls.py签名认证实现apps/authentication/backends/drf.pyJava 示例与配套文档demo.java、使用说明中文、使用说明英文【免费下载链接】jumpserverJumpServer is an open-source Privileged Access Management (PAM) platform that provides DevOps and IT teams with on-demand and secure access to SSH, RDP, Kubernetes, Database and RemoteApp endpoints through a web browser.项目地址: https://gitcode.com/GitHub_Trending/ju/jumpserver创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 