如何获取永不过期的Google Refresh Token？Node+Gmail API场景

获取长期有效Refresh Token的正确操作 #

• 选对OAuth客户端类型：创建OAuth 2.0客户端时，选择「桌面应用」或「其他」类型。Web应用类型的refresh token会自动轮换，无法长期保留；而桌面/其他类型的refresh token默认仅在6个月未使用或用户撤销权限时才会过期。
• 授权请求必须携带access_type=offline参数：使用Node的google-auth-library时，配置示例如下：

  const {OAuth2Client} = require('google-auth-library');
  const oAuth2Client = new OAuth2Client(
    YOUR_CLIENT_ID,
    YOUR_CLIENT_SECRET,
    YOUR_REDIRECT_URI
  );
  // 生成授权URL时指定离线访问
  const authUrl = oAuth2Client.generateAuthUrl({
    access_type: 'offline', // 关键参数，必须添加
    scope: ['https://www.googleapis.com/auth/gmail.send'], // 按需设置权限范围
  });
  

• 妥善存储首次授权返回的refresh token：后续若再次发起授权且权限范围变更，旧的refresh token会被作废，需及时替换为新的token。

排查Refresh Token频繁过期的原因 #

• 确认用户是否主动撤销了应用权限：用户可在Google账号「安全」-「第三方应用访问」中查看并撤销权限，一旦撤销，对应refresh token立即失效。
• 检查token是否长期闲置：Google会自动回收超过6个月未使用的refresh token，需确保定期用它刷新access token。
• 避免重复授权覆盖旧token：每次用户授权后，若返回新的refresh token，务必更新存储的版本，旧token会立即失效。

替代方案：服务账号模式 #

如果你的应用操作的是Google Workspace（原G Suite）账号，推荐使用服务账号：

• 创建服务账号并启用「域范围委派」，让服务账号拥有指定Workspace账号的Gmail API访问权限。
• Node中直接通过服务账号密钥文件获取令牌，无需用户授权，也不存在refresh token过期问题，示例代码：

  const {google} = require('googleapis');
  const auth = new google.auth.GoogleAuth({
    keyFile: 'service-account-key.json', // 你的服务账号密钥文件路径
    scopes: ['https://www.googleapis.com/auth/gmail.send'],
    subject: 'user@your-domain.com', // 要操作的Workspace账号邮箱
  });
  const gmail = google.gmail({version: 'v1', auth});
  

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