ASP.NET Core中使用OAuth Token连接Google Gmail客户端的问题

1. 配置Google OIDC以获取长期访问能力 #

要实现后台长期协助用户处理邮件，必须在OIDC配置中添加offline_access范围和Gmail所需的权限（比如https://www.googleapis.com/auth/gmail.modify），这样才能拿到刷新令牌（refresh_token）——这是获取长期访问权限的核心，用于定期刷新短期的access_token。

修改OIDC配置代码：

builder.Services.AddAuthentication()
    .AddGoogleOpenIdConnect(options =>
    {
        options.ClientId = "你的ClientID";
        options.ClientSecret = "你的ClientSecret";
        // 添加Gmail权限和离线访问范围
        options.Scope.Add("https://www.googleapis.com/auth/gmail.modify");
        options.Scope.Add("offline_access");
        
        options.Events.OnTokenValidated = async context =>
        {
            // 从认证上下文提取关键令牌信息
            var accessToken = context.Properties.GetTokenValue("access_token");
            var refreshToken = context.Properties.GetTokenValue("refresh_token");
            var userId = context.Principal.FindFirstValue(ClaimTypes.NameIdentifier);
            
            // 持久化refresh_token到数据库/缓存，供后续后台服务调用
            // 示例：await _tokenStorage.SaveRefreshToken(userId, refreshToken);
            
            // 创建符合Google客户端要求的UserCredential
            var credential = new UserCredential(
                new GoogleAuthorizationCodeFlow(
                    new GoogleAuthorizationCodeFlow.Initializer
                    {
                        ClientSecrets = new ClientSecrets
                        {
                            ClientId = options.ClientId,
                            ClientSecret = options.ClientSecret
                        },
                        Scopes = options.Scope.ToList()
                    }),
                userId,
                new TokenResponse
                {
                    AccessToken = accessToken,
                    RefreshToken = refreshToken,
                    ExpiresInSeconds = long.Parse(context.Properties.GetTokenValue("expires_at")) - DateTimeOffset.UtcNow.ToUnixTimeSeconds()
                });
            
            // 初始化GmailService并测试调用
            var gmailService = new GmailService(new BaseClientService.Initializer
            {
                HttpClientInitializer = credential,
                ApplicationName = "你的应用名称"
            });
            var userProfile = await gmailService.Users.GetProfile("me").ExecuteAsync();
            Console.WriteLine($"当前授权用户邮箱：{userProfile.EmailAddress}");
            
            return Task.CompletedTask;
        };
    });

2. 解决"UnderlyingCredential is not an OIDC token provider"错误 #

这个错误的本质是：Google的BaseClientService不支持直接使用OIDC流程返回的原始令牌，必须用UserCredential这类官方凭据类型包装令牌信息。上面的代码通过UserCredential封装access_token和refresh_token，就能完美适配GmailService的初始化要求。

3. 后台服务长期调用Gmail API的处理逻辑 #

后台服务无法依赖用户在线，所以核心是用持久化的refresh_token自动刷新access_token：

// 后台服务中初始化GmailService的示例方法
public async Task<GmailService> GetGmailService(string userId, string savedRefreshToken)
{
    var flow = new GoogleAuthorizationCodeFlow(new GoogleAuthorizationCodeFlow.Initializer
    {
        ClientSecrets = new ClientSecrets
        {
            ClientId = "你的ClientID",
            ClientSecret = "你的ClientSecret"
        },
        Scopes = new[] { "https://www.googleapis.com/auth/gmail.modify" }
    });
    
    // 用保存的refresh_token创建凭据
    var credential = new UserCredential(flow, userId, new TokenResponse { RefreshToken = savedRefreshToken });
    
    // 自动刷新access_token（若已过期）
    if (await credential.GetAccessTokenForRequestAsync() == null)
    {
        throw new InvalidOperationException("无法刷新访问令牌，请引导用户重新授权");
    }
    
    return new GmailService(new BaseClientService.Initializer
    {
        HttpClientInitializer = credential,
        ApplicationName = "你的应用名称"
    });
}

关键注意事项 #

• 确保Google Cloud控制台中，OAuth客户端已配置正确的重定向URI
• 权限范围按需选择，避免请求不必要的高权限
• refresh_token可能因用户取消授权、令牌过期等原因失效，需处理对应错误并引导用户重新授权

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