使用服务账号访问Google用户联系人的权限错误排查

场景概述 #

开发C# Windows应用，通过服务账号实现域范围委派，同步第三方数据源到Google域内用户的邮件列表与联系人。已实现邮件组成员读取功能，但读取/更新用户自定义联系人时遇到权限相关错误。

第一次错误：权限范围不足 #

代码示例 #

credential = await GoogleWebAuthorizationBroker.AuthorizeAsync(
   GoogleClientSecrets.FromStream(stream).Secrets,
   new[] { PeopleServiceService.Scope.DirectoryReadonly, PeopleServiceService.Scope.Contacts },
   "[snip]@email-group-updater.iam.gserviceaccount.com", CancellationToken.None);
var initializer = new BaseClientService.Initializer()
   { HttpClientInitializer = credential, ApplicationName = "UpdateMailGroups" };
var people_service = new PeopleServiceService(initializer);
var pc = people_service.People.Connections.List("people/me");
var x = pc.Execute();

错误信息 #

GoogleApiException: The service people has thrown an exception. HttpStatusCode is Forbidden. Request had insufficient authentication scopes.
Error=Google.Apis.Requests.RequestError
Request had insufficient authentication scopes. [403]
Errors [
Message[Insufficient Permission] Location[ - ] Reason[insufficientPermissions] Domain[global]
]
...（省略完整错误内容）

问题分析 #

1. 授权方式错误：GoogleWebAuthorizationBroker是面向终端用户的OAuth 2.0授权流，不适合服务账号的域范围委派场景，无法正确模拟域内用户获取联系人权限。
2. 权限逻辑问题：服务账号本身无个人联系人数据，必须模拟域内真实用户才能访问其联系人，当前代码未完成正确的用户模拟。

第二次错误：未授权客户端 #

修改后的代码示例 #

var credential = GoogleCredential.FromFile(serviceAccountKeyjsonFile)
   .CreateScoped(new[] { PeopleServiceService.Scope.DirectoryReadonly})
   .CreateWithUser(<user I'm impersonating>);

错误信息 #

Exception: Google.Apis.Auth.OAuth2.Responses.TokenResponseException: Error:"unauthorized_client", Description:"Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.", Uri:""

问题分析 #

1. 缺少联系人权限范围：仅添加了DirectoryReadonly，未包含读取/修改联系人所需的权限。
2. 域范围委派配置不匹配：Admin控制台中服务账号的委派权限未与代码中指定的作用域对应，或未正确启用域范围委派。

正确解决方案 #

1. 配置域范围委派权限 #

在Google Admin控制台完成以下操作：

• 进入「安全」>「API控制」>「域范围委派」
• 添加服务账号的客户端ID，勾选以下权限（根据需求选择）：
  • https://www.googleapis.com/auth/contacts（读写联系人）
  • https://www.googleapis.com/auth/contacts.readonly（只读联系人）
  • https://www.googleapis.com/auth/admin.directory.group.readonly（只读邮件组）

2. 正确的代码实现 #

// 加载服务账号密钥文件
var credential = GoogleCredential.FromFile("service-account-key.json")
    .CreateScoped(new[] { 
        PeopleServiceService.Scope.ContactsReadonly, // 按需替换为Contacts以获得读写权限
        PeopleServiceService.Scope.DirectoryReadonly
    })
    .CreateWithUser("target-user@your-domain.com"); // 替换为域内真实用户邮箱

// 初始化People服务
var serviceInitializer = new BaseClientService.Initializer()
{
    HttpClientInitializer = credential,
    ApplicationName = "UpdateMailGroups"
};
var peopleService = new PeopleServiceService(serviceInitializer);

// 读取联系人（必须指定PersonFields，API要求明确请求字段）
var contactsRequest = peopleService.People.Connections.List("people/me");
contactsRequest.PersonFields = "names,emailAddresses,phoneNumbers"; // 按需指定需要的字段
var contactsResponse = contactsRequest.Execute();

关键注意事项 #

• 必须指定PersonFields：People API要求明确声明需要获取的联系人字段，否则会抛出参数错误。
• 用户模拟有效性：CreateWithUser中的邮箱必须是域内已存在的有效用户，服务账号仅能模拟本域内用户。
• 权限一致性：代码中声明的作用域必须与Admin控制台委派的权限完全匹配，不能遗漏或错配。

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