google-api-nodejs-client 的 @googleapis/oauth2：3 个端点搞定令牌校验与用户信息查询

google-api-nodejs-client 的 googleapis/oauth23 个端点搞定令牌校验与用户信息查询【免费下载链接】google-api-nodejs-clientGoogles officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.项目地址: https://gitcode.com/gh_mirrors/go/google-api-nodejs-clientgoogle-api-nodejs-client里的googleapis/oauth2是一个被标记为废弃、但至今仍在生效的授权辅助模块。它只做一件事帮你校验一张 OAuth2 令牌是否有效并顺手查出当前登录用户的邮箱、姓名等基础资料。对于仍在维护传统授权链路的存量项目这套tokeninfo加userinfo的轻量调用链路比直接解析 JWT 更省心也是本文要讲透的全部内容。什么场景下你还会用到这个模块src/apis/oauth2/目录承载的是 Google OAuth2 API版本v2发现文档 discovery/oauth2-v2.json 里的revision还停在20200213README 也挂着[Deprecated]前缀——官方早已不为它增加新功能。但这不意味着它不能用。两个真实场景仍然会踩到它你手里有一张access_token或id_token想在业务代码里快速判断它是否过期、授权范围够不够不想自己解码、验签你要展示当前用户是谁需要邮箱、姓名、头像这些公开资料而不想引入整套 People API。只要落在这两类需求里googleapis/oauth2仍然是最短路径。最小可用调用3 行代码查一个用户先把能跑起来的最小例子放在前面方便你直接照抄。安装聚合包后用统一入口拿到v2实例再调userinfo.getconst {google} require(googleapis); const oauth2 google.oauth2(v2); const res await oauth2.userinfo.get({}); console.log(res.data); // { email, name, picture, ... }这段在做什么google.oauth2(v2)通过VERSIONS表拿到Oauth2实例userinfo.get({})以 GET 方式请求https://www.googleapis.com/oauth2/v2/userinfo返回体直接落在res.data里。注意它没有任何必填参数——身份完全来自全局绑定的认证客户端下一节讲怎么绑。两种引入方式与包信息除了聚合包googleapis还可以装独立子包它由src/apis/oauth2生成并单独发布npm install googleapis/oauth2独立包与聚合包指向同一份实现二选一即可。从 src/apis/oauth2/package.json 能确认这个子包的关键信息项值包名googleapis/oauth2版本10.0.1入口 / 类型build/index.js/build/index.d.ts运行时依赖仅googleapis-common^9.0.0引擎要求node 22.0.0许可Apache-2.0走聚合包时工厂函数与主包导出是这么接起来的src/apis/oauth2/index.ts 里的oauth2()调用getAPIT(oauth2, versionOrOptions, VERSIONS, this)其中VERSIONS把字符串v2绑定到oauth2_v2.Oauth2类主入口 src/index.ts 再把oauth2_v2从包里导出于是你在代码里能直接写出google.oauth2(v2)。三个端点各管一件事这个模块对外就暴露三处方法都挂在同一个Oauth2实例上tokeninfo校验令牌。POST https://www.googleapis.com/oauth2/v2/tokeninfo用于验证access_token或id_token并回传元信息。oauth2.userinfo.get拉当前用户资料。GET https://www.googleapis.com/oauth2/v2/userinfo。oauth2.userinfo.v2.me.get同一资料的旧端点。GET https://www.googleapis.com/userinfo/v2/me是历史遗留的userinfo/v2/me路径返回结构与上一项完全一致。资源挂载结构决定了调用路径Oauth2构造时先挂userinfo资源Resource$Userinfo内部再级联出v2.me子资源最终拼出userinfo.get与userinfo.v2.me.get两条链。三个方法在 src/apis/oauth2/v2.ts 中都是同一套createAPIRequest骨架差别只在url、method与返回的 Schema。调用前Scope 与全局认证怎么配调userinfo之前必须给认证客户端配好对应 Scope。整个 API 只涉及这三个见发现文档auth.oauth2.scopes与两个userinfo方法的scopes数组Scope作用openid把你与你的个人 Google 信息关联https://www.googleapis.com/auth/userinfo.email查看你的主邮箱地址https://www.googleapis.com/auth/userinfo.profile查看你的个人含已公开的信息配置方式有两种二选一const auth new google.auth.GoogleAuth({ // 可传数组也可传一个空格分隔的字符串 scopes: [ openid, https://www.googleapis.com/auth/userinfo.email, https://www.googleapis.com/auth/userinfo.profile, ], }); const authClient await auth.getClient(); google.options({auth: authClient}); // 绑定全局后续调用自动携带令牌这段在做什么GoogleAuth拿到客户端后用google.options({auth: authClient})做全局绑定之后oauth2的所有请求都自动带上访问令牌无需在每个调用里重复传认证信息。scopes既可写成数组也可写成单个空格分隔字符串这点在源码注释里已明确。调用时标准参数与请求选项无论调哪个方法都会自动支持一组标准参数定义在 v2.ts 的StandardParameters接口与发现文档parameters段对齐auth本请求用的认证客户端或 API Key支持OAuth2Client、JWT、Compute、UserRefreshClient、BaseExternalAccountClient、GoogleAuth及字符串形式alt响应数据格式默认jsonfields部分响应字段选择器只取你要的字段keyAPI Key用于标识项目与计入配额未提供 OAuth 2.0 token 时为必填oauth_token当前用户的 OAuth 2.0 tokenprettyPrint是否返回带缩进换行的响应默认truequotaUser配额统计用的不透明用户标识最长 40 字符userIp已废弃请改用quotaUser。几个容易忽略的点rootUrl默认取options.rootUrl || https://www.googleapis.com/因此你可以在请求选项里覆盖rootUrl把请求打到自己或代理的域名上每个方法都支持 Promise 与 callback 两种风格返回类型分别是PromiseGaxiosResponseWithHTTP2Schema$Userinfo与void传入StreamMethodOptions时方法返回流式响应Readable而非普通对象适合处理大体积返回或做管道转发。tokeninfo的参数只有两个且都不是必填需至少提供其一const res await oauth2.tokeninfo({ access_token: your-access-token, // 校验访问令牌 // id_token: your-id-token, // 或校验 ID 令牌 });服务端根据你传入的令牌类型回传对应信息具体字段见下一节。响应怎么读Tokeninfo 与 Userinfo 字段tokeninfo返回Schema$Tokeninfo字段类型含义audiencestring令牌受众通常与issued_to相同emailstring用户邮箱仅当请求含 email scope 时返回expires_ininteger (int32)令牌剩余有效秒数issued_tostring令牌签发对象通常与audience相同scopestring该令牌被授予的 scope 列表空格分隔user_idstring混淆后的用户 IDverified_emailboolean邮箱是否已验证仅当请求含 email scope 时返回两个userinfo端点返回同一个Schema$Userinfo字段类型含义emailstring用户邮箱family_namestring姓氏given_namestring名字genderstring性别hdstring托管域名如example.comWorkspace 用户才有idstring混淆后的用户 IDlinkstring个人资料页 URLlocalestring偏好语言区域namestring全名picturestring头像 URLverified_emailboolean邮箱是否验证因只返回主邮箱恒为true授权码流程从换令牌到调接口tokeninfo/userinfo本身只是校验与查询而拿到那张贴身的access_token通常靠google.auth.OAuth2客户端驱动。仓库里的 samples/oauth2.js 给出了完整参考核心三步用CLIENT_ID、CLIENT_SECRET、REDIRECT_URI三要素来自 Cloud Console 凭据页构造google.auth.OAuth2客户端并google.options({auth: oauth2Client})做全局绑定generateAuthUrl({access_type: offline, scope: scopes.join( )})生成授权地址在本地启动 HTTP 服务接收回调里的code拿到code后调getToken(code)换令牌把结果写回oauth2Client.credentials此后客户端即可自动带令牌发请求。示例里最终演示的是people.people.get——用它证明授权完成后就能访问其他 Google API正好呼应这个模块为其他 Google API 获取授权许可的定位。授权逻辑本身即上述三步People 调用属于示例演示范畴。弃用状态、引擎要求与现代替代方案上手前先把这几条注意事项记牢官方已弃用README 明确标注[Deprecated]发现文档revision停留在20200213Google 不再为其加新功能。新项目应优先转向 Google Identity 平台的现代方案如直接解析/验证 ID token、或对接更新的 Identity API而不是把googleapis/oauth2当作新的授权地基。运行环境要求抬高src/apis/oauth2/CHANGELOG.md 显示 2026 年起最低 Node 版本提升至22package.json里engines.node已写死 22.0.0。确认你的运行环境达标否则安装/构建会出问题。存量项目可继续用该模块仍随主仓库持续发布与维护tokeninfo与userinfo方法本身不受影响作为传统授权链路的兼容实现保留没有问题。配额与 Keykey参数在没走 OAuth token 时是必填的配合quotaUser做配额归因别再用已废弃的userIp。简言之这是一个老但仍有效的工具——校验令牌、查用户资料这两件事它做得干脆利落但别拿它去搭建全新的授权体系。【免费下载链接】google-api-nodejs-clientGoogles officially supported Node.js client library for accessing Google APIs. Support for authorization and authentication with OAuth 2.0, API Keys and JWT (Service Tokens) is included.项目地址: https://gitcode.com/gh_mirrors/go/google-api-nodejs-client创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考