本教程详细介绍了如何使用php和google admin sdk通过服务账户（service account）和域范围授权（domain-wide delegation）来获取特定用户所属的google群组列表。文章涵盖了客户端配置、权限设置、oauth流程以及如何正确进行用户模拟，以解决常见的`unauthorized_client`错误，确保api调用的成功。

在Google Workspace环境中，通过编程方式管理用户和群组是常见的需求。本教程将指导您如何使用PHP客户端库和Google Admin SDK来列出特定用户所属的所有Google群组。我们将重点讲解如何正确配置服务账户和域范围授权，以克服常见的认证和授权问题。

1. 环境准备与API配置

在开始编写PHP代码之前，您需要完成以下准备工作：

1. Google Cloud项目设置：
   • 在Google Cloud Console中创建一个新项目或选择一个现有项目。
   • 导航到“API和服务” > “库”，搜索并启用 Admin SDK API。
2. 创建服务账户并生成JSON密钥文件：
   • 在Google Cloud Console中，导航到“IAM和管理” > “服务账户”。
   • 创建一个新的服务账户，并为其分配适当的角色，例如“项目” > “查看者”或更细粒度的角色（尽管Admin SDK的权限主要通过域范围授权控制）。
   • 为该服务账户创建一个新的JSON密钥，并下载到您的项目目录中。此文件将用于您的PHP应用程序进行认证。
3. 配置域范围授权（Domain-Wide Delegation）：
   • 在Google Cloud Console中，找到您的服务账户的“唯一ID”（Client ID）。
   • 登录到您的Google Workspace管理控制台（admin.google.com）。
   • 导航到“安全” > “API 控件” > “域范围授权”。
   • 添加一个新的API客户端，将服务账户的Client ID粘贴到“客户端 ID”字段中。
   • 在“OAuth 范围”字段中，添加以下范围（或根据您的具体需求添加更多）：
     • https://www.googleapis.com/auth/admin.directory.group.readonly (读取群组信息)
     • https://www.googleapis.com/auth/userinfo.email (读取用户邮箱)
     • https://www.googleapis.com/auth/userinfo.profile (读取用户资料)
   • 点击“授权”。这一步至关重要，它允许您的服务账户模拟域内的用户执行这些操作。
4. PHP项目依赖：
   • 通过Composer安装Google API客户端库：

     composer require google/apiclient

2. PHP客户端初始化与认证流程

本节将分步介绍如何在PHP中初始化Google客户端，并执行两阶段认证：首先通过OAuth2获取当前登录用户的基本信息，然后切换到服务账户模拟该用户来执行Admin SDK操作。

2.1 用户OAuth2认证获取基本信息

首先，我们需要让用户通过OAuth2登录，以获取他们的邮箱地址。这个邮箱地址稍后将用于服务账户模拟。

setClientId('YOUR_CLIENT_ID.apps.googleusercontent.com');
$client->setClientSecret('YOUR_CLIENT_SECRET');
$client->setRedirectUri('YOUR_REDIRECT_URL'); // 必须与Google Cloud Console中配置的URL一致

$client->setApplicationName("My Google Group Lister");

// 添加获取用户邮箱和资料信息的OAuth范围
$client->addScope("https://www.googleapis.com/auth/userinfo.email");
$client->addScope("https://www.googleapis.com/auth/userinfo.profile");

// 处理OAuth回调
if (isset($_GET['code'])) {
    $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

    if (!isset($token["error"])) {
        $client->setAccessToken($token['access_token']);

        // 获取用户基本信息
        $google_oauth = new Google_Service_Oauth2($client);
        $google_account_info = $google_oauth->userinfo->get();
        $userEmail = $google_account_info->email; // 获取当前登录用户的邮箱

        echo "当前登录用户邮箱: " . $userEmail . "
";

        // ... 接下来将进行服务账户模拟操作
    } else {
        echo "OAuth认证失败: " . $token["error_description"];
    }
} else {
    // 如果没有code参数，则重定向到Google认证页面
    $authUrl = $client->createAuthUrl();
    header('Location: ' . filter_var($authUrl, FILTER_SANITIZE_URL));
    exit();
}
?>

2.2 服务账户模拟用户执行Admin SDK操作

在获取到用户邮箱后，我们将切换到使用服务账户进行认证，并模拟该用户来调用Admin SDK。这是获取群组列表的关键步骤。

setAuthConfig('PATH_TO_YOUR_SERVICE_ACCOUNT_KEY.json');

        // 指定要模拟的用户邮箱。
        // 这个邮箱必须是Google Workspace域内的有效用户，
        // 并且该服务账户已通过域范围授权获得了相应的权限。
        $client->setSubject($userEmail); // 模拟当前登录的用户

        // 添加Admin SDK所需的OAuth范围
        // 注意：这个范围也必须在Google Workspace管理控制台的域范围授权中配置
        $client->addScope("https://www.googleapis.com/auth/admin.directory.group.readonly");

        // ... 接下来将进行获取群组列表的操作
?>

重要提示：

• setAuthConfig() 应该指向您下载的服务账户JSON密钥文件。
• setSubject() 中的邮箱地址是您希望模拟的域内用户的邮箱。在这里，我们使用通过OAuth2认证获取到的当前登录用户的邮箱。
• addScope("https://www.googleapis.com/auth/admin.directory.group.readonly") 必须在域范围授权中被服务账户授权。

3. 获取用户所属群组列表

