PHP Symfony项目中Gmail API服务端认证的凭证选择与报错问题

背景 #

在Symfony项目中开发操作Gmail账户邮件的服务，参考官方文档后仍有困惑，已编写src/Service/Gmail.php代码如下：

<?php

namespace App\Service;

use Google\Client;


class Gmail
{
    private \Google\Service\Gmail $api;


    private function getGoogleClient(): Client
    {
        $credentialsPath = getenv('GOOGLE_APPLICATION_CREDENTIALS');
        if (empty($credentialsPath)) {
            throw new \Exception('You need to set env var GOOGLE_APPLICATION_CREDENTIALS');
        }

        if (!file_exists($credentialsPath)) {
            throw new \Exception('Credentials file path ' . getenv('GOOGLE_APPLICATION_CREDENTIALS') . ' set in GOOGLE_APPLICATION_CREDENTIALS does not exist');
        }

        $client = new Client();
        $client->useApplicationDefaultCredentials();
        return $client;
    }

    private function getApi(): \Google\Service\Gmail
    {
        if (!isset($this->api)) {
            $this->api = new \Google\Service\Gmail($this->getGoogleClient());
        }

        return $this->api;
    }

    public function getUserMessages($userId): \Google\Service\Gmail\ListMessagesResponse
    {
        return $this->getApi()->users_messages->listUsersMessages($userId);
    }
}

已完成以下步骤：

• 创建新项目
• 启用Gmail API
• 创建Web应用服务端凭证

疑问 #

不清楚该选择OAuth client ID还是Service account类型的凭证？如果选OAuth client ID，是否需要选择「Web application」应用类型并配置服务端URL？还是应该选Service account？

遇到的错误 #

使用Service account时触发401未授权错误：

In REST.php line 134:
                                                                                                                                                                                        
  {                                                                                                                                                                                      
    "error": {                                                                                                                                                                           
      "code": 401,                                                                                                                                                                       
      "message": "Request is missing required authentication credential. Expected OAuth 2 access token, login cookie or other valid authentication credential. See https://developers.  
  google.com/identity/sign-in/web/devconsole-project.",                                                                                                                                 
      "errors": [                                                                                                                                                                        
        {                                                                                                                                                                                
          "message": "Login Required.",                                                                                                                                                 
          "domain": "global",                                                                                                                                                            
          "reason": "required",                                                                                                                                                          
          "location": "Authorization",                                                                                                                                                   
          "locationType": "header"                                                                                                                                                       
        }                                                                                                                                                                                
      ],                                                                                                                                                                                 
      "status": "UNAUTHENTICATED",                                                                                                                                                       
      "details": [                                                                                                                                                                       
        {                                                                                                                                                                                
          "@type": "type.googleapis.com/google.rpc.ErrorInfo",                                                                                                                           
          "reason": "CREDENTIALS_MISSING",                                                                                                                                               
          "domain": "googleapis.com",                                                                                                                                                    
          "metadata": {                                                                                                                                                                  
            "service": "gmail.googleapis.com",                                                                                                                                           
            "method": "caribou.api.proto.MailboxService.ListMessages"                                                                                                                    
          }                                                                                                                                                                              
        }                                                                                                                                                                                
      ]                                                                                                                                                                                  
    }                                                                                                                                                                                    
  }

解答 #

凭证类型选择 #

• OAuth client ID（Web应用类型）：如果需要操作普通个人Gmail账户，或需要用户主动授权访问其邮件数据，必须选这个。配置时要指定服务端的回调URL，用于接收授权码换取访问令牌。
• Service account：仅适用于Google Workspace（原G Suite）企业账户，且需要在Workspace管理员后台为服务账号开启域范围授权，允许服务账号模拟域内用户访问Gmail。个人Gmail账户完全无法使用Service account。

401错误原因及修复 #

你当前用Service account报错的原因分两种情况：

1. 若使用个人Gmail账户：Service account不支持访问个人Gmail，必须切换到OAuth client ID方案。
2. 若使用Workspace账户：未配置域范围授权，且代码中未指定要模拟的用户邮箱。需：
   • 在Workspace admin控制台为服务账号添加Gmail API的授权范围（比如https://www.googleapis.com/auth/gmail.readonly）
   • 修改代码，在创建Client后添加以下代码指定模拟用户：

     $client->setSubject('user@your-domain.com'); // 替换为域内实际用户邮箱
     

OAuth client ID方案代码调整 #

如果切换到OAuth client ID，需要修改Google Client的初始化逻辑，实现完整授权流程：

1. 设置客户端ID、客户端密钥、重定向URL：

   $client = new Client();
   $client->setClientId(getenv('GOOGLE_CLIENT_ID'));
   $client->setClientSecret(getenv('GOOGLE_CLIENT_SECRET'));
   $client->setRedirectUri(getenv('GOOGLE_REDIRECT_URI'));
   $client->addScope(\Google\Service\Gmail::GMAIL_READONLY); // 根据需求调整权限范围
   

2. 实现授权流程：
   • 生成授权URL引导用户登录授权
   • 用回调收到的授权码换取访问令牌和刷新令牌
   • 存储刷新令牌，后续请求用刷新令牌获取新的访问令牌

内容的提问来源于stack exchange，提问作者Thomas V