Haystack OAuth 集成指南：用 OAuthTokenResolver 在 Pipeline 中运行时解析访问令牌

Haystack OAuth 集成指南用 OAuthTokenResolver 在 Pipeline 中运行时解析访问令牌【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本指南基于 Haystack 仓库中 OAuth 集成 API 参考文档完整讲解OAuthTokenResolver组件及其三种可插拔 token source 的设计与用法。你将学会如何在 Haystack Pipeline 运行时自动解析并注入访问令牌、如何为单身份refresh grant、多用户token exchange与长寿命静态令牌选择正确的 source以及如何将解析出的access_token接入 SharePoint / Google Drive 检索器与抓取器构建“仅需 query 即可运行”的 RAG 检索链路。一、为什么需要 OAuthTokenResolver在 Haystack 生态中检索 SharePoint、OneDrive、Google Drive 等 SaaS 内容时下游组件例如MSSharePointRetriever、GoogleDriveFetcher都要求传入一个委托delegatedOAuth 访问令牌。直接在业务代码里反复刷新令牌、处理过期与旋转逻辑会让 Pipeline 的编排变得臃肿。OAuthTokenResolver的定位是在 Pipeline 运行时解析一个 OAuth 访问令牌并在access_token输出 socket 上发出它。下游组件通过普通连接消费该令牌完全不需要关心它是如何解析出来的——令牌的刷新、缓存、过期缓冲、多用户交换全部被封装在可插拔的 token source 中。从 组件文档 可以看到其典型位置“在 Pipeline 起始处把access_token喂给下游组件如MSSharePointRetriever或GoogleDriveRetriever”。这正是其设计目的把鉴权从业务 Pipeline 中剥离出来作为一个独立的、可替换的“源节点”。1.1 薄封装 可插拔 source 的设计OAuthTokenResolver本身是一个薄封装真正获取令牌的工作全部委托给可插拔的token source。你通过token_source参数注入具体策略从而在不改动 Pipeline 其余部分的前提下切换鉴权方式refresh grant、按请求 token exchange、静态长寿命令牌。OAuthTokenResolver的构造函数签名见 参考文档__init__(token_source: TokenSource | SubjectTokenSource) - Nonetoken_source解析访问令牌的策略。如果该 source 设置了requires_subject_token True例如OAuthTokenExchangeSourceresolver 会声明一个必填的subject_token运行输入否则 resolver 不声明任何运行输入。若token_source未实现 token-source 协议抛出OAuthConfigError。1.2 运行输入随 source 类型而变化resolver 的run输入完全取决于所配置的 source配置型 sourceOAuthRefreshTokenSource、OAuthStaticTokenSourcerequires_subject_token False不声明任何运行输入resolver 充当源节点source node。需按请求凭据的 sourceOAuthTokenExchangeSourcerequires_subject_token Trueresolver 声明一个必填的subject_token输入——这是一个由应用/控制器按请求注入的凭据例如传入的用户断言不是由最终用户选择的值。run(**kwargs) - dict[str, str]返回一个仅含access_token键的字典值为 bearer 令牌字符串若 source 要求subject_token但缺失或为空抛出OAuthConfigError。同步版本为run异步对应版本为run_async签名与返回一致。二、三种可插拔 Token Source 详解所有 source 均可从haystack_integrations.utils.oauth导入。下表整理自 组件文档帮助快速决策Source适用场景每次运行的输入OAuthRefreshTokenSource单个固定身份、持有存储的 refresh token希望由 source 兑换成短期 access token 并缓存无OAuthTokenExchangeSource服务多用户或多副本部署把传入的按请求用户断言兑换为下游令牌无需持久化存储。实现 RFC 8693 令牌交换与 Microsoft on-behalf-of 流程subject_tokenOAuthStaticTokenSource提供商签发不过期令牌且在带外管理例如 Slack 或 Notion无2.1 TokenSource 与 SubjectTokenSource 协议haystack_integrations.utils.oauth.protocols定义了两个协议见 参考文档TokenSourceProtocol无按请求输入的配置型 source。由构造时凭据固定的 source 实现OAuthRefreshTokenSource、OAuthStaticTokenSource类属性requires_subject_token False因此OAuthTokenResolver将其作为源节点运行。接口包括resolve() - str、resolve_async() - str、to_dict()、from_dict(data)。SubjectTokenSourceProtocol通过交换按请求的 subject token 来解析访问令牌的 source。由OAuthTokenExchangeSource实现类属性requires_subject_token True使 resolver 声明必填的subject_token运行输入。接口包括resolve(subject_token: str) - str、resolve_async(subject_token: str) - str、to_dict()、from_dict(data)。这套 Protocol 设计意味着你也可以自定义 token source只要实现对应协议含to_dict/from_dict以便序列化就能无缝接入 resolver。2.2 OAuthRefreshTokenSource单身份刷新授权RFC 6749该 source 针对 OAuth 令牌端点运行 RFC 6749refresh-token grant用存储的 refresh token 加上客户端凭据兑换 access token并在进程内缓存到临近过期之前。如果身份提供商在兑换时轮换 refresh token新值会在进程生命周期内保留并通过可选的on_rotate回调暴露便于你持久化。构造函数完整签名见 参考文档__init__( token_url: str, client_id: str, *, refresh_token: Secret Secret.from_env_var(OAUTH_REFRESH_TOKEN), client_secret: Secret | None None, scopes: list[str] | None None, scope_delimiter: str , expiry_buffer_seconds: int DEFAULT_EXPIRY_BUFFER_SECONDS, timeout: float DEFAULT_TIMEOUT_SECONDS, on_rotate: Callable[[str], None] | None None )参数说明参数说明token_urlOAuth 2.0 令牌端点。client_idOAuth 客户端标识。refresh_token用于兑换的 refresh token。默认读取OAUTH_REFRESH_TOKEN环境变量。client_secret机密客户端的客户端密钥公开客户端可省略。scopes要请求的 OAuth 作用域用scope_delimiter连接。作用域的具体取值是提供商相关的需查阅身份提供商的文档。scope_delimiter连接作用域的定界符默认空格部分提供商使用逗号。expiry_buffer_seconds在声明的过期时间前多少秒刷新缓存的 access token默认值DEFAULT_EXPIRY_BUFFER_SECONDS。timeout请求令牌端点的超时秒数默认值DEFAULT_TIMEOUT_SECONDS。on_rotate提供商轮换 refresh token 时被调用的可选回调入参为新值。用于持久化轮换后的令牌source 本身只在进程内保留。配置非法时抛出OAuthConfigError。多副本部署注意事项重要该 source 是单身份的——每个实例一个 refresh token进程内缓存不跨进程共享。在多副本部署中每个副本各自维护缓存对于会轮换签发一次性使用refresh token 的提供商各副本可能相互使彼此的令牌失效。除非通过on_rotate将轮换持久化到共享存储、并由单个 owner 驱动刷新否则副本间会互相破坏令牌。因此单个固定身份、由 refresh grant 支撑 → 选OAuthRefreshTokenSource长寿命、不过期令牌 → 选OAuthStaticTokenSource多副本或多用户后端 → 选OAuthTokenExchangeSource。2.3 OAuthTokenExchangeSource按请求令牌交换RFC 8693 / 微软 OBO该 source 在令牌端点把按请求的 subject token兑换为访问令牌。它实现RFC 8693 令牌交换并且可通过配置实现Microsoft 的 on-behalf-of 流程。与OAuthRefreshTokenSource不同它是无持久化存储的多用户方案按请求的subject_token传入的用户断言本身就是用户身份每次被兑换为新的下游令牌。解析出的令牌按 subject token 缓存在内存中有界、LRU直到临近过期。由于不持久化任何实例状态它也适合多副本部署。提供商差异全部通过配置表达grant_type、subject_token_param例如微软用assertion、scopes、extra_token_params例如{requested_token_use: on_behalf_of}。构造函数完整签名见 参考文档__init__( token_url: str, client_id: str, *, client_secret: Secret | None None, grant_type: str DEFAULT_TOKEN_EXCHANGE_GRANT, subject_token_param: str subject_token, subject_token_type: str | None None, requested_token_type: str | None None, scopes: list[str] | None None, scope_delimiter: str , extra_token_params: dict[str, str] | None None, expiry_buffer_seconds: int DEFAULT_EXPIRY_BUFFER_SECONDS, cache_max_size: int DEFAULT_CACHE_MAX_SIZE, timeout: float DEFAULT_TIMEOUT_SECONDS )关键参数说明参数说明grant_type作为grant_type表单参数发送的授权类型。默认为 RFC 8693 令牌交换授权请设置为提供商期望的值例如微软 on-behalf-of 使用urn:ietf:params:oauth:grant-type:jwt-bearer。subject_token_param承载按请求 subject token 的表单参数名默认subject_tokenRFC 8693。部分提供商期望其他名称如微软的assertion。subject_token_typeRFC 8693 中 supplied subject token 的类型标识作为subject_token_type表单参数发送未设置时省略。RFC 8693 令牌交换必需例如urn:ietf:params:oauth:token-type:access_token微软 on-behalf-of 流程不使用。requested_token_typeRFC 8693 中期望返回的令牌类型标识作为requested_token_type表单参数发送未设置时省略可选。scopes/scope_delimiter要请求的作用域及其连接定界符默认空格仅线格式按 RFC 6749 §3.3 标准化作用域取值仍提供商相关。extra_token_params每次请求中原样包含的额外表单参数例如{requested_token_use: on_behalf_of}。最后应用因此其中的键会覆盖由其他参数推导出的对应表单参数如grant_type、subject_token_type、requested_token_type、scope、client_secret。expiry_buffer_seconds在声明的过期时间前多少秒刷新缓存的 access token。cache_max_size内存缓存中保留的按用户令牌最大数量默认DEFAULT_CACHE_MAX_SIZE缓存满时驱逐最近最少使用LRU的条目。timeout请求令牌端点的超时秒数。2.4 OAuthStaticTokenSource静态长寿命令牌对于签发不过期令牌的提供商例如 Slack、Notion无需刷新流程、令牌带外管理时直接原样返回配置的令牌。构造函数仅一个参数__init__(token: Secret) - Noneresolve()/resolve_async()返回配置的长寿命访问令牌它不接收任何按请求输入。若提供商签发的是必须刷新的短期令牌应改用OAuthRefreshTokenSource。三、错误体系haystack_integrations.utils.oauth.errors定义了三层异常见 参考文档OAuthErrorOAuth 集成抛出的所有错误的基类继承Exception。OAuthConfigError继承OAuthErrorOAuth 组件或 token source 配置错误时抛出。例如token_source未实现协议、subject_token缺失或为空、source 配置非法。TokenRefreshError继承OAuthError令牌无法在身份提供商处解析或刷新时抛出。在异常处理代码中捕获OAuthError即可统一覆盖配置错误与刷新失败两种场景。四、实战三种使用方式4.1 安装pip install oauth-haystack对应的下游集成包microsoft-sharepoint-haystack、google-drive-haystack等可按需单独安装。4.2 独立使用RefreshTokenSource用存储的 refresh token 解析令牌。refresh token 通过 Secret API 从环境变量读取from haystack.utils import Secret from haystack_integrations.components.connectors.oauth import OAuthTokenResolver from haystack_integrations.utils.oauth import OAuthRefreshTokenSource resolver OAuthTokenResolver( token_sourceOAuthRefreshTokenSource( token_urlhttps://login.microsoftonline.com/common/oauth2/v2.0/token, client_idaaa-bbb-ccc, refresh_tokenSecret.from_env_var(MS_REFRESH_TOKEN), scopes[ https://graph.microsoft.com/Files.Read.All, offline_access, ], ), ) access_token resolver.run()[access_token]要点MS_REFRESH_TOKEN环境变量需提前设置scopes必须与下游服务匹配Microsoft Graph 需要如https://graph.microsoft.com/Files.Read.All这样的作用域另可加Sites.Read.AllGoogle Drive 需要如https://www.googleapis.com/auth/drive.readonlyoffline_access用于获取 refresh token是常见追加项。4.3 独立使用StaticTokenSourcefrom haystack.utils import Secret from haystack_integrations.components.connectors.oauth import OAuthTokenResolver from haystack_integrations.utils.oauth import OAuthStaticTokenSource resolver OAuthTokenResolver( token_sourceOAuthStaticTokenSource(tokenSecret.from_env_var(SERVICE_TOKEN)), ) access_token resolver.run()[access_token]4.4 独立使用TokenExchangeSource多用户后端此时 resolver 要求每次运行提供subject_tokenfrom haystack_integrations.components.connectors.oauth import OAuthTokenResolver from haystack_integrations.utils.oauth import OAuthTokenExchangeSource resolver OAuthTokenResolver( token_sourceOAuthTokenExchangeSource( token_urlhttps://login.microsoftonline.com/tenant/oauth2/v2.0/token, client_idaaa-bbb-ccc, subject_token_paramassertion, grant_typeurn:ietf:params:oauth:grant-type:jwt-bearer, scopes[https://graph.microsoft.com/Files.Read.All], extra_token_params{requested_token_use: on_behalf_of}, ), ) # subject_token 是传入的按请求用户断言由你的应用注入。 access_token resolver.run(subject_tokenincoming-user-assertion)[access_token]注意微软 OBO 流程与 RFC 8693 的差异OBO 使用assertion作为 subject token 参数名、urn:ietf:params:oauth:grant-type:jwt-bearer作为授权类型、{requested_token_use: on_behalf_of}作为额外参数且不使用subject_token_type。4.5 放入 PipelineSharePoint 检索示例把 resolver 的access_token输出连接到下游组件的access_token输入。以下示例把 resolver 接入MSSharePointRetriever使运行时只需提供query即可搜索 SharePointfrom haystack import Pipeline from haystack.utils import Secret from haystack_integrations.components.connectors.oauth import OAuthTokenResolver from haystack_integrations.utils.oauth import OAuthRefreshTokenSource from haystack_integrations.components.retrievers.microsoft_sharepoint import ( MSSharePointRetriever, ) pipeline Pipeline() pipeline.add_component( resolver, OAuthTokenResolver( token_sourceOAuthRefreshTokenSource( token_urlhttps://login.microsoftonline.com/common/oauth2/v2.0/token, client_idaaa-bbb-ccc, refresh_tokenSecret.from_env_var(MS_REFRESH_TOKEN), scopes[ https://graph.microsoft.com/Files.Read.All, https://graph.microsoft.com/Sites.Read.All, offline_access, ], ), ), ) pipeline.add_component(retriever, MSSharePointRetriever(top_k5)) pipeline.connect(resolver.access_token, retriever.access_token) result pipeline.run({retriever: {query: quarterly roadmap}}) documents result[retriever][documents]关键点单个access_token输出可以连接到多个下游输入该 Pipeline 的运行时输入只有{retriever: {query: ...}}令牌解析完全自动化若改用OAuthTokenExchangeSource则运行时需额外传入subject_token。五、下游消费方与 SharePoint / Google Drive 集成access_token的典型消费者包括见 MSSharePointRetriever 文档 与相关集成参考文档MSSharePointRetriever通过 Microsoft Search (Graph) API 搜索用户 SharePoint/OneDrive 内容。access_token必须是携带委托Microsoft Graph 权限的 bearer 令牌如Files.Read.All站点与列表范围还需Sites.Read.AllSearch API 仅支持委托权限。运行时输入为queryaccess_token。MSSharePointFetcher通过 Graphshares端点及 Pages API抓取检索结果的完整内容同样以access_token为运行输入参考 Microsoft SharePoint 集成文档。GoogleDriveFetcher通过 Drive API v3 下载文件完整内容。access_token必须携带委托的 Google OAuth 作用域如https://www.googleapis.com/auth/drive.readonly通常从上游OAuthTokenResolver接入参考 Google Drive 集成文档。典型完整链路为OAuthTokenResolver发出access_token→MSSharePointRetriever返回检索文档→MSSharePointFetcher抓取完整内容→ 转换器如PyPDFToDocument、DOCXToDocument、XLSXToDocument、PPTXToDocument前面可接FileTypeRouter。resolver 的单个access_token输出可同时连接 retriever 与 fetcher 的access_token输入。5.1 关于作用域的提醒OAuth 作用域是提供商相关的Microsoft Graph 与 Google Drive 的作用域取值互不相同务必查阅你的身份提供商文档获取准确的作用域值。只有线上传输格式RFC 6749 §3.3才是标准化的。六、序列化to_dict / from_dict所有组件与 source 都实现了to_dict()与from_dict(data)便于 Pipeline YAML 序列化与反序列化OAuthTokenResolver.to_dict() - dict[str, Any]把组件序列化为字典from_dict(data)反序列化若序列化中的token_source类型无法导入则抛出ImportError。各 sourceOAuthRefreshTokenSource、OAuthTokenExchangeSource、OAuthStaticTokenSource同样实现to_dict/from_dict序列化时Secret会以安全方式处理不会把明文凭据写入字典。这意味着你可以把包含 resolver 的 Pipeline 导出为 YAML 配置文件在部署时通过反序列化重建组件——token source 类型与配置参数都会随之恢复。七、选型决策速查场景推荐 source每次运行输入单个固定身份持有 refresh tokenOAuthRefreshTokenSource无长寿命不过期令牌Slack、Notion 等OAuthStaticTokenSource无多用户后端 / 多副本部署需按请求兑换OAuthTokenExchangeSourcesubject_token必填自定义获取令牌逻辑实现TokenSource或SubjectTokenSource协议视协议而定同步与异步所有 source 均提供resolve与resolve_async。OAuthRefreshTokenSource的文档特别提醒一个实例应只在同步或异步模式中二选一使用不要混用。OAuthTokenResolver也提供run与run_async异步 Pipeline 场景下使用run_async即可。安全要点刷新令牌、客户端密钥与静态令牌一律通过Secret建议环境变量注入如OAUTH_REFRESH_TOKEN管理避免明文出现在代码与序列化文件中多副本部署且提供商轮换 refresh token 时务必通过on_rotate把轮换后的令牌持久化到共享存储并由单一 owner 驱动刷新防止副本间互相使令牌失效。延伸阅读组件使用文档OAuthTokenResolver本指南对应的 API 参考OAuth 集成 API下游消费方MSSharePointRetriever、MSSharePointFetcher、GoogleDriveFetcher、Google Drive 集成参考密钥管理Secret API【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考