README

概述

Google Auth SDK 是由 GitLab IT 工程团队创建的用于 Laravel 内部应用程序的开放源代码 Composer 包，用于生成使用 Google JSON 凭据的 API 令牌，这些令牌可用于在相关 gitlab-it/google-* SDK 包中使用 REST API 端点。

免责声明：这不是由 GitLab 或 Google 产品和开发团队维护的官方包。这是我们 GitLab IT 部门使用的一个内部工具，我们现在将其开源，作为我们公司价值观的一部分。

请在自己的风险下使用，并为我们遇到的任何错误创建合并请求。

我们不会维护社区功能请求路线图，但我们邀请您做出贡献，并且我们很乐意审查您的合并请求。

v2 到 v3 升级指南

3.0 版本有多个重大更改。有关更多信息，请参阅 v3.0 更新日志。

更改内容

• 3.0 版本不添加任何新功能，重点在于命名空间的重大更改。
• glamstack/google-auth-sdk 已弃用，并重命名为 gitlab-it/google-auth-sdk。
• 命名空间从 Glamstack\GoogleAuth 更改为 GitlabIt\GoogleAuth。
• 从修改版的 Calendar Versioning (CalVer) 更改为使用 Semantic Versioning (SemVer)。
• 许可证从 Apache 2.0 更改为 MIT。

迁移步骤

此包作为依赖项包含在 gitlab-it/google-* SDK 包中。只有当 glamstack/google-auth-sdk 存在于您的 composer.json 文件中时，这些步骤才是必要的。否则，只需将 gitlab-it/google-* SDK 包更新到 ^3.0。

1. 从 composer.json 中删除 glamstack/google-auth-sdk 并添加 "gitlab-it/google-auth-sdk": "^3.0"，然后运行 composer update。
2. 在代码库中对 Glamstack\GoogleAuth 进行查找和替换为 GitlabIt\GoogleAuth。

维护者

工作原理

此包用于使用 Google 服务帐户 JSON API 密钥 进行 Google OAuth2 服务器认证。

OAUTH 服务将返回一个 短期 API 令牌，可用于使用 Laravel HTTP 客户端 执行 GET、POST、PATCH、DELETE 等操作。API 请求，可在 Google API 查询器 文档中找到。

为了提供流畅的开发者体验，此 SDK 将接受指向 JSON API 密钥存储路径的 file_path 参数，或者您可以在 json_key 参数中提供 JSON API 密钥作为字符串。

此 SDK 不使用任何 .env 文件或配置文件，而应将这些配置在调用此 SDK 的应用程序中。

SDK 初始化

api_scopes

如果请求的 API 范围未配置在 Google 账户中，则认证将失败。

您可以通过参考特定REST端点的Google API Explorer文档来了解所需的授权范围。

// Option 1
$google_auth = new \Gitlabit\GoogleAuth\AuthClient([
    // ...
    'api_scopes' => ['https://www.googleapis.com/auth/admin.directory.user'],
]);

// Option 2
$api_scopes = [
    https://www.googleapis.com/auth/cloud-platform
    https://www.googleapis.com/auth/cloudplatformprojects
];

$google_auth = new \Gitlabit\GoogleAuth\AuthClient([
    // ...
    'api_scopes' => $api_scopes,
]);

文件路径

您可以选择提供字符串形式的文件路径或json_key。

$google_auth = new \Gitlabit\GoogleAuth\AuthClient([
    // ...
    'file_path' => storage_path('keys/google_json_api_key.json'),
]);

json_key

您可以选择提供字符串形式的文件路径或json_key。

安全警告：您绝不应将服务帐户密钥作为变量提交到源代码中，以避免泄露您GCP组织或项目的凭证。

// Get service account from your model (`GoogleServiceAccount` is an example)
$service_account = \App\Models\GoogleServiceAccount::where('id', '123456')->firstOrFail();

// Get JSON key string from database column that has an encrypted value
$json_key_string = decrypt($service_account->json_key);

$google_auth = new \Gitlabit\GoogleAuth\AuthClient([
    // ...
    'json_key' => $json_key_string,
]);

主题邮箱

这是一个可选键。

这仅用于Google Workspace API和其他使用域范围委派的服务。如果您仅使用SDK进行Google Cloud API服务，则在初始化期间不需要包含此变量。

默认情况下，将使用client_email字段作为主题邮箱。但是，如果您正在使用此SDK对需要域范围委派的任何Google端点进行身份验证，则必须在初始化期间添加subject_email键。

此电子邮件地址是Google Workspace中用户帐户的电子邮件地址，该帐户包含将使用API的适当管理权限。在开发或测试应用程序时，这可以是开发人员或测试帐户的电子邮件地址。

在生产环境中，这应该是您作为Google Workspace用户创建的具有权限范围到您的应用程序提供的自动化的机器人服务帐户的电子邮件地址。

