本文介绍如何使用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设置的时间。

说明 您可以通过CreateRoleUpdateRole接口设置角色最大会话时间MaxSessionDuration。更多信息,请参见CreateRoleUpdateRole
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);