Bindu Agent 身份认证实战指南：基于 Ory Hydra 的 Bearer Token 机制与配置排查

Bindu Agent 身份认证实战指南基于 Ory Hydra 的 Bearer Token 机制与配置排查【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址: https://gitcode.com/gh_mirrors/bin/Bindu导读本文以 docs/AUTHENTICATION.md 为核心系统讲解 Bindu 中 AI Agent 的 HTTP 身份认证层一个基于Ory Hydra的 OAuth 2.0 Bearer Token 方案。你将掌握认证Authentication与身份签名DID signing两大概念如何分工、Bearer Token 的完整生命周期注册客户端 → 换取令牌 → 调用 Agent → 服务端 introspection 校验以及如何通过环境变量开启认证、用 curl 完成三步实操、并快速定位常见的 401/403 错误。读完本文你可以独立为 Bindu Agent 配置并调试一套可用的认证链路。一、先想清楚Agent 收到请求时要回答的两个问题当一个 Agent 收到 HTTP 请求它在做任何事之前必须先决定一件事我到底该不该回答这个请求这个问题看似简单背后却隐藏着一个更深的问题——就像一位陌生人拿着信封来敲门你开门之前需要确认两件事他们是谁—— 信封上的名字可能是真的也可能是假的。他们被允许进来吗—— 即使名字是真的他们是否有权限进入这个特定的房间大多数认证教程会把这两件事混为一谈。在 Bindu 中它们被严格分开因为二者需要不同的工具问题由谁回答存在于哪里你被允许发出这个请求吗认证Authentication—— 由受信任服务签发的访问令牌OAuth 2.0 / Ory Hydra这个请求真的来自它所声称的身份吗DID 签名—— 只有持有私钥才能生成的密码学签名参见 DID.md在真实场景中两者几乎总是同时需要。本文聚焦第一个问题读完本文后再阅读 DID 文档二者合起来才能解释一个真实 Bindu 请求的完整生命周期。从源码结构看Bindu 的认证中间件也确实是混合设计HydraMiddleware的 docstring 明确写着hybrid OAuth2 DID authentication在验证 token 有效之后还会对client_id以did:开头的调用方强制校验 DID 签名见 bindu/server/middleware/auth/hydra.py。二、Bearer Token 背后的思想想象一家电影院。买票时门口的人并不关心你叫什么名字——他们只需要证明你付过钱。你递上一张纸质票对方撕下票根你走进去。这张票就是凭证。任何持有有效票的人都可以进入——这就是它被称为bearer持有者token 的原因谁持有它谁就获得访问权。HTTP 中的Bearer Token工作原理相同。它是一个看似随机的字符串。你的客户端把它附加到每个请求上。服务器看一眼这个字符串判断好的这是一张有效票据——放行而不会进一步盘问你。Bindu 中一个真实的 bearer token 长这样ory_at_hV2cm_iq55iipi8M53mwvQbpNwQNfTTxvJnDlOWFRYw.I8V_GL5s2afZTh_ZMpshauGpnItx7iItBc6pgVRAOVg它作为 HTTP 头随每个请求发送Authorization: Bearer ory_at_hV2cm_iq55iipi...这就是 Bindu 认证部分的全部客户端附带 bearer token服务器校验它如果有效请求就被放行。从谁持有它谁就能进这一原则自然推导出两条铁律把 Token 当密码对待。泄漏的 token 就是敞开的大门。不要把它粘贴到聊天应用里不要提交到 git不要写进日志。给它设置过期时间。Bindu 的 token 大约存活一小时。即使 token 泄漏损害窗口也是有限的。从实现上看Bindu 的服务端中间件会对 token 做三重校验active必须为true、必须携带subsubject声明、exp必须晚于当前时间任何一项不满足都会抛出错误并拒绝请求见 bindu/server/middleware/auth/hydra.py 中的_validate_token。三、谁签发 Token认识 Hydra现在一个明显的问题出现了bearer token 从哪来Agent 当然不会自己发——那就好比让电影院门口检票的人同时去经营售票亭。取而代之Bindu 使用一个独立服务其全部职责就是签发和校验 token。这个服务就是Ory Hydra—— 一个开源的 OAuth 2.0 服务器久经考验被大量公司使用。Bindu 不自己实现签发逻辑因为 token 签发这件事很容易在细节上出错又很难审查。Hydra 对外暴露两个不同的 URLURL用途谁调用它https://hydra.getbindu.comPublic公开—— 向客户端签发 token。端点如/oauth2/token。客户端你的代码、Postman、gatewayhttps://hydra-admin.getbindu.comAdmin管理—— 注册客户端、查询 token 的含义。端点如/admin/*。Agent、注册脚本这两个 URL 是同一个 Hydra 进程上的两个监听器背后共享同一个数据库。在 admin 上注册一个客户端会立即可见于 public 端的 token 端点——这正是整个流程可以在两个主机名之间顺畅工作、而无需任何同步步骤的原因。为什么要有两个 URLAdmin 端点绝不能暴露到公网。任何能访问/admin/clients的人都可以注册新客户端或读取密钥。在生产环境中admin 位于私有网络只有 public URL 对外可达。Bindu 的配置模型也印证了这一点bindu/settings.py 中的HydraSettings默认admin_urlhttps://hydra-admin.getbindu.com、public_urlhttps://hydra.getbindu.com并提供了timeout默认 10 秒、verify_ssl默认 True、max_retries默认 3等连接参数。而 bindu/auth/hydra/client.py 中的HydraClient正是围绕 admin API 封装了introspect_token、create_oauth_client、get_oauth_client、update_oauth_client、delete_oauth_client、revoke_token、health_check等操作——它默认使用base_urladmin_url并在 admin URL 缺省时尝试用默认端口admin 4445 / public 4444推导 public URL。四、全流程走查从客户端到 Agent当一个客户端想要与某个 Agent 对话时端到端发生的事如下┌─────────┐ ┌──────────────┐ ┌──────────────┐ ┌───────┐ │ Client │ │ Hydra admin │ │ Hydra public │ │ Agent │ └────┬────┘ └──────┬───────┘ └──────┬───────┘ └───┬───┘ │ │ │ │ │ 1. Register as OAuth client │ │ │ ├─────────────────────────────▶│ │ │ │ │ │ │ │ 201 Created │ │ │ │◀─────────────────────────────┤ │ │ │ │ │ │ │ 2. Exchange secret for a token │ │ ├────────────────────────────────────────────────────────────▶ │ │ │ │ │ │ access_token (valid ~1h) │ │ │ │◀──────────────────────────────────────────────────────────── │ │ │ │ │ │ 3. Call agent with Authorization: Bearer token │ │ ├────────────────────────────────────────────────────────────────────────────────────▶ │ │ │ │ │ │ │ 4. Agent asks Hydra: is this token valid? │ │ │◀─────────────────────────────────────────────────────┤ │ │ │ │ │ │ activetrue, expires in X │ │ │ ├─────────────────────────────────────────────────────▶│ │ │ │ │ │ 5. Response │ │ │ │◀────────────────────────────────────────────────────────────────────────────────────┤ │ │ │ │三个真实世界的步骤每一步都有自己的形态步骤 1每个客户端只做一次—— 你向 Hydra 自我介绍。Hydra 记录你是谁并给你一个 client secret。这很少发生——通常只在新的客户端被初始化时做一次。步骤 2每小时一次—— 你用 secret 换取一个短生命周期的 bearer token。secret 是长生命周期的token 不是。步骤 3–5每个请求—— 你把 token 附加到每个请求上。Agent 不会盲目信任 token它会请 Hydra 确认它仍然有效。步骤 4 被称为token introspection令牌内省。正是它让 Hydra 的不透明 token 变得安全Agent 从不自行解读 token只询问 Hydra 它代表什么。在 Bindu 源码中这一步落在 bindu/server/middleware/auth/hydra.py 的_validate_token中间件用hashlib.sha256对 token 做摘要作为缓存键调用HydraClient.introspect_token(token)对应 bindu/auth/hydra/client.py 中 POST/admin/oauth2/introspect并校验返回值。校验通过后_extract_user_info会把 introspection 结果归一化为标准的 user/service 对象sub、client_id、scope、exp、iat、is_m2m等随后通过_attach_user_context写入 ASGI scope 的state[user]让下游 handler 知道是谁在调用见 bindu/server/middleware/auth/base.py。4.1 一个值得一提的优化introspection 缓存每次请求都打一次 Hydra 会带来额外延迟。因此中间件实现了 introspection 缓存默认 TTL 为 5 分钟CACHE_TTL_SECONDS 300可通过HYDRA__CACHE_TTL覆盖缓存键为 token 的 SHA-256 摘要缓存条目在min(token.exp, now cache_ttl)时过期。但缓存会带来一个副作用被撤销的 token 最长还能在本地存活 5 分钟。为此bindu/server/middleware/auth/hydra.py 定义了DEFAULT_SENSITIVE_SCOPESadmin、agent:execute、payment:capture、key:rotate凡是携带这些 scope 的 token一律不缓存每个请求都重新 introspection从而让撤销立即生效。这一设计正是对历史缺陷的修复详见 bugs/core/2026-04-26-hydra-token-cache-revocation-lag.md。中间件还提供了invalidate_token_cache(token)与revoke_token(token)内部先调 Hydra 撤销、再清本地缓存并实现了 O(1) 摊还的_lazy_clean_cache清理逻辑。对应的测试用例在 tests/unit/server/middleware/test_hydra_token_cache.py。五、Token 里到底有什么以及没有什么Bindu 的 bearer token 看起来随机这是刻意为之。它是不透明的——一个句柄而不是一份文档。读取字符串本身不会透露任何关于用户身份的信息。所有含义都存在于 Hydra 的数据库中。当 Agent introspection 一个 token 时Hydra 返回类似下面的内容{ active: true, client_id: did:bindu:dutta_raahul_at_gmail_com:postman:ee67868d-d4b6-..., sub: did:bindu:dutta_raahul_at_gmail_com:postman:ee67868d-d4b6-..., scope: openid offline agent:read agent:write, exp: 1776622403, iat: 1776618803, token_type: Bearer }逐行解读active: true—— Hydra 仍然认为这个 token 有效。如果 token 已过期、被撤销、或从未签发此值翻转为false请求被拒绝。client_id/sub—— 此 token 所签发给的客户端标识。这通常是一个 DID。DID 文档解释了为什么。scope—— 这个 token 携带的权限列表。把 scope 想象成这张票允许你进入房子的哪些房间。agent:read提供读权限agent:write提供写权限。exp—— token 过期的 Unix 时间戳。在此之后active变为false。iat—— token 被签发的时间。Agent 的中间件读取这个对象决定是否放行请求并把client_id附加到传入请求的上下文中让 handler 知道谁在调用。从源码看中间件对返回结果的要求比文档描述得更严格不仅要求activetrue还强制要求必须携带sub与exp声明否则直接判定 token 无效bindu/server/middleware/auth/hydra.py 的_validate_token。此外_extract_user_info还会区分 M2M机器对机器与用户型 token当token_type access_token且grant_type client_credentials时标记is_m2mTrue此时sub即服务身份否则会尝试从ext扩展字段中提取username、email、name、preferred_username等用户属性。六、在 Bindu 中打开认证开关在开发环境中认证默认是关闭的。要打开它设置几个环境变量告诉 Bindu 该与哪个 Hydra 通信# 打开总开关 AUTH__ENABLEDtrue # 目前只支持 Hydra AUTH__PROVIDERhydra # 你的 Hydra 实例位于哪里 HYDRA__ADMIN_URLhttps://hydra-admin.getbindu.com HYDRA__PUBLIC_URLhttps://hydra.getbindu.com双下划线__是 Bindu 把嵌套配置扁平化为环境变量的方式。AUTH__ENABLED映射到settings.auth.enabledHYDRA__ADMIN_URL映射到settings.hydra.admin_url。你不需要关心映射细节——直接设置即可。配置模型的env_prefix定义见 bindu/settings.pyAuthSettings前缀为AUTH__HydraSettings前缀为HYDRA__。当你的 Agent 带着这些配置启动时中间件会自动配置自己通过 Hydra admin 做 introspection。拒绝任何没有有效Authorization: Bearer ...头的传入请求。把 introspection 结果附加到请求上让下游代码知道是谁在调用。6.1 中间件是如何被装进应用的在 bindu/server/applications.py 的_setup_middleware中认证中间件的装配遵循明确的顺序CORS → X402支付→ mTLS →Hydra 认证→ Metrics。逻辑要点只要auth_enabled参数为真或app_settings.auth.enabled为真就会安装认证中间件settings 为准在mtls模式下mTLS 为唯一认证层会跳过 Hydra因为证书本身就是凭证_create_auth_middleware根据app_settings.auth.provider选择实现目前仅支持hydra否则抛出ValueError。6.2 更多可调参数除文档列出的四个变量外HydraSettings还提供一批有默认值的参数均可通过HYDRA__*环境变量覆盖见 bindu/settings.py环境变量默认值说明HYDRA__TIMEOUT10请求超时秒HYDRA__VERIFY_SSLTrue是否校验 SSL 证书HYDRA__MAX_RETRIES3失败请求的最大重试次数HYDRA__CACHE_TTL300introspection 缓存 TTL秒HYDRA__MAX_CACHE_SIZE1000缓存最大条目数HYDRA__SENSITIVE_SCOPESadmin, agent:execute, payment:capture, key:rotate携带这些 scope 的 token 不做缓存撤销即时生效HYDRA__AUTO_REGISTER_AGENTSTrueAgent 启动时是否自动在 Hydra 注册为 OAuth 客户端HYDRA__DEFAULT_AGENT_SCOPESopenid offline agent:read agent:write自动注册时申请的默认 scopeHYDRA__DEFAULT_GRANT_TYPESclient_credentials, authorization_code, refresh_token自动注册时的默认授权类型AuthSettings中还有两个对生产很有用的开关public_endpoints无需认证即可访问的路径白名单默认含/.well-known/agent.json、/health、/metrics、/did/resolve、/agent/skills、/payment-capture等。中间件在启动时会把它们编译为正则每个请求 O(1) 判定是否放行见 bindu/server/middleware/auth/base.py 的_is_public_endpoint。allowed_didsDID 准入白名单。默认为None所有通过 introspection 与签名的调用者都被放行一旦配置了列表只有列表内的 DID 会被放行其余一律 403见 bindu/server/middleware/auth/hydra.py 的_is_did_admitted对应测试在 tests/unit/server/middleware/test_hydra_admission.py。七、获取你的第一个 Bearer Token步骤 1 —— 在 Hydra 注册你的客户端把它想象成在银行开户。你告诉 Hydra 你是谁Hydra 归档这些文件。curl -X POST https://hydra-admin.getbindu.com/admin/clients \ -H Content-Type: application/json \ -d { client_id: did:bindu:your_email_at_example_com:your_agent:uuid, client_secret: pick a strong random value, grant_types: [client_credentials], response_types: [token], scope: openid offline agent:read agent:write, token_endpoint_auth_method: client_secret_post }对每个字段的说明client_id—— 你的 Agent 在 Hydra 中的名字。在 Bindu 中这总是一个 DID 字符串原因见 DID 文档。Hydra 把它当作任意不透明标识符DID 机制在其之上添加意义。client_secret—— 你获取 token 的密码。生成 32 字节随机数openssl rand -base64 32 | tr -d | tr / -_像保存数据库密码一样保存它。步骤 2 还需要用到。grant_types—— 你将如何获取 token。client_credentials意味着我是服务器不是浏览器里的人——没有登录表单没有重定向只是用 secret 换 token。scope—— 你希望 token 携带的权限。不要申请你用不到的 scope。token_endpoint_auth_method: client_secret_post—— 表示你会把 secret 放在请求体HTTP POST 表单中发送而不是放在请求头里。两者都有效Bindu 的代码使用post以保持兼容。从源码看注册是怎么自动化的如果你使用bindufy部署 Agent注册通常不需要手工执行。bindu/auth/hydra/registration.py 的register_agent_in_hydra会在HYDRA__AUTO_REGISTER_AGENTStrue默认时自动完成注册以 DID 作为client_id用secrets.token_urlsafe(32)生成 secret把public_keyEd25519 base58写入 Hydra 客户端的metadata.public_key供后续 DID 签名校验使用并支持从 Vaultdocs/VAULT_INTEGRATION.md恢复或备份凭据、对已存在客户端做幂等复用与 audience 修补。步骤 2 —— 用 secret 换取 token每当你的 access token 即将过期或第一次需要时调用curl -X POST https://hydra.getbindu.com/oauth2/token \ -H Content-Type: application/x-www-form-urlencoded \ -d grant_typeclient_credentials \ -d client_iddid:bindu:your_email_at_example_com:your_agent:uuid \ -d client_secretthe secret from step 1 \ -d scopeopenid offline agent:read agent:write响应{ access_token: ory_at_...long opaque string..., expires_in: 3599, scope: openid offline agent:read agent:write, token_type: bearer }access_token就是你的 bearer token。复制它。不要记录它。把它放在内存中保存约一小时快到期时再刷新。步骤 3 —— 使用 tokencurl --location http://localhost:3773/ \ --header Content-Type: application/json \ --header Authorization: Bearer ory_at_... \ --data { jsonrpc: 2.0, method: message/send, params: { message: { role: user, content: Hello! } }, id: 1 }如果 Agent 返回真实数据说明你的认证已经生效。如果它用 401 或 403 拒绝下一节解释原因。提示localhost:3773是本地 Agent 的默认端口。客户端也可以通过?token...查询参数传递 token用于严格的 WebSocket/SSE 场景或在 WebSocket 握手时使用sec-websocket-protocol: bearer-token子协议——这两条回退路径都实现在 bindu/server/middleware/auth/base.py 的_extract_token中。八、可能出什么问题以及每个错误的含义错误是新手消耗时间最多的地方。下面是一张错误地图——如果你看到其中一个去原因列找它修复那个问题而不是别的东西。你看到的现象最可能的原因修复方法401 Unauthorized没有Authorization头你忘了附加 token添加Authorization: Bearer token401 Unauthorizedintrospection 返回active:falseToken 已过期重新执行步骤 2 获取新 token401 Unauthorizedintrospection 说 token 不存在Token 属于另一个 Hydra不是 Agent 用的那个检查HYDRA__ADMIN_URL—— Agent 和客户端必须指向同一个 Hydratoken 端点的invalid_clientclient_secret错误、client_id错误、或该客户端在此 Hydra 上不存在先注册客户端或仔细核对 secrettoken 端点的invalid_scope申请了客户端未注册的 scope要么给客户端注册更多 scope要么少申请一些Token 在一个端点能用在另一个端点失败Agent 要求一个你未申请的特定 scope申请该 scope如agent:write并获取新 token还有一个更隐蔽的情况值得单独强调现象对某个 Hydra URL 的 introspection 返回active:true但 Agent 说 token 无效。原因Agent 被配置成与签发该 token 的另一个Hydra 实例通信。当开发机的HYDRA__ADMIN_URL指向本地 Hydra、而 token 来自生产环境时就会发生这种情况。修复确保 Agent 使用的HYDRA__ADMIN_URL指向你注册并获取 token 的同一个 Hydra。检查 Agent 的启动日志——它会打印它正在使用的 admin URL。从源码看中间件在 Hydra 不可达连接拒绝或超时时会返回 503 Authentication service temporarily unavailable而不是 401active:false或 token 被撤销会映射为 401 Token is not active or has been revoked见 bindu/server/middleware/auth/hydra.py 的_handle_validation_error。另外未携带 token 的请求会以 JSON-RPC 2.0 格式返回 401且id为null——这是有意为之避免解析未认证的超大请求体DoS 防护见 bindu/server/middleware/auth/base.py。九、丢失凭据时如何找回两件值得记住的事你的 Agent 的 DID发布在它的 agent card 中curl http://localhost:3773/.well-known/agent.jsonagent.did字段或类似字段保存着 DID——它也是 Hydra 的client_id。你的 client secret由bindufy生成保存在本地的.bindu/oauth_credentials.json中。像对待.ssh/id_rsa一样对待这个文件——只读、仅当前用户、绝不提交到仓库。从源码看这个文件的写入逻辑在 bindu/auth/hydra/registration.py 的save_agent_credentials中文件以 DIDclient_id为键保存凭据因为 agent_id 在重载时会变而 DID 保持稳定并且会用chmod(0o600)设置只有属主可读写日志还会警告你把它加入.gitignore。如果你完全丢失了 client secret可以通过 admin API 注册一个新的用PUT /admin/clients/client_id替换它。PUT轮换在 DID 设置文档中有说明。提醒Hydra 的PUT /admin/clients/{id}是整体替换full replace不是补丁。因此更新时必须提交完整的客户端记录同时GET不会返回client_secret的哈希所以用 GET 响应直接拼 PUT 会导致 secret 被意外轮换。源码中 bindu/auth/hydra/client.py 的update_oauth_clientdocstring 与 bindu/auth/hydra/registration.py 的 audience 修补逻辑都特别注释了这一陷阱。十、下一步认证回答了你被允许进来吗。但在一个 Agent 可能代表第三个 Agent 向另一个 Agent 请求工作的世界里你需要回答一个更有力的问题你真的是你声称的那个人吗这就是 DID 签名处理的范畴。继续阅读DID.md。附录常用命令速查注册一个客户端curl -X POST https://hydra-admin.getbindu.com/admin/clients \ -H Content-Type: application/json \ -d { ...see step 1 above... }查询一个客户端它存在吗设置了哪些元数据curl https://hydra-admin.getbindu.com/admin/clients/client_id更新一个客户端轮换 secret、更新元数据curl -X PUT https://hydra-admin.getbindu.com/admin/clients/client_id \ -H Content-Type: application/json \ -d { ...full client record with changes... }删除一个客户端小心——会使现有 token 失效curl -X DELETE https://hydra-admin.getbindu.com/admin/clients/client_id内省一个 token调试这个 token 有效吗curl -X POST https://hydra-admin.getbindu.com/admin/oauth2/introspect \ -H Content-Type: application/x-www-form-urlencoded \ -d tokenyour access token生成一个强 secretopenssl rand -base64 32 | tr -d | tr / -_对应的程序化操作都在 bindu/auth/hydra/client.py 中封装好了create_oauth_client、get_oauth_client、update_oauth_client、delete_oauth_client、introspect_token、revoke_token、list_oauth_clients支持limit/offset分页与health_check。注意客户端 ID 中含冒号的 DID 会在请求前做 URL 编码quote(client_id, safe)单元测试见 tests/unit/auth/test_hydra_client.py 与 tests/unit/auth/test_hydra_registration.py。【免费下载链接】BinduBindu: The identity, communication, and payments layer for AI agents.项目地址: https://gitcode.com/gh_mirrors/bin/Bindu创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考