本文介绍如何使用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服务生成临时访问凭证。示例代码如下:
重要 使用express模块前,请确保已安装express模块。如果未安装,请执行npm install express --save命令进行安装。
// 通过STS服务生成临时访问凭证。临时访问凭证包括临时访问密钥(AccessKeyId和AccessKeySecret)和安全令牌(SecurityToken)。
const { STS } = require('ali-oss');
const express = require("express");
const app = express();

app.get('/sts', (req, res) => {
 let sts = new STS({
  // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
  accessKeyId: 'yourAccessKeyId',
  accessKeySecret: 'yourAccessKeySecret'
});
  // roleArn填写角色ARN。
  // policy填写自定义权限策略。
  // expiration用于设置临时访问凭证有效时间单位为秒,最小值为900,最大值以当前角色设定的最大会话时间为准。
  // sessionName用于自定义角色会话名称,用来区分不同的令牌,例如填写为SessionTest。
  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);
  });
});
app.listen(8000,()=>{
   console.log("server listen on:8000")
})
在客户端使用临时访问凭证初始化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(杭州)为例,yourRegion填写为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("https://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进行临时授权的常见示例。

说明 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));