授权访问_Node.js_SDK 示例_对象存储 OSS

本文介绍如何使用STS以及签名URL临时授权访问OSS资源。

使用STS进行临时授权

OSS可以通过阿里云STS (Security Token Service) 进行临时授权访问。阿里云STS是为云计算用户提供临时访问令牌的Web服务。通过STS，您可以为第三方应用或子用户（即用户身份由您自己管理的用户）颁发一个自定义时效和权限的访问凭证。STS更详细的解释请参见STS介绍。

STS的优势如下：

您无需透露您的长期密钥（AccessKey）给第三方应用，只需生成一个访问令牌并将令牌交给第三方应用。您可以自定义这个令牌的访问权限及有效期限。
您无需关心权限撤销问题，访问令牌过期后自动失效。

使用STS访问OSS的流程请参见开发指南中的STS临时授权访问OSS。

使用STS访问OSS时需设置stsToken参数，具体示例如下：

let OSS = require('ali-oss');
let STS = OSS.STS;
let sts = new STS({
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>'
});
async function assumeRole () {
  try {
    let token = await sts.assumeRole(
    '<role-arn>', '<policy>', '<expiration>', '<session-name>');
    let client = new OSS({
      region: '<region>',
      accessKeyId: token.credentials.AccessKeyId,
      accessKeySecret: token.credentials.AccessKeySecret,
      stsToken: token.credentials.SecurityToken,
      bucket: '<bucket-name>'
    });
  } catch (e) {
    console.log(e);
  }
}
assumeRole();

参数说明如下：

role-arn：表示自定义的权限策略名称。
policy：在扮演角色的时候额外添加的权限限制。请参见基于RAM Policy的权限控制。
此处传入的Policy是用来限制扮演角色之后的临时访问凭证的权限。临时访问凭证最后获得的权限是角色的权限和这里传入的Policy的交集。扮演角色的时候传入Policy的原因是为了授权的灵活性，例如上传文件的时候可以根据不同的用户添加对于上传文件路径的限制等。
expiration：设置临时访问凭证的有效时长，单位为s，最小有效时长为900s，最大有效时长为3600s。

说明因STS临时账号以及签名URL均需设置有效时长，当您使用STS临时账号生成签名URL执行相关操作（例如上传、下载文件）时，以最小的有效时长为准。例如，您的STS临时账号的有效时长设置为1200s、签名URL设置为3600s时，当有效时长超过1200s后，您无法使用此STS临时账号生成的签名URL上传文件。
session-name：用户自定义参数。此参数用来区分不同的令牌，可用于用户级别的访问审计。此参数的格式说明请参见AssumeRole。

向STS申请临时Token时，还可以指定自定义的STS Policy。这样申请的临时权限是所扮演角色的权限与Policy指定的权限的交集。下面的例子将通过指定STS Policy申请对my-bucket的只读权限，并指定临时Token的过期时间为15分钟。

let OSS = require('ali-oss');
let STS = OSS.STS;
let sts = new STS({
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>'
});
let policy = {
  "Statement": [
    {
      "Action": [
        "oss:Get*"
      ],
      "Effect": "Allow",
      "Resource": ["acs:oss:*:*:my-bucket/*"]
    }
  ],
  "Version": "1"
};
async function assumeRole () {
  try {
    let token = await sts.assumeRole(
    '<role-arn>', policy, 15 * 60, '<session-name>');
    let client = new OSS({
      region: '<region>',
      accessKeyId: token.credentials.AccessKeyId,
      accessKeySecret: token.credentials.AccessKeySecret,
      stsToken: token.credentials.SecurityToken,
      bucket: '<bucket-name>'
    });
  } catch (e) {
    console.log(e);
  }
}
assumeRole();

使用签名URL进行临时授权

以下介绍使用签名URL进行临时授权的常见示例。

生成签名URL
您可以将生成的签名URL提供给访客进行临时访问。生成签名URL时，您可以通过指定URL的过期时间来限制访客的访问时长。

使用签名URL上传和下载文件

name {String}表示存放在OSS的Object名称，[expires] {Number}表示URL过期时间，默认是1800s。其他参数相关说明，请参见Github。

使用签名URL上传和下载文件的示例代码如下：

const OSS = require('ali-oss');

const client = new OSS({
  region: '<Your region>',
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>',
  bucket: '<Your bucket name>'
});

// 获取下载文件ossdemo.txt的签名URL，浏览器访问时默认直接预览要下载的文件。
const url = client.signatureUrl('ossdemo.txt');
console.log(url);

// 获取下载文件ossdemo.txt的签名URL，配置响应头实现浏览器访问时自动下载文件，并设置下载的文件名。
const filename = 'ossdemo.txt' // 自定义文件名。
const response = {
  'content-disposition': `attachment; filename=${encodeURIComponent(filename)}`
}
const url = client.signatureUrl('ossdemo.txt', { response });
console.log(url);


// 获取上传文件ossdemo.txt的签名URL，并设置过期时间。
const url = client.signatureUrl('ossdemo.txt', {
  expires: 3600, // 设置过期时间，默认为1800秒。
  method: 'PUT' //  设置请求方式为PUT。默认请求方式为GET。
});
console.log(url);

// 获取上传文件ossdemo.txt的签名URL，并设置Content-Type。
const url = client.signatureUrl('ossdemo.txt', {
  expires: 3600,
  method: 'PUT',
  'Content-Type': 'text/plain; charset=UTF-8',
});
console.log(url);

生成带图片处理参数的签名URL

生成带图片处理参数的签名URL示例代码如下：

let OSS = require('ali-oss');
let store = new OSS({
    bucket: '<your bucket>',
    region: '<your region>',
    accessKeyId: '<your accessKeyId>',
    accessKeySecret: '<your accessKeySecret>'
})
const url = store.signatureUrl('ossdemo.png', {
  process: 'image/resize,w_200'
});
console.log(url);
// --------------------------------------------------
const url = store.signatureUrl('ossdemo.png', {
  expires: 3600,
  process: 'image/resize,w_200'
});
console.log(url);