作者简介
吴硕卫:腾讯云技术支持工程师,现负责腾讯云存储产品的技术支持专项工作。
为了实现权限分离,提供更细颗粒度的权限控制,有效的控制帐号生效周期,本文通过腾讯云 CAM 产品的 STS(临时访问凭证)来实现部署,调试,验证等一系列的操作体验。
主要介绍基于腾讯云对象存储 COS,如何使用 COS 签名工具和 HTTP 请求工具 Postman 来验证临时密钥的有效性,以及如何快速实现一个 Web 端页面的文件直传功能。服务器上只需要生成和管理访问密钥,无需关心细节,文件数据都存放在腾讯云 COS 上。
在前端页面直接向 COS 发起请求,此时数据的上传和下载可以不经过后端服务器,既节约了后端服务器的带宽和负载,还可以充分利用 COS 的带宽和全球加速等能力,提升应用体验。
临时密钥(临时访问凭证) 是通过 CAM 云 API 提供的接口,获取到权限受限的密钥。
COS API 可以使用临时密钥计算签名,用于发起 COS API 请求。
COS API 请求使用临时密钥计算签名时,需要用到获取临时密钥接口返回信息中的三个字段,如下:
Web、iOS、Android 使用 COS 时,通过固定密钥计算签名方式不能有效地控制权限,同时把永久密钥放到客户端代码中有极大的泄露风险。如若通过临时密钥方式,则可以方便、有效地解决权限控制问题。例如,在申请临时密钥过程中,可以通过设置权限策略 policy 字段,限制操作和资源,将权限限制在指定的范围内。
有关 COS API 授权策略,请参见:
https://cloud.tencent.com/document/product/436/31923
整体架构图如下所示:
其中:
(1) 用户客户端向用户的后台服务器请求临时密钥。
(2) 用户的服务器通过 CAM STS 接口请求临时密钥。
(3) CAM 返回临时密钥给用户服务器,该临时密钥有效期最长是 2 小时。
(4) 客户服务器下发临时密钥给客户端。
(5) 客户端获取到临时密钥的信息后,再做签名,携带签名请求上传、下载等操作。
本文测试使用的各个工具版本为:
名称 | 版本 |
---|---|
Node | 14.4.0 |
NPM | 6.14.5 |
Git | 1.8.3.1 |
一、部署临时密钥 STS 服务
COS 针对 STS 提供了 SDK 和样例,目前已有 Java、Nodejs、PHP、Python、Go 等多种语言的样例。具体内容请参见 COS STS SDK(https://github.com/tencentyun/qcloud-cos-sts-sdk)。各个 SDK 的使用说明请参见 Github 上的 README 和样例。
本次实践使用的是 Nodejs 语言。
# 拉取 COS STS SDK 代码:
git clone [https://github.com/tencentyun/qcloud-cos-sts-sdk.git](https://github.com/tencentyun/qcloud-cos-sts-sdk.git)
# 本次使用nodejs环境,进入到nodejs里的demo文件夹
cd qcloud-cos-sts-sdk/nodejs/demo/
# 全局安装express
npm install express-generator -g
# 安装所需要的包模块
npm install body-parser request express
可以直接使用 sts-server.js
或者 sts-server-scope.js
修改配置参数,来搭建密钥服务器。
如下修改sts-server.js
里的密钥等配置文件,其中可以看到 demo 使用的是 Express 框架,还需要修改一下服务器运行的端口,防止跟后续的示例冲突,示例:
var bodyParser = require('body-parser');var STS = require('../index');var express = require('express');
// 配置参数var config = { secretId: 'AKID****************', secretKey: '**********', proxy: '', durationSeconds: 1800,
// 放行判断相关参数 bucket: 'buckettest-1250000000', region: 'ap-guangzhou', allowPrefix: '*', // 这里改成允许的路径前缀,可以根据自己网站的用户登录态判断允许上传的具体路径,例子:a.jpg 或者 a/* 或者 * (使用通配符*存在重大安全风险, 请谨慎评估使用) // 简单上传和分片,需要以下的权限,其他权限列表请看 https://cloud.tencent.com/document/product/436/31923 allowActions: [ // 简单上传 'name/cos:PutObject', 'name/cos:PostObject', // 分片上传 'name/cos:InitiateMultipartUpload', 'name/cos:ListMultipartUploads', 'name/cos:ListParts', 'name/cos:UploadPart', 'name/cos:CompleteMultipartUpload' ],};
// 创建临时密钥服务var app = express();app.use(bodyParser.json());
// 支持跨域访问app.all('*', function (req, res, next) { res.header('Content-Type', 'application/json'); res.header('Access-Control-Allow-Origin', '*'); res.header('Access-Control-Allow-Headers', 'origin,accept,content-type'); if (req.method.toUpperCase() === 'OPTIONS') { res.end(); } else { next(); }});
// 临时密钥接口app.all('/sts', function (req, res, next) {
// TODO 这里根据自己业务需要做好放行判断
// 获取临时密钥 var shortBucketName = config.bucket.substr(0, config.bucket.lastIndexOf('-')); var appId = config.bucket.substr(1 + config.bucket.lastIndexOf('-')); var policy = { 'version': '2.0', 'statement': [{ 'action': config.allowActions, 'effect': 'allow', 'principal': { 'qcs': ['*'] }, 'resource': [ 'qcs::cos:' + config.region + ':uid/' + appId + ':prefix//' + appId + '/' + shortBucketName + '/' + config.allowPrefix, ], }], }; STS.getCredential({ secretId: config.secretId, secretKey: config.secretKey, proxy: config.proxy, durationSeconds: config.durationSeconds, policy: policy, }, function (err, tempKeys) { var result = JSON.stringify(err || tempKeys) || ''; res.send(result); });});app.all('*', function (req, res, next) { res.writeHead(404); res.send({ code: 404, codeDesc: 'PageNotFound', message: '404 page not found' });});
// 启动签名服务app.listen(3333);console.log('app is listening at http://127.0.0.1:3333');
其中/sts
作为导入路由的前缀,是对外提供接口的部分。bucket、region、allowPrefix、allowAction 这几个参数用于设置权限策略 policy 字段,来限定临时密钥所允许访问的资源路径和请求的操作。
由于这里演示的是数据直传,为了测试方便,allowPrefix 这里置为*
,放开整个存储桶的权限,可以根据自己的需要在这里对资源路径进行收缩。允许操作的 Action 默认参数里有 cos:PutObject ,这里可以不做改动。
node sts-server.js# 启动 STS 服务,会看到控制台打印的app is listening at http://127.0.0.1:3333
服务会运行在服务器的 3333 端口,可以在倒数第二行自行修改为其他端口。
在本地浏览器打开 http://ip:port/sts,可以看到云服务器返回的临时密钥信息。
http://42.194.201.209:3333/sts)
二、COS 签名工具
COS 签名工具是腾讯云对象存储为用户提供的 Web 工具,可用于生成请求签名。您可以在工具页面上填入指定的参数,生成请求签名,以及校验请求签名的正确性。
1、基础信息
2、API 密钥
3、HTTP 参数
点击生成签名后,会看到生成类似以下格式的一种签名串。
q-sign-algorithm=sha1&q-ak=QmFzZTY0IGlzIGEgZ2VuZXJp&q-sign-time=1480932292;1481012292&q-key-time=1480932292;1481012292&q-header-list=host&q-url-param-list=versioning&q-signature=43803ef4a4207299d87bb75d1c739c06cc9406bb
签名串中的各个参数描述如下:
名称 | 描述 |
---|---|
q-sign-algorithm | 描述该签名使用的加密方式,目前腾讯云使用的是 HMAC-SHA1 的方式加密签名。 |
该字段请保持默认值:sha1 | |
q-ak | 用于标识用户身份 SecretID 的字段 |
q-sign-time | 签名的有效起止时间,其使用 10 位 Unix 时间戳来表示,有效效力精确到秒。 |
该字段通过分号区分起止,起时在前止时在后。 | |
q-key-time | 可以用户自定义的 SecretKey 有效时间,使用 10 位 Unix 时间戳来表示,有效效力精确到秒。 |
该字段通过分号区分起止,起始时间在前终止时间在后。 | |
一般 q-key-time 的时间范围大于等于 q-sign-time。 | |
q-header-list | 提供密文中包含需要校验的 Headers 列表,必须是小写字符。 |
q-url-param-list | 提供密文中包含需要校验的 Parameters 列表,必须是小写字符。 |
q-signature | 经过 HMAC-SHA1 算法加密的请求校验信息。 |
三、验证临时密钥有效性
COS API 使用临时密钥访问 COS 服务时,通过 x-cos-security-token
字段传递临时 sessionToken
,通过临时 SecretId
和 SecretKey
计算签名。
简单来说,就是使用临时密钥里返回的 TmpSecretId
和 TmpSecretKey
去做签名,签名的结果传入 HTTP 请求头部中的 Authorization
字段。
然后把临时密钥返回的 Token 传入 HTTP 请求头部中的 x-cos-security-token
字段。
验证临时密钥的话官网其实也是有 COS 请求工具的,使用起来也比较方便,勾选使用临时密钥,然后分别填入 tmpsecret id 和 key、token 就可以发起请求了。
这里为了更好的理解这里的工作模式,我们选择使用 Postman 工具做一次 PUT 的请求示例。
访问之前已经部署好的临时密钥 STS 服务 URL 地址:
http://42.194.201.209:3333/sts
返回的临时密钥信息如下
{
"expiredTime": 1592792349,
"expiration": "2020-06-22T02:19:09Z",
"credentials": {
"sessionToken": "mfHiMQfhfPUOF67lopyh9KwkCx0mSumV828468f4042e7bd968906ff80cf77ae7bwh6DeY15XgJ6\_Ddr9HmT7SOs38bO-nN8ih7izzRM1H2KJDDE46goteDHe2W1qD9YIRY34bIWpFT6HIvRyKKHBGCCZ\_SvTvJX\_lRnJU5CCksmsuWlxe5qEzJBvzVmn3GrqZ5-5HaOydNKiuhZKo1PphORN-ViyIFOVYSbkWCG3zR3UGig1FomKOBusLpXLkaYa3b9MuasHsmJs71Rv9jE1gLRjpxi3\_eRA19sFun6nzkDGD3WeuYgqx\_Rf05dOkJAxe2lO6o5t8b5jGUICbdCQThh1b695yw529ffHsR14IHxYMMBuXp\_OShDooOBssD-lZquKBhq9LI4MfWELSHu3qiq\_-JagSWMIT\_CXYmaw6na6U6Tl4syX78XaZCHwoncIOJg-ADiFOxGAF7cEcafPDaiO-Q0dbTuNBQ7Fc2ZlkTTlznhYuj45tlXJ6\_hBwrfCY9RRVUQmoBI8CZJ0\_C1ExUHUf2p9g4gGZ1fX8yqNY",
"tmpSecretId": "AKIDrXn4jL7XfaZ-Tj-Qt5VYPGjtt637\_\_z57hXYV31EtA4gne4n-RD\_D7mspOrMfVI8",
"tmpSecretKey": "ytqC8ZYE7y3ZrUmmKbnZHxB/ZBNc6jEFHMooRisvI8I="
},
"requestId": "fd494be7-0998-462f-9649-baebacaf2f47",
"startTime": 1592790549
}
打开 COS 签名工具,既然演示的是数据直传,那么在这里我们选择以 PUT 的方式传一个文件上去。
签名填的参数如下,SecretId
和 SecretKey
填入刚刚获取到的 tmpSecretId
和 tmpSecretKey
:
打开 Postman,PUT 的请求方式如下,Authorization
字段参数填入刚刚 COS 签名工具生成的签名串,x-cos-security-token
字段参数填入临时密钥返回的 sessionToken
。
点击发送请求,可以看到 COS 服务器返回 200 的状态码,临时密钥验证通过。
四、PUT 直传实践
临时密钥使用的是 Nodejs 的 Express 框架,这里环境为了能跟临时密钥使用的保持一致,也使用 Express 来快速的搭建一个 Web 服务。
创建一个名为 cos-web-test
的项目,使用 Pug 模板库,不使用 CSS 引擎。
首先,进入准备放置项目的目录,然后在命令提示符运行 Express
应用生成器,生成器将创建(并列出)项目的文件:
[root@VM-0-11-centos data]# mkdir cos-web-test[root@VM-0-11-centos data]# cd cos-web-test/[root@VM-0-11-centos cos-web-test]# express --view=pug
create : public/ create : public/javascripts/ create : public/images/ create : public/stylesheets/ create : public/stylesheets/style.css create : routes/ create : routes/index.js create : routes/users.js create : views/ create : views/error.pug create : views/index.pug create : views/layout.pug create : app.js create : package.json create : bin/ create : bin/www install dependencies: $ npm install
run the app: $ DEBUG=cos-web-test:* npm start
安装依赖包并运行该项目:
npm installnpm start
本地浏览器打开
http://42.194.201.209:3000
可以看到如下效果,代表 Express 应用配置成功。
进入存储桶详情页,单击【基础配置】页签。下拉页面找到【跨域访问 CORS 设置】配置项,单击【添加规则】,配置示例如下图,详情请参见设置跨域访问文档。
关于跨域的概念和介绍,这里就不具体展开讲了。引申阅读:跨域的基本概念 https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Access_control_CORS
打开app.js
,在中间添加一行,示例如下,目的为 express.static 中间件函数提供的文件创建虚拟路径前缀 /cos
,为了使用代码在名为 public 的目录中提供的静态资源
app.use('/', indexRouter);app.use('/users', usersRouter);
# 需要添加的行app.use('/cos', express.static('public'));
// catch 404 and forward to error handlerapp.use(function (req, res, next) { next(createError(404));});
打开 Public 目录,新建文件test.html
,示例:
使用 AJAX 上传:AJAX 上传需要浏览器支持基本的 HTML5 特性,当前方案使用 PUT Object 文档,操作指引如下:
<!doctype html><html lang="en"> <head> <meta charset="UTF-8"> <title>Ajax Put 上传</title> <style> h1, h2 { font-weight: normal; } #msg { margin-top: 10px; }</style></head> <body> <h1>Ajax Put 上传</h1> <input id="fileSelector" type="file"> <input id="submitBtn" type="submit"> <div id="msg"></div> <script src="https://unpkg.com/cos-js-sdk-v5/demo/common/cos-auth.min.js"></script> <script> (function () { // 请求用到的参数 var Bucket = 'shuoweiwu-125****742'; var Region = 'ap-guangzhou'; var protocol = location.protocol === 'https:' ? 'https:' : 'http:'; var prefix = protocol + '//' + Bucket + '.cos.' + Region + '.myqcloud.com/'; // 对更多字符编码的 url encode 格式 var camSafeUrlEncode = function (str) { return encodeURIComponent(str) .replace(/!/g, '%21') .replace(/'/g, '%27') .replace(/\(/g, '%28') .replace(/\)/g, '%29') .replace(/\*/g, '%2A'); }; // 计算签名 var getAuthorization = function (options, callback) { // var url = 'http://127.0.0.1:3000/sts-auth' + // 在这里填入临时密钥STS服务URL地址 var url = 'http://42.194.201.209:3333/sts'; var xhr = new XMLHttpRequest(); xhr.open('GET', url, true); xhr.onload = function (e) { var credentials; try { credentials = (new Function('return ' + xhr.responseText))().credentials; } catch (e) { } if (credentials) { callback(null, { XCosSecurityToken: credentials.sessionToken, Authorization: CosAuth({ SecretId: credentials.tmpSecretId, SecretKey: credentials.tmpSecretKey, Method: options.Method, Pathname: options.Pathname, }) }); } else { console.error(xhr.responseText); callback('获取签名出错'); } }; xhr.onerror = function (e) { callback('获取签名出错'); }; xhr.send(); }; // 上传文件 var uploadFile = function (file, callback) { var Key = 'dir/' + file.name; // 这里指定上传目录和文件名 getAuthorization({ Method: 'PUT', Pathname: '/' + Key }, function (err, info) { if (err) { alert(err); return; } var auth = info.Authorization; var XCosSecurityToken = info.XCosSecurityToken; var url = prefix + camSafeUrlEncode(Key).replace(/%2F/g, '/'); var xhr = new XMLHttpRequest(); xhr.open('PUT', url, true); xhr.setRequestHeader('Authorization', auth); XCosSecurityToken && xhr.setRequestHeader('x-cos-security-token', XCosSecurityToken); xhr.upload.onprogress = function (e) { console.log('上传进度 ' + (Math.round(e.loaded / e.total * 10000) / 100) + '%'); }; xhr.onload = function () { if (/^2\d\d$/.test('' + xhr.status)) { var ETag = xhr.getResponseHeader('etag'); callback(null, { url: url, ETag: ETag }); } else { callback('文件 ' + Key + ' 上传失败,状态码:' + xhr.status); } }; xhr.onerror = function () { callback('文件 ' + Key + ' 上传失败,请检查是否没配置 CORS 跨域规则'); }; xhr.send(file); }); }; // 监听表单提交 document.getElementById('submitBtn').onclick = function (e) { var file = document.getElementById('fileSelector').files[0]; if (!file) { document.getElementById('msg').innerText = '未选择上传文件'; return; } file && uploadFile(file, function (err, data) { console.log(err || data); document.getElementById('msg').innerText = err ? err : ('上传成功,ETag=' + data.ETag); }); }; })();</script> </body> </html>
打开本地浏览器,输入静态网页地址
http://42.194.201.209:3000/cos/test.html
选择文件,点击上传,上传成功后会在页面上打印出文件的 Etag。
原创声明,本文系作者授权发表,未经许可,不得转载。 如有侵权,请联系小编删除,谢谢。
点击阅读原文,领取 COS 限时1元礼包!
扫码关注腾讯云开发者
领取腾讯云代金券
Copyright © 2013 - 2025 Tencent Cloud. All Rights Reserved. 腾讯云 版权所有
深圳市腾讯计算机系统有限公司 ICP备案/许可证号:粤B2-20090059 深公网安备号 44030502008569
腾讯云计算(北京)有限责任公司 京ICP证150476号 | 京ICP备11018762号 | 京公网安备号11010802020287
Copyright © 2013 - 2025 Tencent Cloud.
All Rights Reserved. 腾讯云 版权所有