本教程详细介绍了如何使用PHP与Google API客户端库，通过服务账户（Service Account）和域级授权（Domain-Wide Delegation）来获取Google Workspace中特定用户所属的群组列表。文章涵盖了Google API项目配置、PHP客户端库的初始化、用户身份验证流程，以及核心的服务账户授权与用户模拟机制，并提供了完整的示例代码与注意事项，旨在帮助开发者解决在集成Google Admin SDK Directory API时遇到的权限问题。
1. 概述与准备工作
在Google Workspace环境中，若要通过编程方式获取组织内用户的群组信息，通常需要具备管理员权限。直接使用用户的OAuth 2.0凭据通常无法完成此类域级管理操作。此时，Google的服务账户（Service Account）结合域级授权（Domain-Wide Delegation）成为最佳实践。通过这种方式，服务账户可以模拟（impersonate）域内的任何用户，执行该用户被授权的操作，甚至执行管理员级别的操作，前提是服务账户本身已被委派了相应的权限。
准备工作：
-
创建Google Cloud项目并启用API：
- 访问Google Cloud Console。
- 创建一个新项目或选择现有项目。
- 在“API和服务”->“库”中搜索并启用 Admin SDK API 和 Google People API (如果需要获取更详细的用户信息)。
-
创建服务账户并生成JSON密钥：
- 在Google Cloud Console中，导航到“IAM和管理”->“服务帐号”。
- 创建一个新的服务账户，并为其分配适当的角色（例如，如果仅用于读取群组，则无需过多权限，但域级授权将覆盖此处的角色）。
- 创建后，点击服务账户，进入“密钥”选项卡，添加新密钥并选择JSON格式。下载此JSON文件，它将用于PHP代码中的身份验证。
-
配置域级授权：
- 登录Google Workspace管理控制台（admin.google.com）。
- 导航到“安全性”->“API 控制”->“域级授权”。
- 点击“添加新”以配置新的客户端ID。
- 客户端ID： 填写您服务账户的唯一ID（可在服务账户详情页找到）。
-
OAuth 范围： 关键步骤。您需要添加服务账户将被授权模拟用户访问的API范围。对于获取用户群组信息，至少需要以下范围：
- https://www.googleapis.com/auth/admin.directory.group.readonly (读取群组信息)
- https://www.googleapis.com/auth/userinfo.email (获取用户电子邮件)
- https://www.googleapis.com/auth/userinfo.profile (获取用户个人资料)
- 点击“授权”。这一步至关重要，它赋予了服务账户模拟域内用户并执行这些范围操作的能力。
2. PHP客户端库安装
使用Composer安装Google API PHP客户端库：
立即学习“PHP免费学习笔记（深入）”；
composer require google/apiclient:^2.0
3. PHP代码实现：获取用户群组列表
以下代码示例展示了如何结合用户OAuth认证和服务账户域级授权来获取当前登录用户的群组列表。
<?php
require_once 'vendor/autoload.php';
// -------------------------------------------------------------------------
// 步骤1: 初始化Google客户端并进行用户OAuth认证，以获取当前登录用户的基本信息
// -------------------------------------------------------------------------
// 创建Google客户端实例
$client = new Google_Client();
// 替换为您的Google Cloud项目凭据
$client->setClientId('YOUR_CLIENT_ID.apps.googleusercontent.com');
$client->setClientSecret('YOUR_CLIENT_SECRET');
// 替换为您的重定向URI，必须与Google Cloud控制台中配置的完全一致
$client->setRedirectUri('YOUR_REDIRECT_URI');
$client->setApplicationName('My Google Workspace App');
// 为用户OAuth认证添加必要的范围
// 这些范围将请求用户授权应用程序访问其电子邮件和个人资料
$client->addScope('https://www.googleapis.com/auth/userinfo.email');
$client->addScope('https://www.googleapis.com/auth/userinfo.profile');
// 检查是否存在授权码，表示用户已从Google认证服务器重定向回来
if (isset($_GET['code'])) {
try {
// 使用授权码获取访问令牌
$token = $client->fetchAccessTokenWithAuthCode($_GET['code']);
// 检查是否存在错误
if (isset($token["error"])) {
echo "Error fetching access token: " . $token["error_description"];
exit();
}
// 设置客户端的访问令牌
$client->setAccessToken($token['access_token']);
// 使用OAuth2服务获取当前登录用户的基本信息
$google_oauth = new Google_Service_Oauth2($client);
$google_account_info = $google_oauth->userinfo->get();
$userEmail = $google_account_info->email;
echo "<h2>当前登录用户: " . htmlspecialchars($userEmail) . "</h2>";
// -------------------------------------------------------------------------
// 步骤2: 重新配置客户端以使用服务账户进行域级授权和用户模拟
// -------------------------------------------------------------------------
// 加载服务账户的JSON密钥文件
// 确保此文件路径正确，且文件安全存储
$client->setAuthConfig('path/to/your-service-account-key.json');
// 设置要模拟的用户邮箱。这里我们模拟当前登录的用户。
// 服务账户必须已通过域级授权，并被授予了对admin.directory.group.readonly范围的权限。
$client->setSubject($userEmail);
// 初始化Directory服务。此时，客户端将使用服务账户的凭据
// 并模拟由setSubject指定的用户来执行Admin SDK操作。
$adminService = new Google_Service_Directory($client);
// -------------------------------------------------------------------------
// 步骤3: 使用Directory服务获取模拟用户所属的群组列表
// -------------------------------------------------------------------------
$optParams = array(
'domain' => 'yourdomain.com', // 替换为您的Google Workspace域名
'userKey' => $userEmail // 指定要查询群组的用户邮箱
);
// 调用listGroups方法获取群组列表
$googleGroups = $adminService->groups->listGroups($optParams);
$groups = $googleGroups->getGroups();
if (!empty($groups)) {
echo "<h3>" . htmlspecialchars($userEmail) . " 所属群组:</h3>";
echo "<ul>";
foreach ($groups as $group) {
echo "<li>" . htmlspecialchars($group->getName()) . " (" . htmlspecialchars($group->getEmail()) . ")</li>";
}
echo "</ul>";
} else {
echo "<p>未找到 " . htmlspecialchars($userEmail) . " 所属的群组。</p>";
}
} catch (Google_Service_Exception $e) {
// 捕获Google API服务异常，通常是权限不足或配置错误
echo "<h3>获取群组时发生错误:</h3>";
echo "<p>错误代码: " . $e->getCode() . "</p>";
echo "<p>错误信息: " . $e->getMessage() . "</p>";
// 可以根据错误信息进一步调试，例如检查域级授权配置
} catch (Exception $e) {
// 捕获其他通用异常
echo "<h3>发生未知错误:</h3>";
echo "<p>" . $e->getMessage() . "</p>";
}
} else {
// 如果没有授权码，则生成授权URL并引导用户进行认证
$authUrl = $client->createAuthUrl();
echo "<p><a href='" . htmlspecialchars($authUrl) . "'>点击此处登录Google并查看您的群组</a></p>";
}
?>4. 注意事项与常见问题
-
服务账户权限是关键：
- unauthorized_client 错误通常表示服务账户本身未被正确授权。请务必在Google Workspace管理控制台为您的服务账户客户端ID授予 https://www.googleapis.com/auth/admin.directory.group.readonly 等必要范围的域级授权。
- 服务账户JSON文件中的 client_email 必须与在Google Workspace中配置域级授权时使用的客户端ID匹配。
-
setSubject() 的作用：
- $client->setSubject('impersonated_user_email'); 指定了服务账户将模拟哪个用户来执行操作