现在，我们已经正确配置了客户端并进行了认证，可以使用Google_Service_Directory服务来查询用户所属的群组。

 'YOUR_DOMAIN.com', // 替换为您的Google Workspace域名
            'userKey' => $userEmail        // 使用要查询的用户邮箱
        );

        try {
            // 调用Admin SDK的groups->listGroups方法
            $googleGroups = $service->groups->listGroups($optParams);
            $groups = $googleGroups->getGroups();

            if (!empty($groups)) {
                echo "
用户 " . $userEmail . " 所属的群组:
";
                echo "
";
                foreach ($groups as $group) {
                    echo "
" . $group->getEmail() . " (" . $group->getName() . ")
";
                }
                echo "
";
            } else {
                echo "用户 " . $userEmail . " 不属于任何群组。";
            }
        } catch (Google_Service_Exception $e) {
            echo "获取群组时发生错误: " . $e->getMessage();
            // 详细错误信息可能在 $e->getErrors() 中
        }

// ...
?>

4. 完整示例代码

将上述所有部分整合，形成一个完整的PHP脚本：

setClientId('YOUR_CLIENT_ID.apps.googleusercontent.com');
$client->setClientSecret('YOUR_CLIENT_SECRET');
$client->setRedirectUri('YOUR_REDIRECT_URL');
$client->setApplicationName("My Google Group Lister");

// 添加获取用户邮箱和资料信息的OAuth范围
$client->addScope("https://www.googleapis.com/auth/userinfo.email");
$client->addScope("https://www.googleapis.com/auth/userinfo.profile");

$userEmail = null;

if (isset($_GET['code'])) {
    $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

    if (!isset($token["error"])) {
        $client->setAccessToken($token['access_token']);

        // 获取用户基本信息
        $google_oauth = new Google_Service_Oauth2($client);
        $google_account_info = $google_oauth->userinfo->get();
        $userEmail = $google_account_info->email; // 获取当前登录用户的邮箱

        echo "当前登录用户邮箱: " . $userEmail . "
";

        // --- 第二阶段：服务账户模拟用户，执行Admin SDK操作 ---
        // 配置服务账户认证
        // 加载您的服务账户JSON密钥文件路径
        $client->setAuthConfig('PATH_TO_YOUR_SERVICE_ACCOUNT_KEY.json');

        // 指定要模拟的用户邮箱
        $client->setSubject($userEmail); 

        // 添加Admin SDK所需的OAuth范围
        $client->addScope("https://www.googleapis.com/auth/admin.directory.group.readonly");

        // 初始化Directory服务
        $service = new Google_Service_Directory($client);

        // 设置查询参数，列出指定用户所属的群组
        $optParams = array(
            'domain' => 'YOUR_DOMAIN.com', // 替换为您的Google Workspace域名
            'userKey' => $userEmail        // 使用要查询的用户邮箱
        );

        try {
            // 调用Admin SDK的groups->listGroups方法
            $googleGroups = $service->groups->listGroups($optParams);
            $groups = $googleGroups->getGroups();

            if (!empty($groups)) {
                echo "
用户 " . $userEmail . " 所属的群组:
";
                echo "
";
                foreach ($groups as $group) {
                    echo "
" . $group->getEmail() . " (" . $group->getName() . ")
";
                }
                echo "
";
            } else {
                echo "用户 " . $userEmail . " 不属于任何群组。";
            }
        } catch (Google_Service_Exception $e) {
            echo "获取群组时发生错误: " . $e->getMessage() . "
";
            echo "详细错误: " . print_r(json_decode($e->getMessage(), true), true);
        }

    } else {
        echo "OAuth认证失败: " . $token["error_description"];
    }
} else {
    // 如果没有code参数，则重定向到Google认证页面
    $authUrl = $client->createAuthUrl();
    header('Location: ' . filter_var($authUrl, FILTER_SANITIZE_URL));
    exit();
}
?>

请务必将代码中的 YOUR_CLIENT_ID.apps.googleusercontent.com、YOUR_CLIENT_SECRET、YOUR_REDIRECT_URL、PATH_TO_YOUR_SERVICE_ACCOUNT_KEY.json 和 YOUR_DOMAIN.com 替换为您的实际值。

5. 关键注意事项与故障排除

• unauthorized_client 错误：这是最常见的错误，通常意味着：
  • 服务账户权限不足：确保您的服务账户已在Google Workspace管理控制台中通过域范围授权，并添加了所有必要的OAuth范围（例如 https://www.googleapis.com/auth/admin.directory.group.readonly）。
  • OAuth范围不匹配：代码中addScope添加的范围必须与域范围授权中配置的范围完全一致。
  • setAuthConfig 或 setSubject 配置不当：确保JSON密钥文件路径正确，并且setSubject中使用的邮箱是Google Workspace域内的有效用户。
  • API未启用：确保在Google Cloud项目中已启用Admin SDK API。
• 域范围授权的Client ID：在Google Workspace管理控制台中配置域范围授权时，请使用服务账户的唯一ID（通常在服务账户详情页面的“详细信息”标签页中），而不是OAuth 2.0客户端ID。
• 模拟用户：setSubject方法用于指定服务账户要模拟的域内用户。只有通过域范围授权的服务账户才能模拟用户。
• 错误处理：始终使用try-catch块来捕获Google_Service_Exception，以便更好地诊断API调用失败的原因。

总结

通过本教程，您应该已经掌握了如何使用PHP和Google Admin SDK，结合服务账户和域范围授权来获取特定用户所属的Google群组列表。关键在于正确配置Google Cloud项目、服务账户、域范围授权，并在PHP代码中分阶段进行认证：首先通过OAuth2获取用户身份，然后利用服务账户模拟该用户来执行Admin SDK操作。遵循这些步骤将有效避免常见的认证和授权问题，确保您的应用程序能够顺利与Google Workspace API交互。