本教程详细介绍了如何使用php和google admin sdk通过服务账户（service account）和域范围授权（domain-wide delegation）来获取特定用户所属的google群组列表。文章涵盖了客户端配置、权限设置、oauth流程以及如何正确进行用户模拟，以解决常见的`unauthorized_client`错误，确保api调用的成功。
在Google Workspace环境中，通过编程方式管理用户和群组是常见的需求。本教程将指导您如何使用PHP客户端库和Google Admin SDK来列出特定用户所属的所有Google群组。我们将重点讲解如何正确配置服务账户和域范围授权，以克服常见的认证和授权问题。
1. 环境准备与API配置
在开始编写PHP代码之前，您需要完成以下准备工作：
-
Google Cloud项目设置：
- 在Google Cloud Console中创建一个新项目或选择一个现有项目。
- 导航到“API和服务” > “库”，搜索并启用 Admin SDK API。
-
创建服务账户并生成JSON密钥文件：
- 在Google Cloud Console中，导航到“IAM和管理” > “服务账户”。
- 创建一个新的服务账户，并为其分配适当的角色，例如“项目” > “查看者”或更细粒度的角色（尽管Admin SDK的权限主要通过域范围授权控制）。
- 为该服务账户创建一个新的JSON密钥，并下载到您的项目目录中。此文件将用于您的PHP应用程序进行认证。
-
配置域范围授权（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 (读取用户资料)
- 点击“授权”。这一步至关重要，它允许您的服务账户模拟域内的用户执行这些操作。
-
PHP项目依赖：
- 通过Composer安装Google API客户端库：
composer require google/apiclient
- 通过Composer安装Google API客户端库：
2. PHP客户端初始化与认证流程
本节将分步介绍如何在PHP中初始化Google客户端，并执行两阶段认证：首先通过OAuth2获取当前登录用户的基本信息，然后切换到服务账户模拟该用户来执行Admin SDK操作。
2.1 用户OAuth2认证获取基本信息
首先，我们需要让用户通过OAuth2登录，以获取他们的邮箱地址。这个邮箱地址稍后将用于服务账户模拟。
立即学习“PHP免费学习笔记（深入）”；
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 "
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 "
"; 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交互。
