Node.js授权访问 - 对象存储 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临时授权访问OSS的步骤如下：

步骤1：创建RAM用户

登录RAM控制台。
在左侧导航栏，选择身份管理>用户。
单击创建用户。
输入登录名称和显示名称。
在访问方式区域下，选择OpenAPI调用访问，然后单击确定。
根据界面提示，完成安全验证。
复制访问密钥（AccessKey ID和AccessKey Secret）。
重要
RAM用户的AccessKey Secret只在创建时显示，后续不支持查看，请妥善保管。

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

单击已创建RAM用户右侧对应的添加权限。
在新增授权页面，选择AliyunSTSAssumeRoleAccess系统策略。
说明
授予RAM用户调用STS服务AssumeRole接口的固定权限是AliyunSTSAssumeRoleAccess，与后续获取临时访问凭证以及通过临时访问凭证发起OSS请求所需权限无关。
单击确认新增授权。

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

在左侧导航栏，选择身份管理>角色。
单击创建角色，选择可信实体类型为阿里云账号，单击下一步。
在创建角色对话框，角色名称填写为RamOssTest，选择信任的云账号为当前云账号。
单击完成。角色创建完成后，单击关闭。
在角色页面，搜索框输入角色名称RamOssTest，然后单击RamOssTest。
单击ARN右侧的复制，保存角色的ARN。

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

为角色授予上传文件和下载文件的自定义权限策略。
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，然后单击确定。
为RAM角色RamOssTest授予自定义权限策略。
1. 在左侧导航栏，选择身份管理 > 角色。
2. 在角色页面，找到目标RAM角色RamOssTest。
3. 单击RAM角色RamOssTest右侧的新增授权。
4. 在添加权限页面下的自定义策略页签，选择已创建的自定义权限策略RamTestPolicy。
5. 单击确定。

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

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

重要

使用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：使用临时访问凭证上传和下载文件。

使用临时访问凭证上传文件

说明

此步骤中的示例需要依赖axios，请在运行前下载

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,
      authorizationV4: true,
      // 填写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,
      authorizationV4: true,
      // 填写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过程中，SDK利用本地存储的密钥信息，根据特定算法计算出签名（signature），然后将其附加到URL上，以确保URL的有效性和安全性。这一系列计算和构造URL的操作都是在客户端完成，不涉及网络请求到服务端。因此，生成签名URL时不需要授予调用者特定权限。但是，为避免第三方用户无法对签名URL授权的资源执行相关操作，需要确保调用生成签名URL接口的身份主体被授予对应的权限。
例如，通过签名URL上传文件时，需要授予oss:PutObject权限。通过签名URL下载或预览文件时，需要授予oss:GetObject权限。
您可以将生成的签名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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // 填写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);

生成带versionId的签名URL

const OSS = require('ali-oss');
const client  = new OSS({  
  // yourRegion填写Bucket所在地域。以华东1（杭州）为例，yourRegion填写为oss-cn-hangzhou。
  region: 'yourRegion',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // 填写Bucket名称。
  bucket: 'examplebucket'
})
  // 生成带versionId的签名URL。
  // 填写不包含Bucket名称在内的Object完整路径，例如example.png。
  console.log(
  client.signatureUrl('example.jpg', {
    subResource: {
      // 填写Object的versionId。
      versionId: 'CAEQMBiBgIDW7duIqxgiIDA4OWRiYmFlZDUxMDQ3YzM4OWUyNjQzMzAzMDhj****',
    },
  })
 )

生成签名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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // 填写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',
  // 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  authorizationV4: true,
  // 填写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));

常见问题

生成签名URL时是否支持使用POST方法？

不支持。生成签名URL时仅支持使用PUT和GET方法。如果您需要通过POST方法进行上传，您需要参考PostObject自行构造POST请求。