本文介绍如何使用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临时授权访问OSS的步骤如下:

步骤1:创建RAM用户

  1. 登录RAM控制台
  2. 在左侧导航栏,选择身份管理 > 用户
  3. 单击创建用户
  4. 输入登录名称显示名称
  5. 访问方式区域下,选择Open API 调用访问,然后单击确定
  6. 单击复制,保存访问密钥(AccessKey ID 和 AccessKey Secret)。

步骤2:为RAM用户授予请求AssumeRole的权限

  1. 单击已创建RAM用户右侧对应的添加权限
  2. 添加权限页面,选择AliyunSTSAssumeRoleAccess系统策略。policy
  3. 单击确定

步骤3:创建用于获取临时访问凭证的角色

  1. 在左侧导航栏,选择身份管理 > 角色
  2. 单击创建角色,选择可信实体类型为阿里云账号,单击下一步
  3. 角色名称填写为RamOssTest选择云账号当前云账号
  4. 单击完成。角色创建完成后,单击关闭
  5. RAM角色管理页面,搜索框输入角色名称RamOssTest
  6. 单击复制,保存角色的ARN。arn

步骤4:为角色授予上传和下载文件的权限

  1. 为角色授予上传文件和下载文件的自定义权限策略。
    1. 在左侧导航栏,选择权限管理 > 权限策略
    2. 单击创建权限策略
    3. 创建权限策略页面,单击脚本编辑,然后在策略文档输入框中赋予角色向目标存储空间examplebucket执行简单上传(oss:PutObject)和下载文件(oss:GetObject)的权限。具体配置示例如下。
      警告 以下示例仅供参考。您需要根据实际需求配置更细粒度的授权策略,防止出现权限过大的风险。关于更细粒度的授权策略配置详情,请参见通过RAM或STS服务向其他用户授权
      {
          "Version": "1",
          "Statement": [
           {
                 "Effect": "Allow",
                 "Action": [
                   "oss:PutObject",
                   "oss:GetObject"
                 ],
                 "Resource": [
                   "acs:oss:*:*:examplebucket",
                   "acs:oss:*:*:examplebucket/*"
                 ]
           }
          ]
      }
    4. 策略配置完成后,单击下一步
    5. 基本信息区域,填写策略名称RamTestPolicy,然后单击确定
  2. 为RAM角色RamOssTest授予自定义权限策略。
    1. 在左侧导航栏,选择身份管理 > 角色
    2. 角色页面,找到目标RAM角色RamOssTest
    3. 单击RAM角色RamOssTest右侧的添加权限
    4. 添加权限页面下的自定义策略页签,选择已创建的自定义权限策略RamTestPolicy
    5. 单击确定

步骤5:生成临时访问凭证。

临时访问凭证包括临时访问密钥(AccessKey ID和AccessKey Secret)和安全令牌(SecurityToken)。临时访问凭证有效时间单位为秒,最小值为900,最大值以当前角色设定的最大会话时间为准。更多信息,请参见设置角色最大会话时间

重要 使用express模块前,请确保已安装express模块。如果未安装,请执行npm install express --save命令进行安装。
const { STS } = require('ali-oss');
const express = require("express");
const app = express();

app.get('/sts', (req, res) => {
 let sts = new STS({
  // 填写步骤1创建的RAM用户AccessKey。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});
  // roleArn填写步骤2获取的角色ARN,例如acs:ram::175708322470****:role/ramtest。
  // policy填写自定义权限策略,用于进一步限制STS临时访问凭证的权限。如果不指定Policy,则返回的STS临时访问凭证默认拥有指定角色的所有权限。
  // 临时访问凭证最后获得的权限是步骤4设置的角色权限和该Policy设置权限的交集。
  // expiration用于设置临时访问凭证有效时间单位为秒,最小值为900,最大值以当前角色设定的最大会话时间为准。本示例指定有效时间为3000秒。
  // sessionName用于自定义角色会话名称,用来区分不同的令牌,例如填写为sessiontest。
  sts.assumeRole('acs:ram::175708322470****:role/ramtest', ``, '3000', 'sessiontest').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);
  });
});
app.listen(8000,()=>{
   console.log("server listen on:8000")
})

