overtrue / laravel-qcloud-federation-token
QCloud COS FederationToken generator for Laravel.
Fund package maintenance!
overtrue
Installs: 4 491
Dependents: 0
Suggesters: 0
Security: 0
Stars: 16
Watchers: 3
Forks: 2
Open Issues: 0
Requires
- laravel/framework: ^9.0|^10.0|^11.0
- tencentcloud/tencentcloud-sdk-php: ^3.0
Requires (Dev)
- brainmaestro/composer-git-hooks: dev-master
- jetbrains/phpstorm-attributes: ^1.0
- laravel/pint: ^1.5
- mockery/mockery: ^1.2
- orchestra/testbench: ^8.0
- phpunit/phpunit: ^10.0
README
Laravel 腾讯云联合身份临时访问凭证 生成器,主要用于下发腾讯云联合身份临时访问凭证,比如前端直传等场景。
开始之前,请您仔细阅读并理解一下官方文档:
安装
$ composer require overtrue/laravel-qcloud-federation-token -vvv
配置
你可以通过以下命令将配置文件写入 config/federation-token.php
:
$ php artisan vendor:publish --provider="Overtrue\\LaravelQCloudFederationToken\\QCloudFederationTokenServiceProvider"
config/federation-token.php
return [ // 默认配置,strategies 下的每一个策略将合并此基础配置 'default' => [ 'secret_id' => env('QCLOUD_COS_SECRET_ID', ''), 'secret_key' => env('QCLOUD_COS_SECRET_KEY', ''), 'region' => env('QCLOUD_COS_REGION', 'ap-guangzhou'), "effect" => "allow", // 全局变量,会被替换到所有策略中 'variables' => [ 'uid' => env('QCLOUD_COS_APP_ID'), 'region' => env('QCLOUD_COS_REGION', 'ap-guangzhou'), //... ], ], // strategies 'strategies' => [ 'cos' => [ // 策略名称,可选 'name' => 'cos-put', // 临时凭证过期时间 'expires_in' => 1800, // 将与默认配置合并 'variables' => [ 'appid' => env('QCLOUD_COS_APP_ID'), 'bucket' => env('QCLOUD_COS_BUCKET', ''), //... ], // Statement 请参考:https://cloud.tencent.com/document/product/598/10603 "statements" => [ [ "action" => [ "cos:PutObject", "cos:GetObject", ], "resource" => [ "qcs::cos:ap-beijing:uid/<appid>:<bucket>-<appid>/<date>/<uuid>/*", ], ] ], ], ], ];
配置语法请参考:https://cloud.tencent.com/document/product/598/10603
你可以根据使用场景配置多个策略,然后按策略分发访问凭证。
Warning
注意:
condition
中使用cos:content-type
记得 urlencode, 不然遇到带+号的 MIME 将会失效,比如image/svg+xml
。
安全提醒
临时 token 规则配置不合理,可能会造成安全问题,请谨慎配置,请严格检查如下:
- 配置前请仔细阅读:《用于前端直传 COS 的临时密钥安全指引》
- 凭证生命周期不要设置过长。
- 避免使用主账号来生成凭证,专用的限制登录的 API 子账号。
- 按照《条件键说明及使用示例》 添加请求限制如上传大小和类型等。
- 将账号权限控制在尽量小的范围内,避免越权操作。
变量替换
在配置中难免会用到各种上下文变量或者一些动态 resouce 路径等,你可以在配置中指定 variables
变量来实现变量替换,例如:
仅 principal 和 resource 中的变量可以替换,其他变量不支持替换。
// config/federation-token.php <?php return [ // 默认配置,strategies 下的每一个策略将合并此基础配置 'default' => [ 'secret_id' => env('QCLOUD_COS_SECRET_ID'), 'secret_key' => env('QCLOUD_COS_SECRET_KEY'), 'region' => env('QCLOUD_COS_REGION', 'ap-guangzhou'), "effect" => "allow", // 全局变量,会被替换到所有策略中 'variables' => [ 'region' => env('QCLOUD_COS_REGION', 'ap-guangzhou'), //... ], ], // strategies 'strategies' => [ // 请参考:https://cloud.tencent.com/document/product/598/10603 'cos' => [ // 将与默认配置合并 'variables' => [ 'appid' => env('QCLOUD_COS_APP_ID'), 'bucket' => env('QCLOUD_COS_BUCKET'), //... ], "statements" => [ [ "action" => [ "cos:PutObject", "cos:GetObject", ], "resource" => [ "qcs::cos:ap-beijing:uid/<appid>:<bucket>-<appid>/<date>/<uuid>/*", ], ] ], ], ], ];
以上配置将会生成如下结果:
{ "effect": "allow", "action": [ "cos:PutObject", "cos:GetObject", ], "resource": [ "qcs::cos:ap-beijing:uid/12278900:example-12278900/20220202/bbeae9bb-d650-46f9-aab3-f4171a1bfdea/*" ] }
内置变量如下
<uuid>
- UUID 例如:ca007813-4a49-4d5a-afab-abae18a969a5
<timestamp>
- 当前时间戳,例如:1654485526
<random>
- 随机字符串,16 位,例如:Bbq6gkXXIPyCDsEL
<random:32>
- 随机字符串,32 位,例如:FykbMqi6GT6JHiyv6E2xqUeo3CZLPjo7
<date>
- 日期,例如:20220606
<Ymd>
- 日期,例如:20220606
<YmdHis>
- 日期时间(年月日时分秒),例如:20220606031846
<Y>
- 年,例如:2022
<m>
- 月,例如:06
<d>
- 日,例如:06
<H>
- 时,例如:03
<i>
- 分,例如:18
<s>
- 秒,例如:46
使用
use Overtrue\LaravelQCloudFederationToken\FederationToken; // 使用默认策略(配置项 strategies 中第一个) $token = FederationToken::createToken(); // 或者指定策略 $token = FederationToken::strategy('cos')->createToken(); $token->toArray(); // 'credentials' => [ // 'token' => 'kTRtHpOSOCUzTVWmzlPKweHffXjT9Izo7b61a142d6b56d31c0a7ace4d22bcff3zpbsXKTIrCo43dRRh7bDIKE1ZOE1KRYHEm0KNLjWG_aSF63YoQWchg', // 'tmp_secret_id' => 'AKIDw7dwZbmFSup9CnAOraJ7skiPMybaV3WPP5B4oVMCIL5kLyphV_3IyAHFJ5QMCjE6', // 'tmp_secret_key' => '/lvEo280/AlGt4orjDl9tWLIOMl5nkexS5Pg+xys7ps=', // ], // 'expired_at' => 1547696355,
如果你需要获取生成 token 的配置信息,你可以使用 getStatements
方法:
$token->getStatements();
格式请参考: https://cloud.tencent.com/document/product/1312/48195
字符限制问题
对于单次策略请求,官方限制策略总字符数为 1000 字符,稍微复杂一点就会超过这个限制,建议做法:
- 在控制台配置策略,写法一样,也有可视化配置界面,不限制字符数
- 在 API 侧配置简单的基础策略
请求时将会产生交集结果,所以二者结合,既保证了安全,也避免了 API 断字符限制问题。
事件
❤️ 赞助我
如果你喜欢我的项目并想支持它,点击这里 ❤️
贡献代码
你可以通过以下方式参与贡献:
- 通过 issue tracker 提交 Bug;
- 通过 issue tracker 回答问题或修复 Bug;
- 通过 Pull Request 增加新特性或优化文档。
代码贡献过程不需要很正式。你只需要确保你遵循 PSR-0、PSR-1 和 PSR-2 的编码准则。任何新的代码贡献都必须附带对应的单元测试。
Project supported by JetBrains
Many thanks to Jetbrains for kindly providing a license for me to work on this and other open-source projects.
PHP 扩展包开发
想知道如何从零开始构建 PHP 扩展包?
请关注我的实战课程,我会在此课程中分享一些扩展开发经验 —— 《PHP 扩展包实战教程 - 从入门到发布》
License
MIT