ADK 本地授权码认证全栈演示：authn-adk-all-in-one 实战指南

ADK 本地授权码认证全栈演示authn-adk-all-in-one 实战指南【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本篇指南围绕 ADKAgent Development Kit中auth-code授权码grant type 认证机制完整讲解如何在本地零外部依赖地搭建一套IDP 受保护后端 API ADK Agent三件套演示环境用户通过 Agent 询问酒店信息时Agent 自动触发 OAuth 授权码流程将用户导向 IDP 登录授权再用换取到的 Access Token 调用受保护 API。读完本文你将掌握 ADK 中 OpenAPI Tool 与 OIDC 认证的接入方式、本地 IDP 的搭建与密钥配置以及 Agent、IDP、后端三进程联调的全过程。背景Agent 为什么需要按用户认证在实际生产环境中Agent 调用的 OpenAPI 工具和 MCP 工具往往使用某种系统身份system identity访问后端服务。这种做法的安全隐患很明显多个终端用户共享同一个身份意味着任何一个用户都能以该身份访问后端中所有用户的数据。ADK 提供了多种[认证机制]本文以源码为证详见下文各组件分析来解决这一问题其核心思路是把谁来调用 API从共享的系统身份下沉为发起请求的具体终端用户——通过 OAuth/OIDC 授权码流程为每位用户换取专属的 Access Token再以该 Token 访问受保护资源。不过要真正验证这套机制通常需要 IDP、后端服务、Agent 等多个组件协同工作。本示例目录 contributing/samples/integrations/authn-adk-all-in-one 一次性提供了运行认证演示所需的全部组件一个 IDP本地身份提供方基于 Flask 实现的 OIDC Provider一个酒店预订应用后端受 JWT 保护的 REST API一个酒店助手 ADK Agent通过 OpenAPI Tool 访问酒店预订应用总体架构三个组件、三条链路整个演示的组件拓扑如下图中 User、IDP、Hotel Agent、Hotel Booker API 四者之间的编号链路对应下文认证流程中的各步骤从仓库目录结构可以看出三个组件的代码归属组件目录技术栈默认端口IDPidpFlask PyJWT5000酒店预订后端hotel_booker_appFlask SQLite PyJWT8081ADK Agentadk_agentsgoogle-adk OpenAPI Toolset8000adk web授权码认证流程从提问到拿数据的 8 个步骤以用户让 Agent 帮忙查找纽约的酒店为例完整的授权码Auth Code流程如下用户提问用户向 Agent 发起请求要求查找 New York 的酒店Agent 判定需要鉴权Agent 根据 LLM 的响应判断需要调用某个工具且该工具需要认证重定向到 IDPAgent 将用户重定向到 IDP 的登录页携带回跳到 ADK UI 的 callback/redirect URL用户登录授权用户输入凭据演示账号john.doe/password123并同意授权consent回传授权码IDP 将auth_code通过重定向送回第 3 步指定的 redirect URL换取 Access TokenADK 用该auth_code向 IDP 的 token endpoint 换取 Access Token调用受保护 APIADK 携带 Access Token 调用酒店 API 获取酒店数据将结果交给 LLM 格式化回复用户ADK 将最终答复返回给用户。这套流程与标准 OAuth 2.0 Authorization Code 授权码模式一致关键差异在于整个流程由 Agent 在对话过程中自动编排——用户无需感知底层换 Token 细节只看到跳转登录 → 授权 → 回到对话拿到结果。从源码看 IDP 端如何支撑该流程IDP 的实现在 idp/app.py 中通过一个标准 OIDC Provider 的角色支撑上述流程OIDC Discovery/.well-known/openid-configuration端点返回OPENID_CONFIGapp.py 中 OPENID_CONFIG 定义声明了authorization_endpointhttp://localhost:5000/authorize、token_endpointhttp://localhost:5000/generate-token、jwks_uri、支持的grant_types含authorization_code以及code_challenge_methods_supported: [S256]即支持 PKCE授权端点/authorize校验client_id与redirect_uri是否在客户端注册表中然后渲染登录页与 consent 授权页模板见 idp/templates签发授权码consent 通过后对于response_typecodeIDP 生成一次性auth_code存入内存AUTHORIZATION_CODES5 分钟过期并携带code与state重定向回redirect_uriapp.py 授权码签发逻辑Token 端点/generate-token校验 client 凭据支持Authorization: Basic头或表单方式、校验授权码与redirect_uri一致性、过期时间并实现了PKCE 的 S256 code challenge 校验app.py 中 generate_token随后签发 RS256 签名的 Access Token 与 ID Token有效期 1 小时演示账号USER_REGISTRY内置了john.doe和jane.doe两个用户密码均为password123客户端注册表CLIENT_REGISTRY中注册了客户端abc123client_secret为secret123其redirect_uri白名单中包含了 ADK Web UI 的回调地址http://localhost:8000/dev-ui/——这正是 ADK 认证回调的关键配置管理端点IDP 还提供了/admin管理门户及/admin/add-user、/admin/add-client、/admin/update-config等接口可在运行时动态增删用户、客户端或修改 OIDC 配置。从源码看后端如何校验 Token酒店预订后端 hotel_booker_app/main.py 是所有受保护 API 的守门员OIDC 自动发现通过OIDC_CONFIG_URL默认http://localhost:5000/.well-known/openid-configuration拉取并缓存 OIDC 配置再从jwks_uri拉取并缓存 JWKSget_oidc_config / get_jwksJWT 校验is_token_valid使用kid从 JWKS 中定位公钥通过jwt.decode校验签名、isshttp://localhost:5000、audhttp://localhost:8081与expis_token_valid。源码注释中还点明更严格的实现应校验被调用 API 是否属于 audience 覆盖范围如localhost:8081/api应覆盖localhost:8081/api/hotels但不覆盖localhost:8000/admin本演示因 audience 固定为localhost:8081而省略了该检查路由保护token_required装饰器要求每个受保护路由的Authorization头携带BearerToken否则返回 401token_required。/hotels、/book、/booking_details三个路由均被保护业务数据核心业务逻辑在 hotelbooker_core.py 中启动时自动创建 SQLite 库并灌入 4 家示例酒店Grand Hyatt、The Plaza Hotel、Hilton Chicago、Marriott Marquis与 2 条初始预订记录。从源码看 Agent 如何接入 OIDCAgent 的定义在 adk_agents/agent_openapi_tools/agent.py核心是把 OpenAPI 工具集与 OIDC 认证方案绑定调用 ADK 提供的openid_url_to_scheme_credential实现在 src/google/adk/tools/openapi_tool/auth/auth_helpers.py传入 IDP 的 discovery URLhttp://localhost:5000/.well-known/openid-configuration与client_id/client_secret即可从 OpenID URL 自动拉取配置构造出OpenIdConnectWithConfig认证方案与AuthCredential用OpenAPIToolset解析 openapi.yaml其中/hotels、/book、/booking_details均声明了BearerAuth安全要求并将auth_scheme、auth_credential注入工具集使所有 API 调用自动携带用户级凭据最终通过LlmAgent组装为hotel_agent其指令为帮助用户查找和预订酒店、查询预订记录model从环境变量GOOGLE_MODEL读取。也就是说从 Agent 视角看工具声明、认证方案、客户端凭据三者都在 agent.py 中显式绑定ADK 会在调用工具前自动完成授权码换取 Token 的整套流程。环境准备与依赖安装整个演示完全本地运行前置条件仅需 Python 3 与网络拉取 pip 依赖、调用 Google Gemini 模型。依赖清单见 requirements.txtgoogle-adk2.6.0、Flask、flask-cors、python-dotenv、PyJWT含 crypto 扩展、requestsAgent 子目录另有独立的 adk_agents/requirements.txt仅google-adk2.6.0。按以下步骤创建并激活虚拟环境# 进入仓库根目录假设已 clone 到本地 cd adk-python # 进入 all-in-one 认证示例目录 cd contributing/samples/integrations/authn-adk-all-in-one/ python3 -m venv .venv . .venv/bin/activate pip install -r requirements.txt后续启动 IDP、后端、Agent 的三个终端窗口都应激活同一个.venv环境。配置并启动 IDP生成密钥与 JWKSIDP 需要一对 RSA 密钥私钥用于给 Token 签名RS256公钥的 JWKS 形式用于让依赖方后端、ADK验签。整个演示用到的就是公钥分发、私钥本地保存的非对称机制。注意文档建议在 Google Cloud Shell 等隔离环境中执行下述密钥生成与公钥提取命令第 1-3、5 步避免私钥散落在不安全的本地环境。cd idp # 创建 .env 文件复制示例并准备 jwks.json cp sample.env .env cp sample.jwks.json jwks.json # 1. 生成密钥对提示输入 passphrase 时直接回车空 passphrase ssh-keygen -t rsa -b 2048 -m PEM -f private_key.pem # 2. 提取公钥 openssl rsa -in private_key.pem -pubout pubkey.pub # 3. 使用 JWKS 在线生成工具基于第 2 步的公钥生成 JWKS 内容 # 选择密钥算法 RS256、Key use 为 Signature # 4. 将第 3 步生成的 JWKS 密钥写入 jwks.json # 注意保留原有数组结构将新 key 追加进 keys 数组 # 5. 将私钥转为单行文本 cat private_key.pem | tr -d \n # 6. 仔细复制上一条命令的输出更新 .env 中的 PRIVATE_KEY 值 # 7. 保存 jwks.json 与 .env.env中需要确认的关键变量模板见 idp/sample.env变量说明GENERATE_JWT是否签发 JWT默认true设为false时 IDP 返回随机十六进制串代替 JWT仅用于调试PRIVATE_KEY单行 RSA 私钥PEM 内容去掉换行。当GENERATE_JWTtrue时必须设置否则 app.py 会直接抛出 ValueErrorjwks.json中需要包含与私钥配对的公钥 JWKS含kid、kty、n、e等字段IDP 签发 JWT 时会取JWKS[keys][0][kid]写入 Token 头generate_jwt这样验证方才能按kid找到对应公钥。JWKS 生成与jwks.json更新后的效果可参考官方截图密钥与配置就绪后启动 IDPpython app.pyIDP 默认监听http://localhost:5000。可通过http://localhost:5000/.well-known/openid-configuration验证 OIDC Discovery 是否正常返回通过http://localhost:5000/admin打开管理门户查看/修改 OIDC 配置、用户与客户端注册表。启动后端 API酒店预订应用另开一个终端启动受 JWT 保护的酒店预订后端# 进入仓库根目录 cd adk-python # 进入 all-in-one 认证示例目录 cd contributing/samples/integrations/authn-adk-all-in-one/ # 激活虚拟环境 . .venv/bin/activate cd hotel_booker_app/ # 启动酒店预订应用 python main.py后端默认监听http://localhost:8081app.run(debugTrue, port8081)首次启动会自动初始化 SQLite 数据库data.db并写入示例酒店数据。它会在运行时通过 OIDC Discovery 自动发现 IDP 并拉取 JWKS因此务必保证 IDP 已先行启动。启动 ADK Agent再开一个终端启动 ADK Agent# 进入仓库根目录 cd adk-python # 进入 all-in-one 认证示例目录 cd contributing/samples/integrations/authn-adk-all-in-one/ # 激活虚拟环境 . .venv/bin/activate cd adk_agents/ cp sample.env .env # ⚠️ 务必在 .env 中填写真实的 GOOGLE_API_KEY # 运行 Agent adk webAgent 的 .env 配置模板 中需要关注以下变量变量说明GOOGLE_API_KEY必须替换为真实 API Key模板默认NOT_SETAgent 的 LLM 调用依赖它GOOGLE_MODEL使用的模型默认gemini-flash-latestGOOGLE_GENAI_USE_ENTERPRISE是否使用企业版 GenAI 端点默认FalseOAUTH_CLIENT_ID需与 IDP 客户端注册表中的client_id一致默认abc123OAUTH_CLIENT_SECRET需与 IDP 客户端注册表中的client_secret一致默认secret123启动成功后打开浏览器访问http://localhost:8000即可进入 ADK Web UI 与 Agent 对话。注意首次完成认证后Agent 的首次响应可能较慢涉及 OAuth 流程与 Token 缓存初始化后续响应会明显更快。端到端验证在对话中触发完整授权码流程在 ADK Web UI 中向hotel_agent提问例如帮我查一下纽约有哪些酒店与 README 演示场景一致Agent 判定需要调用/hotels工具且该工具需要认证浏览器被重定向到 IDP 登录页http://localhost:5000/authorize?...输入john.doe/password123并同意授权IDP 校验客户端abc123的redirect_uri白名单其中包含http://localhost:8000/dev-ui/签发一次性授权码并回跳 ADK UIADK 用授权码向 IDP 的/generate-token换取 Access Token这一步在 auth_helpers.py 构造的 OAuth2 凭据驱动下完成ADK 携带Authorization: Bearer token调用后端/hotels?locationNew York后端通过 JWKS 校验 Token 后返回酒店列表LLM 将结果格式化为自然语言回复用户。该流程同时验证了四件事Agent 侧的工具鉴权编排、IDP 侧的授权码签发与 Token 签发、后端侧的 JWT 验签、以及 OpenAPI 声明openapi.yaml 中/hotels、/book、/booking_details均标记BearerAuth安全要求与实际调用链路的闭合。故障排查与注意事项IDP 启动报 PRIVATE_KEY 缺失检查idp/.env中PRIVATE_KEY是否为单行PEM 私钥用cat private_key.pem | tr -d \n生成且GENERATE_JWT未被误设为false授权回调 400确认 IDP 客户端注册表中的redirect_uri白名单包含http://localhost:8000/dev-ui/且 Agent 侧OAUTH_CLIENT_ID/OAUTH_CLIENT_SECRET与注册表一致后端 401确认 IDP 已先于后端启动后端启动时才拉取并缓存 JWKS确认jwks.json中的公钥与.env中的私钥配对Agent 无响应确认GOOGLE_API_KEY已替换、GOOGLE_MODEL可达端口占用三个组件分别占用 5000、8081、8000注意保持独立。结论本示例将 ADK 的授权码认证链路完整落地在本地无需任何外部 IDP 服务或云资源仅靠仓库内三份代码idp、hotel_booker_app、adk_agents即可完整体验用户级身份 → Agent 自动编排 OAuth → 受保护 API的认证闭环。这套模式可以直接迁移到真实场景将本地 IDP 替换为 Okta、Auth0 等生产级身份服务将后端替换为真实业务 APIAgent 侧仅需保持openid_url_to_scheme_credentialOpenAPIToolset的接入方式不变即可获得同样的按用户鉴权能力。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考