利用STS临时密钥服务快速搭建直传页面的实践
简介
为了实现权限分离，提供更细隔离度的权限控制，有效的控制帐号生效周期，本文通过腾讯云CAM产品的STS（临时访问凭证）来实现部署，调试，验证等一系列的操作体验。
主要介绍基于腾讯云对象存储 COS，如何使用 COS 签名工具和 HTTP 请求工具 Postman 来验证临时密钥的有效性，以及如何快速实现一个 Web 端页面的文件直传功能。服务器上只需要生成和管理访问密钥，无需关心细节，文件数据都存放在腾讯云 COS 上。
在前端页面直接向 COS 发起请求，此时数据的上传和下载可以不经过后端服务器，既节约了后端服务器的带宽和负载，还可以充分利用 COS 的带宽和全球加速等能力，提升应用体验。
临时密钥
临时密钥（临时访问凭证） 是通过 CAM 云 API 提供的接口，获取到权限受限的密钥。
COS API 可以使用临时密钥计算签名，用于发起 COS API 请求。
COS API 请求使用临时密钥计算签名时，需要用到获取临时密钥接口返回信息中的三个字段，如下：
- TmpSecretId
- TmpSecretKey
- Token
使用临时密钥的优势
Web、iOS、Android 使用 COS 时，通过固定密钥计算签名方式不能有效地控制权限，同时把永久密钥放到客户端代码中有极大的泄露风险。如若通过临时密钥方式，则可以方便、有效地解决权限控制问题。 例如，在申请临时密钥过程中，可以通过设置权限策略 policy 字段，限制操作和资源，将权限限制在指定的范围内。
有关 COS API 授权策略，请参见：
架构说明
整体架构图如下所示：
其中：
- 用户客户端：即网页、用户手机 App 等。
- COS：腾讯云对象存储，负责存储 App 上传的数据。
- CAM：腾讯云访问管理，用于生成 COS 的临时密钥。
- 用户服务端：用户自己的后台服务器，这里用于获取临时密钥，并返回给网页。
- 用户客户端向用户的后台服务器请求临时密钥。
- 用户的服务器 通过 CAM STS 接口请求临时密钥。
- CAM 返回临时密钥给用户服务器，该临时密钥有效期最长是 2 小时。
- 该接口属于 CAM 侧的，所以需要客户服务器有能够访问公网的能力。
- 该接口的 QPS 是 600，跟 COS 的存储桶 境内3W/境外3K QPS 不太相同。
- 用户不需要每次上传、下载操作都调用一次临时密钥STS接口，同一个临时密钥申请后在有效时间内都可以使用。
- 客户服务器下发临时密钥给客户端。
- 客户端获取到临时密钥的信息后，再做签名，携带签名请求上传、下载等操作。
环境准备
- 云服务器 1 台 -> 公网ip: 42.194.201.209
- Node.js、Git、NPM、Postman 最新版即可
本文测试使用的各个工具版本为:
|
名称 |
版本 |
|---|---|
|
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。各个 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 工具，可用于生成请求签名。您可以在工具页面上填入指定的参数，生成请求签名，以及校验请求签名的正确性。
- 基础信息
- API 版本：XML/JSON 版本。
- 签名有效时间：签名的有效时间，默认 60 分钟。可以自定义 Unix 起止时间戳。
- API 密钥
- API 密钥的参数信息可从控制台的 API 密钥管理 页面中获取。
- HTTP 参数
- HttpMethod：必填项。HTTP 请求方法，包括 GET，POST，PUT，DELETE，HEAD。
- HttpURI：必填项。HTTP 请求 URI 部分，即 Object Key。
- HttpParameters：可选项。HTTP 请求参数。当您需验证 url 参数时可填写该参数。其中，key 小写，value 需要进行 URLEncode，多个 key 以字典排序。
- HttpHeaders：可选项。HTTP 请求头部。当您需验证 url 参数时可填写该参数。其中，key 小写，value 需要进行 URLEncode，多个 key 以字典排序。
点击生成签名后，会看到生成类似以下格式的一种签名串。
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 install
npm start本地浏览器打开
http://42.194.201.209:3000可以看到如下效果，代表 Express 应用配置成功。
配置 CORS 跨域
进入存储桶详情页，单击【基础配置】页签。下拉页面找到【跨域访问 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 handler
app.use(function (req, res, next) {
next(createError(404));
});打开 Public 目录，新建文件test.html，示例：
使用 AJAX 上传 AJAX 上传需要浏览器支持基本的 HTML5 特性，当前方案使用 PUT Object 文档，操作指引如下：
- 修改下方代码的 Bucket 和 Region，并复制到 test.html 文件。
- 修改 test.html 里的签名服务地址。
<!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。
