Google OAuth2用refresh_token刷新access_token失败但原access_token有效

常见触发原因 #

• Google Cloud OAuth 客户端处于测试发布状态
  如果你的OAuth客户端还处于「测试」状态，只有在控制台「OAuth 同意屏幕」页面手动添加的测试用户，才可以长期使用refresh_token，未被添加的用户虽然可以完成授权、拿到短期有效的access_token，但refresh_token会被系统限制使用，调用刷新接口就会返回unauthorized_client错误。
• Google Workspace 账号管理员限制离线访问权限
  出现问题的账号如果是企业/组织的Workspace账号，管理员可能在后台设置了禁止第三方应用获取离线访问权限，即便用户完成了授权，refresh_token也会被判定为无效。
• 两次请求的客户端凭证不匹配
  如果你获取初始token和刷新token时使用的client_id、client_secret不属于同一个OAuth客户端，或者第一次授权用的是移动端/桌面端类型的客户端、刷新时用了Web端类型的客户端凭证，也会触发该错误。
• refresh_token 传参格式错误
  如果请求时refresh_token包含的特殊字符被错误转义、或者存在前后空格，也会触发该错误。
• 用户账号安全设置拦截
  部分个人账号开启了高级保护计划，或者设置了禁止未经验证的第三方应用访问账号数据，也会导致refresh_token被限制使用。
• 应用未完成Google OAuth敏感权限验证
  Gmail接口属于敏感权限范畴，如果你的应用没有完成Google官方的OAuth权限验证，未被加入测试列表的用户的refresh_token会被自动限制，仅首次返回的access_token可用。

对应解决方法 #

• 确认OAuth客户端的发布状态：如果需要面向所有用户开放，在「OAuth 同意屏幕」页面将应用从测试状态修改为正式发布状态，若涉及敏感权限需要按Google要求完成合规验证。
• 针对Workspace账号报错的情况，引导企业管理员在Workspace后台将你的应用加入允许列表，同时开放离线访问权限。
• 核对获取初始token和刷新token两次请求的client_id、client_secret完全一致，且属于同一个同类型的OAuth客户端。
• 检查refresh_token的传参和授权接口返回的内容完全一致，没有额外空格、不存在特殊字符被错误转义的问题。
• 针对个人账号安全设置拦截的情况，引导用户检查账号的第三方应用访问权限设置，调整后重新授权。
• 确认第一次授权请求时确实添加了access_type=offline参数，保证返回的refresh_token是合法有效的。

注：如果调整后仍然报错，可以先在Google Cloud控制台的OAuth 2.0 Playground中，使用对应问题账号的refresh_token、相同的client_id和client_secret发起刷新请求，排查是否是请求参数格式问题。

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