合并Google OAuth2应用后域用户Refresh Token每日失效问题排查

背景 #

我们有一款SaaS应用，通过OAuth2凭证读取用户Google表格、文档并发送邮件。此前维护两个已验证OAuth应用，权限范围完全一致（均获批敏感受限权限）：

• App1：用于Google Workspace Marketplace插件
• App2：用于Web应用

最初因Web应用需要插件未包含的额外权限，为避免重新提交App1审批的风险，创建了App2。该方案在Web应用beta阶段运行良好，近期两款应用权限范围统一后，决定合并为App1，统一用于插件和Web应用授权，简化维护与审批流程。

合并前工作流程 #

1. Web应用授权（App2）
   • 用户通过app.ourdomain.com访问Web应用
   • OAuth流程使用App2的Client ID和Secret获取凭证
2. 插件授权（App1）
   • 用户从Google Workspace Marketplace安装应用后，关联的Apps Script项目使用App1的Client ID和Secret授权必要的Apps Script权限范围
   • 插件侧边栏打开（嵌入Web应用）后，用户需再次通过App2授权Sheets、Docs和邮件权限范围
3. 凭证存储
   • 无论用户从何处授权，数据库存储的访问文件/发邮件凭证均由App2生成

该方案稳定运行多年无问题。

近期变更 #

为简化维护，停用App2，所有授权（插件+Web应用）统一使用App1完成。因App1与App2权限范围一致，预期过渡顺畅。

当前问题 #

合并为单一App1后（现有凭证均为App1生成），部分域用户出现凭证每日失效的情况：

• 受影响用户授权成功无警告，但凭证在24小时内被自动撤销
• 仅域用户受影响，自有/测试域用户无此问题
• 主要影响包含以下权限范围的凭证：

  [    
      'https://www.googleapis.com/auth/gmail.addons.execute',
      'https://www.googleapis.com/auth/script.container.ui',
      'https://www.googleapis.com/auth/script.external_request'
  ]
  

• 通过Web应用直接重新授权（不预先通过插件授权）可临时解决，但操作繁琐；含上述权限的域用户凭证似乎固定在24小时后过期
• 并非所有域都受影响，例如测试域即使包含受影响权限范围仍正常运行

另外，App1的项目检查页面存在警告（截图：），是否与此相关？

排查方向建议 #

1. 域级OAuth应用设置核查

   • 联系受影响域的管理员，检查Google Workspace管理控制台中App1的授权设置：确认是否开启了"会话时长限制"或"自动撤销未使用权限"的策略，部分域管理员可能针对Marketplace插件类应用设置了每日自动撤销规则
   • 核查域内是否存在针对script.*或gmail.addons.*类权限的特殊安全策略，这类权限属于Apps Script专属范围，可能触发域内的自动清理机制

2. App1的权限范围关联验证

   • 检查App1在Google Cloud Console中的已获批权限范围列表，确认是否存在权限范围的"类型标记"差异：比如gmail.addons.execute是否被标记为"插件专属权限"，而Web应用使用该权限时会被Google的安全系统判定为异常，从而触发每日撤销
   • 对比App1和原App2的权限范围配置细节（包括权限的申请理由、使用场景描述），原App2的权限描述可能更偏向Web应用，而App1的描述偏向插件，导致域内安全策略的判定逻辑不同

3. 授权流程的权限合并逻辑

   • 核查合并后的授权流程：当用户先通过插件授权App1的Apps Script权限，再通过Web应用授权同个App1的文件/邮件权限时，是否出现了权限范围叠加的情况？部分域的安全系统可能对同时包含插件专属权限和Web应用权限的凭证进行特殊限制
   • 测试两种授权路径的凭证有效期：仅通过插件授权、仅通过Web应用授权、先插件后Web应用授权，对比三种情况下的凭证过期时间，定位触发撤销的流程节点

4. Google Cloud Console警告的关联分析

   • 针对App1项目检查页面的警告（截图所示），逐一核实警告内容：比如是否存在"权限范围与应用类型不匹配"、"未完成的安全验证步骤"等问题，这类警告可能导致Google对App1的凭证颁发做了临时限制，仅影响域用户（因为域用户受Workspace管理员策略+Google全局策略双重约束）

5. 凭证撤销日志排查

   • 引导受影响域的管理员查看Google Workspace管理控制台中的OAuth令牌撤销日志，定位凭证被撤销的触发方（是Google系统自动撤销，还是域管理员策略触发），以及撤销的具体原因描述
   • 在Google Cloud Console的App1项目中，查看OAuth consent screen的审核日志，是否有针对域用户凭证的异常标记

内容的提问来源于stack exchange，提问作者Mauricio