授权访问 - 对象存储 OSS

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

说明由于STS临时账号以及签名URL均需设置有效时长，当您使用STS临时账号生成签名URL执行相关操作（例如上传、下载文件）时，以最小的有效时长为准。例如您的STS临时账号的有效时长设置为1200秒、签名URL设置为3600秒时，当有效时长超过1200秒后，您无法使用此STS临时账号生成的签名URL上传文件。

使用STS进行临时授权

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

STS的优势如下：

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

说明关于搭建STS服务的具体操作，请参见开发指南中的使用STS临时访问凭证访问OSS。您可以通过调用STS服务的AssumeRole接口或者使用各语言STS SDK来获取临时访问凭证。临时访问凭证包括临时访问密钥（AccessKeyId和AccessKeySecret）和安全令牌（SecurityToken）。临时访问凭证有效时间单位为秒，最小值为900，最大值以当前角色设定的最大会话时间为准。更多信息，请参见设置角色最大会话时间。

通过STS服务生成临时访问凭证。示例代码如下：

注意使用express模块前，请确保已安装express模块。如果未安装，请执行npm install express --save命令进行安装。

// 通过STS服务生成临时访问凭证。临时访问凭证包括临时访问密钥（AccessKeyId和AccessKeySecret）和安全令牌（SecurityToken）。
const app = express();
const { STS } = require('ali-oss');

app.get('/sts', (req, res) => {
 let sts = new STS({
  // 阿里云主账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM账号进行API访问或日常运维，请登录RAM控制台创建RAM账号。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});
  sts.assumeRole('roleArn', 'policy', 'expiration', 'sessionName').then((result) => {
    console.log(result);
    res.set('Access-Control-Allow-Origin', '*');
    res.set('Access-Control-Allow-METHOD', 'GET');
    res.json({
      AccessKeyId: result.credentials.AccessKeyId,
      AccessKeySecret: result.credentials.AccessKeySecret,
      SecurityToken: result.credentials.SecurityToken,
      Expiration: result.credentials.Expiration
    });
  }).catch((err) => {
    console.log(err);
    res.status(400).json(err.message);
  });
});

在客户端使用临时访问凭证初始化OSSClient，用于临时授权访问OSS资源。示例代码如下：

const axios = require("axios");
const OSS = require("ali-oss");

// 在客户端使用临时访问凭证初始化OSS客户端，用于临时授权访问OSS资源。
const getToken = async () => {
  await axios.get("https:/xxx/sts").then((token) => {
    const client = new OSS({
       // yourRegion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
      region: 'yourRegion',
      accessKeyId: token.AccessKeyId,
      accessKeySecret: token.AccessKeySecret,
      stsToken: token.SecurityToken,
      // 填写Bucket名称，例如examplebucket。
      bucket: "examplebucket",
      // 刷新临时访问凭证。
      refreshSTSToken: async () => {
        const refreshToken = await axios.get("http://127.0.0.1/sts");
        return {
          accessKeyId: refreshToken.AccessKeyId,
          accessKeySecret: refreshToken.AccessKeySecret,
          stsToken: refreshToken.SecurityToken,
        };
      },
    });
  });
};

STS相关参数说明请参见下表。更多信息，请参见AssumeRole。


参数	类型	是否必选	示例值	描述
roleArn	String	是	acs:ram::17464958********:role/ossststest	指定角色的ARN。格式：`acs:ram::$accountID:role/$roleName` 。其中$accountID为阿里云账号ID，$roleName为RAM角色名称。您可以登录RAM控制台，在RAM角色管理界面，搜索创建的RAM角色后，单击RAM角色名称，在RAM角色详情界面查看和复制角色的ARN信息。
policy	String	否	{"Version": "1", "Statement": [{"Action": ["oss:GetObject"], "Effect": "Allow", "Resource": ["acs:oss:::examplebucket/*"]}]}	权限策略。生成STS临时访问凭证时可以指定一个额外的权限策略，以进一步限制STS临时访问凭证的权限。如果不指定则返回的STS临时访问凭证拥有指定角色的所有权限。长度为1~1024个字符。
expiration	Number	否	3600	临时访问凭证的过期时间，单位为秒，默认值为3600秒。过期时间最小值为900秒，最大值为MaxSessionDuration设置的时间。说明您可以通过CreateRole或UpdateRole接口设置角色最大会话时间MaxSessionDuration。更多信息，请参见CreateRole或UpdateRole。
sessionName	String	是	Alice	用户自定义参数。此参数用来区分不同的令牌，可用于用户级别的访问审计。长度为2~32个字符，可包含英文字母、数字、英文句点（.）、at（@）、短划线（-）和下划线（_）。

使用签名URL进行临时授权

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

生成签名URL
您可以将生成的签名URL提供给访客进行临时访问。生成签名URL时，您可以通过指定URL的过期时间来限制访客的访问时长。签名URL的默认过期时间为3600秒，最大值为32400秒。

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

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

以下代码用于生成对应签名URL来上传和下载文件。

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

const client = new OSS({
  // yourRegion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // 填写Bucket名称。
  bucket: 'examplebucket'
});

// 获取下载exampleobject.txt文件的签名URL，使用浏览器访问时默认直接预览要下载的文件。
// 填写不包含Bucket名称在内的Object完整路径。
const url = client.signatureUrl('exampleobject.txt');
console.log(url);

// 获取下载exampleobject.txt文件的签名URL，配置响应头实现浏览器访问时自动下载文件，并自定义下载后的文件名称。
const filename = 'ossdemo.txt' // 自定义下载后的文件名称。
const response = {
  'content-disposition': `attachment; filename=${encodeURIComponent(filename)}`
}
// 填写不包含Bucket名称在内的Object完整路径。
const url = client.signatureUrl('exampleobject.txt', { response });
console.log(url);

// 获取上传exampleobject.txt文件的签名URL，并设置过期时间。
// 填写不包含Bucket名称在内的Object完整路径。
const url = client.signatureUrl('exampleobject.txt', {
  expires: 3600, // 设置过期时间，默认值为1800秒。
  method: 'PUT'  // 设置请求方式为PUT。默认请求方式为GET。
});
console.log(url);

// 获取上传exampleobject.txt文件的签名URL，并设置Content-Type。
// 填写不包含Bucket名称在内的Object完整路径。
const url = client.signatureUrl('exampleobject.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({
  // yourRegion填写Bucket所在地域。以华东1（杭州）为例，Region填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret',
  // 填写Bucket名称。
  bucket: 'examplebucket'
})

// 获取处理exampleobject.png图片的签名URL。
// 填写不包含Bucket名称在内的Object完整路径。
const url = store.signatureUrl('exampleobject.png', {
  process: 'image/resize,w_200' // 设置图片处理参数。
});
console.log(url);

// 获取处理exampleobject.png图片的签名URL，并设置过期时间。
// 填写不包含Bucket名称在内的Object完整路径。
const url = store.signatureUrl('exampleobject.png', { 
  expires: 3600, // 设置过期时间，默认值为1800秒。
  process: 'image/resize,w_200' // 设置图片处理参数。
});
console.log(url);