步骤6:使用临时访问凭证上传和下载文件。

  • 使用临时访问凭证上传文件
    const axios = require("axios");
    const OSS = require("ali-oss");
    
    // 在客户端使用临时访问凭证初始化OSS客户端,用于临时授权访问OSS资源。
    const getToken = async () => {
      // 设置客户端请求访问凭证的地址。
      await axios.get("http://localhost:8000/sts").then((token) => {
        const client = new OSS({
           // yourRegion填写Bucket所在地域。以华东1(杭州)为例,yourRegion填写为oss-cn-hangzhou。
          region: 'oss-cn-hangzhou',
          accessKeyId: token.data.AccessKeyId,
          accessKeySecret: token.data.AccessKeySecret,
          stsToken: token.data.SecurityToken,
          // 填写Bucket名称。
          bucket: "examplebucket",
          // 刷新临时访问凭证。
          refreshSTSToken: async () => {
            const refreshToken = await axios.get("http://localhost:8000/sts");
            return {
              accessKeyId: refreshToken.AccessKeyId,
              accessKeySecret: refreshToken.AccessKeySecret,
              stsToken: refreshToken.SecurityToken,
            };
          },
        });
        // 使用临时访问凭证上传文件。
        // 填写不包含Bucket名称在内的Object的完整路径,例如exampleobject.jpg。
        // 填写本地文件的完整路径,例如D:\\example.jpg。
        client.put('exampleobject.jpg', 'D:\\example.jpg').then((res)=>{console.log(res)}).catch(e=>console.log(e))
      });
    };
    getToken()
  • 使用临时访问凭证下载文件
    const axios = require("axios");
    const OSS = require("ali-oss");
    
    // 在客户端使用临时访问凭证初始化OSS客户端,用于临时授权访问OSS资源。
    const getToken = async () => {
      // 设置客户端请求访问凭证的地址。
      await axios.get("http://localhost:8000/sts").then((token) => {
        const client = new OSS({
           // yourRegion填写Bucket所在地域。以华东1(杭州)为例,yourRegion填写为oss-cn-hangzhou。
          region: 'oss-cn-hangzhou',
          accessKeyId: token.data.AccessKeyId,
          accessKeySecret: token.data.AccessKeySecret,
          stsToken: token.data.SecurityToken,
          // 填写Bucket名称。
          bucket: "examplebucket",
          // 刷新临时访问凭证。
          refreshSTSToken: async () => {
            const refreshToken = await axios.get("http://localhost:8000/sts");
            return {
              accessKeyId: refreshToken.AccessKeyId,
              accessKeySecret: refreshToken.AccessKeySecret,
              stsToken: refreshToken.SecurityToken,
            };
          },
        });
        // 使用临时访问凭证下载文件。
        // 填写不包含Bucket名称在内的Object的完整路径,例如exampleobject.jpg。
        // 填写本地文件的完整路径,例如D:\\example.jpg。
        client.get('exampleobject.jpg', 'D:\\example.jpg').then((res)=>{console.log(res)}).catch(e=>console.log(e))
      });
    };
    getToken()

使用签名URL进行临时授权

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

说明 Node.js SDK不支持生成带versionID的签名URL。

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

重要 通过以下示例生成的签名URL中如果包含特殊符号+,可能出现无法正常访问该签名URL的现象。如需正常访问该签名URL,请将签名URL中的+替换为%2B

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

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

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

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

生成签名URL并通过签名URL上传文件

const OSS = require("ali-oss");
const { default: axios } = require("axios");
const fs = require("fs");

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',
});

// 生成文件的签名URL。
const url = client.signatureUrl("examplefile.txt", {
  method: "PUT",
  "Content-Type": "application/x-www-form-urlencoded",
});

// 指定本地文件的完整路径。
const file = fs.readFileSync("D:\\localpath\\examplefile.txt");

// 使用签名URL上传文件。
axios({
  url,
  method: "PUT",
  data: file,
})
  .then((r) => console.log(r))
  .catch((e) => console.log(e));

生成签名URL并通过签名URL下载文件

const { default: axios } = require("axios");
const fs = require("fs");

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

// 通过签名URL下载文件到本地,并填写下载到本地的文件完整路径。
const file = "D:\\localpath\\examplefile.txt";

axios({
  url,
  method: "GET",
})
  .then((r) => {
    fs.writeFile(file, r.data, (err) => {
      if (err) {
        console.log(err);
      }
    });
  })
  .catch((e) => console.log(e));