Google API PHP，服务帐户模拟问题

Google API PHP 服务帐户模拟问题解析

基础概念

Google API 服务帐户模拟是指使用一个服务帐户来代表另一个用户（通常是域管理员）执行操作的技术。这在企业环境中很常见，当需要以某个用户的身份批量执行操作时使用。

常见问题及解决方案

问题1：权限不足错误

错误表现：

Google_Service_Exception: Not Authorized to access this resource/api

原因：

服务帐户未被授予足够的域范围授权
域范围授权未正确设置
模拟的用户没有访问资源的权限

解决方案：

确保在Google Admin控制台中为服务帐户授予正确的域范围授权
确保模拟的用户确实拥有访问目标资源的权限
检查服务帐户的权限范围

$client = new Google_Client();
$client->setAuthConfig('service-account.json');
$client->setScopes([Google_Service_Directory::ADMIN_DIRECTORY_USER]);
$client->setSubject('admin@yourdomain.com'); // 设置要模拟的用户

问题2：模拟失败

错误表现：

Google_Service_Exception: Delegation denied for [service account email]

原因：

服务帐户未被授予模拟特定用户的权限
域范围授权未包含必要的API权限

解决方案：

在Google Admin控制台中，为服务帐户添加"服务帐户令牌创建者"角色
确保服务帐户有权限模拟目标用户

问题3：令牌过期

错误表现：

Google_Service_Exception: Invalid Credentials

原因：

JWT令牌已过期（默认1小时有效期）
系统时间与服务端不同步

解决方案：

实现令牌刷新机制
确保服务器时间准确

// 自动刷新令牌的示例
$client = new Google_Client();
$client->setAuthConfig('service-account.json');
$client->setScopes([Google_Service_Directory::ADMIN_DIRECTORY_USER]);
$client->setSubject('admin@yourdomain.com');
$client->setAccessType('offline'); // 允许刷新令牌

// 检查令牌是否过期
if ($client->isAccessTokenExpired()) {
    $client->fetchAccessTokenWithAssertion();
}

最佳实践

最小权限原则：只授予服务帐户必要的权限
日志记录：记录所有模拟操作以便审计
错误处理：实现健壮的错误处理机制
令牌管理：妥善管理JWT令牌，避免泄露

完整示例代码

require_once 'vendor/autoload.php';

try {
    $client = new Google_Client();
    $client->setAuthConfig('service-account.json');
    $client->setScopes([
        Google_Service_Directory::ADMIN_DIRECTORY_USER,
        Google_Service_Directory::ADMIN_DIRECTORY_GROUP
    ]);
    $client->setSubject('admin@yourdomain.com');
    
    // 设置访问类型为离线，允许刷新令牌
    $client->setAccessType('offline');
    
    // 检查令牌是否过期
    if ($client->isAccessTokenExpired()) {
        $client->fetchAccessTokenWithAssertion();
    }
    
    // 使用Directory API
    $service = new Google_Service_Directory($client);
    
    // 示例：获取用户列表
    $users = $service->users->listUsers([
        'domain' => 'yourdomain.com',
        'maxResults' => 10
    ]);
    
    foreach ($users->getUsers() as $user) {
        echo $user->getPrimaryEmail() . "\n";
    }
    
} catch (Google_Service_Exception $e) {
    echo "Google Service Exception: " . $e->getMessage();
    // 可以记录更详细的错误信息
    // error_log(json_encode($e->getErrors()));
    
} catch (Exception $e) {
    echo "General Exception: " . $e->getMessage();
}