如何在Google Workspace侧边栏跳转OAuth授权页获取Gmail API凭证？

API 探路者

2026-9-29

核心问题根因

你当前使用的InstalledAppFlow是面向桌面端应用设计的授权流，flow.run_local_server(port=0)方法会在代码运行的服务器本地启动临时HTTP服务等待OAuth回调，而Google Workspace插件的运行环境不支持这种本地回调逻辑，因此会触发HTTP超时报错。同时Google Drive插件的侧边栏属于受限制的iframe容器，不允许直接在iframe内跳转外部OAuth同意屏地址。

适配插件场景的实现方案

第一步：替换授权流
放弃InstalledAppFlow，改用适用于Web服务的AuthorizationCodeFlow，配置时需要提前在Google Cloud控制台的OAuth同意屏配置项中，添加你部署的插件后端的授权回调接口地址作为授权重定向URI。
第二步：生成授权链接并引导跳转
在用户点击条目检测到未授权时，通过flow.authorization_url()方法生成OAuth同意屏链接，将该链接返回给侧边栏前端，调用Google Workspace插件原生的setOpenLink方法打开授权链接，设置为新标签页打开即可避免iframe限制。
示例生成授权链接代码：
```
from google_auth_oauthlib.flow import AuthorizationCodeFlow

flow = AuthorizationCodeFlow.from_client_secrets_file(
    'credentials.json',
    scopes=SCOPES,
    redirect_uri=YOUR_REDIRECT_URI
)
auth_url, state = flow.authorization_url(
    access_type='offline',
    include_granted_scopes='true'
)
```
之后将auth_url返回给前端触发新标签页跳转即可。
第三步：兑换凭证并存储
用户完成授权后，Google会将授权码回调到你配置的重定向URI，在对应的后端接口中用授权码兑换完整的credentials凭证，将凭证和当前用户的Google Workspace账号ID关联存储到数据库/缓存中。
示例兑换凭证代码：
```
flow.fetch_token(authorization_response=request.url)
creds = flow.credentials
# 此处添加将creds序列化后和用户ID关联存储的逻辑
```
第四步：后续调用Gmail API
用户后续再次点击条目时，直接根据用户ID取出存储的credentials，即可直接构建Gmail服务：
```
service = build("gmail", "v1", credentials=creds)
```

注意事项

你需要将用到的Gmail API对应scope同时添加到Google Workspace插件manifest的oauthScopes字段、以及Google Cloud控制台OAuth同意屏的scope列表中，避免授权校验失败。
未发布的测试插件需要将测试用户账号提前添加到OAuth同意屏的测试用户列表中，否则无法正常访问授权页。

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