JumpServer PAM 账号密码查询 API：Python 集成指南（account-secret 接口实战）

JumpServer PAM 账号密码查询 APIPython 集成指南account-secret 接口实战【免费下载链接】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/jumpserverJumpServer 作为开源特权访问管理PAM平台为运维和 IT 团队提供了统一的账号资产托管与安全审计能力。当外部业务系统需要获取托管资产的账号密码时JumpServer 提供了 RESTful 的集成应用Integration Application接口。本文围绕 apps/accounts/demos/python/README.zh-hans.md 文档结合 Python 示例代码 与仓库源码完整讲解账号密码查询接口的请求方式、参数约定、签名认证原理、服务端校验逻辑与常见问题读完即可编写出可安全接入 JumpServer 的 Python 客户端。1. 接口概览本 API 提供 PAM 资产账号密码查询服务支持 RESTful 风格调用并以 JSON 格式返回数据。它的本质是集成应用Integration Application能力的一部分管理员先在 PAM 平台中创建应用并绑定账号外部系统再凭应用的 Key 以 HTTP 签名方式换取指定资产的账号密码。请求方式GET接口路径api/v1/accounts/integration-applications/account-secret/返回格式application/json1.1 请求参数参数名类型必填说明assetstr是资产名称accountstr是账号名称1.2 响应示例{ id: 72b0b0aa-ad82-4182-a631-ae4865e8ae0e, secret: 123456 }其中id为集成应用即调用方的 IDsecret为查询到的账号密码。说明响应中的id对应调用方集成应用自身而不是资产或账号 ID。这一行为由 application.py 中的Response(data{id: request.user.id, secret: secret})决定。2. 环境要求官方 Python 示例的运行环境要求如下Python 3.11requests2.31.0httpsig1.3.0其中httpsig用于实现 HTTP 签名认证HTTP Signaturerequests负责发起 HTTP 请求。需要注意的是setup.py中的python_requires3.6是 SDK 打包时的最低声明而官方 Demo 面向 Python 3.11 验证生产使用建议以 3.11 为准。3. 运行示例API Key 从哪来3.1 在 PAM 中创建应用Q: API Key 如何获取A: 您可以在PAM - 应用管理中创建应用以生成KEY_ID和KEY_SECRET。在 JumpServer 中这个应用对应数据模型 IntegrationApplication其核心字段包括name应用名称与组织组合后唯一unique_together [(name, org_id)]secret应用的密钥即KEY_SECRET加密存储EncryptTextFieldaccounts该应用可查询的账号集合JSONManyToManyField即权限边界——应用只能查询被授权绑定的账号ip_group允许调用来源的 IP 分组白名单is_active应用是否启用。应用创建后应用 ID 即为KEY_IDsecret即为KEY_SECRET。密钥可通过refresh_secret重新生成见 application.pyrandom_string(36)生成 36 位随机串刷新后旧密钥立即失效客户端需同步更新。3.2 快速运行官方 Demo仓库提供了开箱即用的示例 demo.py支持通过环境变量注入配置export API_URLhttp://127.0.0.1:8080 export API_KEY_ID72b0b0aa-ad82-4182-a631-ae4865e8ae0e export API_KEY_SECRET6fuSO7P1m4cj8SSlgaYdblOjNAmnxDVD7tr8 export ORG_ID00000000-0000-0000-0000-000000000002 python demo.pyDemo 中提供的默认值仅为占位示例实际使用时请替换为在应用管理中创建的真实凭据。运行时输出如下查询资产ubuntu_docker的root账号# demo.py 核心调用 if __name__ __main__: client APIClient() result client.get_account_secret(assetubuntu_docker, accountroot) print(result)4. 签名认证原理HTTP Signature HMAC-SHA256该接口并不使用简单的 Token 或 Basic Auth而是采用HTTP Signaturehttpsig签名方案。Demo 中认证对象的构建方式如下from httpsig.requests_auth import HTTPSignatureAuth self.auth HTTPSignatureAuth( key_idKEY_ID, secretKEY_SECRET, algorithmhmac-sha256, headers[(request-target), accept, date, x-jms-org] )签名会覆盖以下请求要素防止请求被篡改或重放(request-target)请求方法 路径get /api/v1/accounts/integration-applications/account-secret/acceptapplication/jsondateRFC 7231 格式的 GMT 时间戳x-jms-org组织 ID。对应的请求头由 Demo 组装headers { Accept: application/json, X-JMS-ORG: ORG_ID, Date: datetime.utcnow().strftime(%a, %d %b %Y %H:%M:%S GMT), X-Source: jms-pam }其中Date必须与签名时使用的date一致格式为%a, %d %b %Y %H:%M:%S GMT如Tue, 09 Sep 2026 02:41:38 GMT。跳板机等中间层不会影响 httpsig 对(request-target)的规范化计算因此无需额外处理。此外仓库还提供了更完整的封装 jms_pam/main.pySecretRequest对asset/asset_id/account/account_id做参数校验Secret统一封装secret与错误描述descvalid not descJumpServerPAM客户端门面_get_auth()中签名头为[(request-target), accept, date]send()负责拼接 URL、发起请求并解析响应。该模块可通过 setup.py 打包为jms-pam库pip install .供业务系统以库的方式集成。5. 服务端校验逻辑与参数进阶虽然 README 只列出了assetaccount两个参数但服务端实际支持四种参数的组合查询。序列化器定义位于 service.pyclass IntegrationAccountSecretSerializer(serializers.Serializer): asset serializers.CharField(requiredFalse, allow_blankTrue) asset_id serializers.UUIDField(requiredFalse, allow_nullTrue) account serializers.CharField(requiredFalse, allow_blankTrue) account_id serializers.UUIDField(requiredFalse, allow_nullTrue)提供account_id时必须唯一提供且不能再传asset/asset_id/account提供account账号名称时必须同时提供asset资产名称或asset_id资产 ID之一account_id与asset_id不允许同时出现至少需要提供asset或asset_id之一以及account或account_id之一。服务端命中账号的查找逻辑见 application.py优先按account_id精确匹配否则按account名称再叠加asset_id或asset__name过滤最后统一叠加应用绑定的账号集合做权限过滤返回distinct().first()。请求处理主流程位于 application.py参数校验失败直接返回400及{error: serializer.errors}以request.user作为集成应用调用service.get_account(**serializer.data)查询账号查不到则抛出JMSException(Not found)每次查询都会写入IntegrationApplicationLog审计日志记录远端 IP、服务名、账号与资产信息见 audits满足 PAM 审计要求若系统配置了SECURITY_DISABLE_VIEW_SECRET禁止查看密码则secret字段返回None——即使查询成功也不返回明文密码。鉴权方面get_account_secret使用RBACPermission要求调用方拥有accounts.view_integrationapplication权限应用模型 is_valid / is_authenticated 直接与is_active绑定即应用被停用后接口立即拒绝服务。6. 完整可运行示例以下代码综合 README 参数表与仓库实现形成最小可运行客户端可与demo.py对比使用import os import requests from datetime import datetime from httpsig.requests_auth import HTTPSignatureAuth API_URL os.getenv(API_URL, http://127.0.0.1:8080) KEY_ID os.getenv(API_KEY_ID, ) KEY_SECRET os.getenv(API_KEY_SECRET, ) ORG_ID os.getenv(ORG_ID, 00000000-0000-0000-0000-000000000002) class APIClient: def __init__(self): self.session requests.Session() self.auth HTTPSignatureAuth( key_idKEY_ID, secretKEY_SECRET, algorithmhmac-sha256, headers[(request-target), accept, date, x-jms-org] ) def get_account_secret(self, asset, account): url f{API_URL}/api/v1/accounts/integration-applications/account-secret/ headers { Accept: application/json, X-JMS-ORG: ORG_ID, Date: datetime.utcnow().strftime(%a, %d %b %Y %H:%M:%S GMT), X-Source: jms-pam } params {asset: asset, account: account} response self.session.get( url, authself.auth, headersheaders, paramsparams, timeout10 ) response.raise_for_status() return response.json() if __name__ __main__: client APIClient() print(client.get_account_secret(assetubuntu_docker, accountroot))调用时替换API_URL、KEY_ID、KEY_SECRET为真实环境值若查询的是组织内的资产务必让ORG_ID与X-JMS-ORG保持一致否则服务端会在签名校验阶段因x-jms-org不一致而拒绝请求。7. 常见问题FAQ与排查指引Q: API Key 如何获取A: 在 PAM - 应用管理中创建应用生成KEY_ID与KEY_SECRET创建后可在应用详情中查看一次性 Secret也可通过刷新接口重新生成。Q: 返回 401/签名失败检查三处KEY_SECRET是否与应用当前 Secret 一致刷新过则需同步Date头是否为 GMT 格式且与签名时一致X-JMS-ORG是否与签名头列表中的x-jms-org匹配。Q: 返回 Account not found确认账号名/资产名拼写正确且该账号已被授权绑定到集成应用accounts字段跨组织查询需使用正确的ORG_ID。Q: 返回 200 但secret为 null这是服务端开启了SECURITY_DISABLE_VIEW_SECRET的安全配置属于预期行为需由管理员评估后调整。Q: 请求来源被拒绝应用配置了ip_group白名单请确认发起请求的出口 IP 在允许范围内且应用处于is_active启用状态。8. 版本历史版本号变更内容日期1.0.0初始版本2025-02-11延伸阅读官方 Python 示例demo.py 与 jms_pam/main.py服务端视图实现application.py集成应用模型application.py参数序列化器service.py路由注册urls.py同接口的 curl / Go / Java / Node 实现见 apps/accounts/demos 目录便于对照迁移【免费下载链接】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），仅供参考