17370845950

新闻动态
PHP集成Google API：通过服务账户与域级授权获取用户群组信息

本教程详细介绍了如何使用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）域内的任何用户，执行该用户被授权的操作，甚至执行管理员级别的操作，前提是服务账户本身已被委派了相应的权限。

准备工作：

  1. 创建Google Cloud项目并启用API：
    • 访问Google Cloud Console。
    • 创建一个新项目或选择现有项目。
    • 在“API和服务”->“库”中搜索并启用 Admin SDK API 和 Google People API (如果需要获取更详细的用户信息)。
  2. 创建服务账户并生成JSON密钥：
    • 在Google Cloud Console中，导航到“IAM和管理”->“服务帐号”。
    • 创建一个新的服务账户，并为其分配适当的角色（例如，如果仅用于读取群组，则无需过多权限，但域级授权将覆盖此处的角色）。
    • 创建后，点击服务账户，进入“密钥”选项卡，添加新密钥并选择JSON格式。下载此JSON文件，它将用于PHP代码中的身份验证。
  3. 配置域级授权：
    • 登录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客户端库：

composer require google/apiclient:^2.0

3. PHP代码实现：获取用户群组列表

以下代码示例展示了如何结合用户OAuth认证和服务账户域级授权来获取当前登录用户的群组列表。

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 "
当前登录用户: " . htmlspecialchars($userEmail) . "
";

        // -------------------------------------------------------------------------
        // 步骤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 "
" . htmlspecialchars($userEmail) . " 所属群组:
";
            echo "
    ";
            foreach ($groups as $group) {
                echo "
  • " . htmlspecialchars($group->getName()) . " (" . htmlspecialchars($group->getEmail()) . ")
    • ";
            }
            echo "
";
        } else {
            echo "
未找到 " . htmlspecialchars($userEmail) . " 所属的群组。
";
        }

    } catch (Google_Service_Exception $e) {
        // 捕获Google API服务异常，通常是权限不足或配置错误
        echo "
获取群组时发生错误:
";
        echo "
错误代码: " . $e->getCode() . "
";
        echo "
错误信息: " . $e->getMessage() . "
";
        // 可以根据错误信息进一步调试，例如检查域级授权配置
    } catch (Exception $e) {
        // 捕获其他通用异常
        echo "
发生未知错误:
";
        echo "
" . $e->getMessage() . "
";
    }

} else {
    // 如果没有授权码，则生成授权URL并引导用户进行认证
    $authUrl = $client->createAuthUrl();
    echo "
点击此处登录Google并查看您的群组
";
}
?>

4. 注意事项与常见问题

  1. 服务账户权限是关键：
    • unauthorized_client 错误通常表示服务账户本身未被正确授权。请务必在Google Workspace管理控制台为您的服务账户客户端ID授予 https://www.googleapis.com/auth/admin.directory.group.readonly 等必要范围的域级授权。
    • 服务账户JSON文件中的 client_email 必须与在Google Workspace中配置域级授权时使用的客户端ID匹配。
  2. setSubject() 的作用：
    • $client->setSubject('impersonated_user_email'); 指定了服务账户将模拟哪个用户来执行操作
广照天下广告 广照天下广告 广照天下广告策划 广照天下广告策划 广照天下 广照天下 广照天下 广照天下 广照天下 广照天下 广照天下广告策划 广照天下广告策划 广照天下广告策划 广照天下广告策划 南昌市广照天下广告策划有限公司 南昌市广照天下广告策划有限公司 南昌市广照天下广告策划有限公司 南昌市广照天下广告策划有限公司

赣ICP备2024031479号