$google_auth = new \Gitlabit\GoogleAuth\AuthClient([
    // ...
    'subject_email' => 'klibby@example.com'
]);

内联使用

// Initialize the SDK using a JSON API key file
$google_auth = new \Gitlabit\GoogleAuth\AuthClient([
    'api_scopes' => ['https://www.googleapis.com/auth/admin.directory.user'],
    'file_path' => storage_path('keys/google_json_api_key.json'),
]);

// Send Auth Request to get JWT token
$api_token = $google_auth->authenticate();

// Perform API Request using short-lived JWT token
// https://developers.google.com/admin-sdk/directory/reference/rest/v1/users/get
$user_key = 'klibby@example.com';
$response = Http::withToken($api_token)
    ->get('https://admin.googleapis.com/admin/directory/v1/users/' . $user_key);

return $response->object;

类方法

上述示例显示了适合大多数用例的基本内联使用。如果您更喜欢使用类和构造函数，下面的示例将提供有用的示例。

<?php

use Gitlabit\GoogleAuth\AuthClient;

class GoogleWorkspaceUserService
{
    protected $auth_token;

    public function __construct()
    {
        $google_auth = new \Gitlabit\GoogleAuth\AuthClient([
            'api_scopes' => ['https://www.googleapis.com/auth/admin.directory.user'],
            'file_path' => storage_path('keys/google_json_api_key.json'),
        ]);
        $this->auth_token = $google_auth->authenticate();
    }

    public function getUser($user_key)
    {
        $response = Http::withToken($this->auth_token)
            ->get('https://admin.googleapis.com/admin/directory/v1/users/' . $user_key);

        return $response->object();
    }
}

安装

要求

添加Composer包

仍在使用glamstack/google-auth-sdk（v2.x）？请参阅v3.0升级指南以获取升级到gitlab-it/google-auth-sdk:^3.0的说明。

composer require gitlab-it/google-auth-sdk:^3.0

如果您正在为此包做出贡献，请参阅CONTRIBUTING.md以获取配置本地Composer包的说明。

相关SDK包

此SDK提供身份验证，以便可以使用Laravel HTTP客户端与Google API Explorer中可以找到的任何端点。

我们已创建了额外的包，这些包为GitLab IT使用的某些常用服务端点提供了定义良好的方法，如果您不想自己指定端点。

• google-workspace-sdk
• google-cloud-sdk

日志配置

此包不会处理任何日志配置。相反，它将抛出带有适用错误消息的异常。这些异常的日志应由调用应用程序处理。

安全最佳实践

Google API范围

包默认加载的配置文件显示了API范围配置的示例。请确保遵循最小权限原则。所有Google范围都可以在此处找到。

您可以通过参考特定REST端点的Google API Explorer文档来了解所需的授权范围。

JSON密钥存储

请勿将您的JSON密钥文件存储在任何不在.gitignore文件中包含的位置。这是为了避免将您的凭据提交到您的存储库（秘密泄露）。

建议将每个JSON API密钥的副本存储在您首选的密码管理器（例如1Password、LastPass等）和/或密钥库（例如HashiCorp Vault、Ansible等）中。

异常

以下是预期异常的列表。

缺少必需的数组参数

Symfony\Component\OptionsResolver\Exception\MissingOptionsException : The required option "api_scopes" is missing.

未设置JSON API密钥参数

Exception : You must specify either the file_path or json_key in the connection_config array.

无效的JSON API密钥

Exception : Google SDK Authentication Error. Invalid JWT Signature.

无效或不匹配的API作用域

Exception : Invalid OAuth scope or ID token audience provided.

测试

此SDK具有单元测试和功能测试。所有单元测试都可以直接运行，而功能测试则需要将两个密钥加载到tests/Storage/keys/目录中。

功能测试密钥名称

1. integration_test_key.json
   • 这应该是一个有效的JSON密钥
   • 用于验证authenticate函数将返回一个适当的Google API OAuth令牌
2. incorrect_key.json
   • 这不应该是一个有效的JSON密钥
   • 用于验证authenticate函数将抛出一个适当的异常信息

问题跟踪和错误报告

免责声明：这不是由 GitLab 或 Google 产品和开发团队维护的官方包。这是我们 GitLab IT 部门使用的一个内部工具，我们现在将其开源，作为我们公司价值观的一部分。

请在自己的风险下使用，并为我们遇到的任何错误创建合并请求。

我们不会维护社区功能请求路线图，但我们邀请您做出贡献，并且我们很乐意审查您的合并请求。

对于GitLab团队成员，请在gitlab-it/google-auth-sdk（公开）或gitlab-com/it/dev/issue-tracker（机密）中创建问题。

贡献

有关如何贡献的更多信息，请参阅CONTRIBUTING.md。