文档

使用STS临时访问凭证访问OSS

更新时间:
重要

本文中含有需要您注意的重要提示信息,忽略该信息可能对您的业务造成影响,请务必仔细阅读。

您可以通过STS服务为其他用户颁发一个临时访问凭证,用户通过临时访问凭证可以在限定的有效期内,以符合策略规定的权限访问OSS资源。超过有效期后,该凭证自动失效,无法继续通过该凭证访问OSS资源,确保了访问控制的灵活性和时效性。

操作视频

观看以下视频快速了解如何快速使用STS临时访问凭证访问OSS。

前提条件

已创建Bucket。具体操作,请参见创建存储空间

步骤一:创建RAM用户

  1. 登录RAM控制台

  2. 在左侧导航栏,选择身份管理>用户

  3. 单击创建用户

  4. 输入登录名称显示名称

  5. 访问方式区域下,选择OpenAPI调用访问,然后单击确定

  6. 根据界面提示,完成安全验证。

  7. 复制访问密钥(AccessKey ID和AccessKey Secret)。

    重要

    RAM用户的AccessKey Secret只在创建时显示,后续不支持查看,请妥善保管。

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

创建RAM用户后,您需要授予RAM用户通过扮演角色来调用STS服务的权限。

  1. 单击已创建RAM用户右侧对应的添加权限

  2. 新增授权页面,选择AliyunSTSAssumeRoleAccess系统策略。

    说明

    授予RAM用户调用STS服务AssumeRole接口的固定权限是AliyunSTSAssumeRoleAccess,与后续获取临时访问凭证以及通过临时访问凭证发起OSS请求所需权限无关。

    image.png

  3. 单击确认新增授权

步骤三:创建RAM角色

您需要创建RAM角色,用于定义RAM角色被扮演时,可以获得OSS服务的哪些访问权限。

  1. 在左侧导航栏,选择身份管理>角色

  2. 单击创建角色,选择可信实体类型为阿里云账号,单击下一步

  3. 创建角色对话框,角色名称填写为RamOssTest,选择信任的云账号当前云账号

  4. 单击完成。角色创建完成后,单击关闭

  5. 角色页面,搜索框输入角色名称RamOssTest,然后单击RamOssTest

  6. 单击ARN右侧的复制,保存角色的ARN。arn

步骤四:为RAM角色授予上传文件的权限

为RAM角色附加一个或多个权限策略,明确RAM角色在被扮演时所能拥有的OSS资源访问权限。例如,如果希望RAM用户在扮演该角色后只能向OSS指定Bucket上传文件,则需要为角色添加写入权限的策略。

  1. 创建上传文件的自定义权限策略。

    1. 在左侧导航栏,选择权限管理>权限策略

    2. 权限策略页面,单击创建权限策略

    3. 创建权限策略页面,单击脚本编辑,然后在策略文档输入框中赋予角色上传文件到examplebucket的权限。具体配置示例如下。

      警告

      以下示例仅供参考。您需要根据实际需求配置更细粒度的授权策略,防止出现权限过大的风险。关于更细粒度的授权策略配置详情,请参见通过RAM或STS服务向其他用户授权

      {
          "Version": "1",
          "Statement": [
           {
                 "Effect": "Allow",
                 "Action": [
                   "oss:PutObject"
                 ],
                 "Resource": [
                   "acs:oss:*:*:examplebucket/*"             
                 ]
           }
          ]
      }
      说明

      RAM角色所拥有的OSS权限取决于Action的配置,例如授予oss:PutObject权限,则RAM用户在扮演RAM角色时可以对指定Bucket执行简单上传、表单上传、追加上传、分片上传、断点续传上传等操作。更多信息,请参见OSS Action说明

    4. 策略配置完成后,单击继续编辑基本信息

    5. 基本信息区域,填写策略名称RamTestPolicy,然后单击确定

  2. 为RAM角色RamOssTest授予自定义权限策略。

    1. 在左侧导航栏,选择身份管理 > 角色

    2. 角色页面,找到目标RAM角色RamOssTest

    3. 单击RAM角色RamOssTest右侧的新增授权

    4. 添加权限页面下的自定义策略页签,选择已创建的自定义权限策略RamTestPolicy

    5. 单击确定

步骤五:使用RAM用户扮演RAM角色获取临时访问凭证

为角色授予上传文件的权限后,RAM用户需要通过扮演角色来获取临时访问凭证。临时访问凭证包括安全令牌(SecurityToken)、临时访问密钥(AccessKeyId和AccessKeySecret)以及过期时间(Expiration)。

使用STS SDK

您可以使用STS SDK来获取临时访问凭证。

本文以Java为例,说明如何使用STS SDK获取具有简单上传(oss:PutObject)权限的临时访问凭证。关于更多语言的STS SDK示例,请参见STS SDK概览。关于STS服务接入点的更多信息,请参见服务接入点

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;
import com.aliyuncs.auth.sts.AssumeRoleRequest;
import com.aliyuncs.auth.sts.AssumeRoleResponse;
public class StsServiceSample {
    public static void main(String[] args) { 
        // STS服务接入点,例如sts.cn-hangzhou.aliyuncs.com。您可以通过公网或者VPC接入STS服务。       
        String endpoint = "sts.cn-hangzhou.aliyuncs.com";
        // 从环境变量中获取步骤1生成的RAM用户的访问密钥(AccessKey ID和AccessKey Secret)。
        String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
        // 从环境变量中获取步骤3生成的RAM角色的RamRoleArn。
        String roleArn = System.getenv("OSS_STS_ROLE_ARN");
        // 自定义角色会话名称,用来区分不同的令牌,例如可填写为SessionTest。        
        String roleSessionName = "yourRoleSessionName";   
        // 临时访问凭证将获得角色拥有的所有权限。      
        String policy = null;
        // 临时访问凭证的有效时间,单位为秒。最小值为900,最大值以当前角色设定的最大会话时间为准。当前角色最大会话时间取值范围为3600秒~43200秒,默认值为3600秒。
        // 在上传大文件或者其他较耗时的使用场景中,建议合理设置临时访问凭证的有效时间,确保在完成目标任务前无需反复调用STS服务以获取临时访问凭证。
        Long durationSeconds = 3600L;
        try {
            // 发起STS请求所在的地域。建议保留默认值,默认值为空字符串("")。
            String regionId = "";
            // 添加endpoint。适用于Java SDK 3.12.0及以上版本。
            DefaultProfile.addEndpoint(regionId, "Sts", endpoint);
            // 添加endpoint。适用于Java SDK 3.12.0以下版本。
            // DefaultProfile.addEndpoint("",regionId, "Sts", endpoint);
            // 构造default profile。
            IClientProfile profile = DefaultProfile.getProfile(regionId, accessKeyId, accessKeySecret);
            // 构造client。
            DefaultAcsClient client = new DefaultAcsClient(profile);
            final AssumeRoleRequest request = new AssumeRoleRequest();
            // 适用于Java SDK 3.12.0及以上版本。
            request.setSysMethod(MethodType.POST);
            // 适用于Java SDK 3.12.0以下版本。
            // request.setMethod(MethodType.POST);
            request.setRoleArn(roleArn);
            request.setRoleSessionName(roleSessionName);
            request.setPolicy(policy); 
            request.setDurationSeconds(durationSeconds); 
            final AssumeRoleResponse response = client.getAcsResponse(request);
            System.out.println("Expiration: " + response.getCredentials().getExpiration());
            System.out.println("Access Key Id: " + response.getCredentials().getAccessKeyId());
            System.out.println("Access Key Secret: " + response.getCredentials().getAccessKeySecret());
            System.out.println("Security Token: " + response.getCredentials().getSecurityToken());
            System.out.println("RequestId: " + response.getRequestId());
        } catch (ClientException e) {
            System.out.println("Failed:");
            System.out.println("Error code: " + e.getErrCode());
            System.out.println("Error message: " + e.getErrMsg());
            System.out.println("RequestId: " + e.getRequestId());
        }
    }
}
重要

如果您希望临时访问凭证在获得角色拥有的权限后,进一步限制权限范围,例如角色被授予了上传文件到examplebucket的权限,您需要限制临时访问凭证只能向该Bucket下的某个目录上传文件,您可以通过参考以下示例设置policy。

// 以下Policy用于限制仅允许使用临时访问凭证向examplebucket下的src目录上传文件。
// 临时访问凭证最后获得的权限是步骤4设置的角色权限和该Policy设置权限的交集,即仅允许将文件上传至examplebucket下的src目录。      
String policy = "{\n" +
                "    \"Version\": \"1\", \n" +
                "    \"Statement\": [\n" +
                "        {\n" +
                "            \"Action\": [\n" +
                "                \"oss:PutObject\"\n" +
                "            ], \n" +
                "            \"Resource\": [\n" +
                "                \"acs:oss:*:*:examplebucket/src/*\" \n" +
                "            ], \n" +
                "            \"Effect\": \"Allow\"\n" +
                "        }\n" +
                "    ]\n" +
                "}";

使用REST API

您可以通过调用STS服务的AssumeRole - 获取扮演角色的临时身份凭证接口来获取临时访问凭证。

步骤六:使用临时访问凭证上传文件至OSS

在临时访问凭证有效期(Expiration)到期之前,使用临时访问凭证上传文件至OSS。

说明
  • 临时访问凭证过期时间格式是UTC,与北京时间有8小时的时差。例如,临时访问凭证过期时间是2024-04-18T11:33:40Z,说明临时访问凭证将在北京时间2024年4月18日19时33分40秒之前过期。

  • 临时访问凭证没有明确的使用次数限制。在有效期到期之前,您可以重复调用上传接口上传多个文件,也可以将要上传的多个文件压缩后上传,最终达到批量上传的目的。

本文以Java SDK 3.12.0版本为例,将本地D:\\localpath路径下的exampletest.txt文件上传至examplebucket的示例代码如下。关于其他SDK使用临时访问凭证上传文件到OSS的代码示例,请参见简介

import com.aliyun.oss.OSS;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.PutObjectRequest;
import com.aliyuncs.exceptions.ClientException;

import java.io.File;

public class Demo {
    public static void main(String[] args) throws ClientException {
// OSS访问域名。以华东1(杭州)地域为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
 String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
// 从环境变量中获取步骤5生成的临时访问密钥AccessKey ID和AccessKey Secret,非阿里云账号AccessKey ID和AccessKey Secret。
String accessKeyId = System.getenv("OSS_ACCESS_KEY_ID");
String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");
// 从环境变量中获取步骤5生成的安全令牌SecurityToken。
String securityToken = System.getenv("OSS_SESSION_TOKEN");

// 创建OSSClient实例。
OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret, securityToken);
// 将本地文件exampletest.txt上传至examplebucket。
PutObjectRequest putObjectRequest = new PutObjectRequest("examplebucket", "exampletest.txt", new File("D:\\localpath\\exampletest.txt"));

// ObjectMetadata metadata = new ObjectMetadata();
// 上传文件时设置存储类型。
// metadata.setHeader(OSSHeaders.OSS_STORAGE_CLASS, StorageClass.Standard.toString());
// 上传文件时设置读写权限ACL。
// metadata.setObjectAcl(CannedAccessControlList.Private);
// putObjectRequest.setMetadata(metadata);

try {
     // 上传文件。
     ossClient.putObject(putObjectRequest);
    } catch (OSSException oe) {
        System.out.println("Caught an OSSException, which means your request made it to OSS, "
                + "but was rejected with an error response for some reason.");
        System.out.println("Error Message:" + oe.getErrorMessage());
        System.out.println("Error Code:" + oe.getErrorCode());
        System.out.println("Request ID:" + oe.getRequestId());
        System.out.println("Host ID:" + oe.getHostId());
    } finally {
        if (ossClient != null) {
            ossClient.shutdown();
        }
    }
}
}

常见问题

报错You are not authorized to do this action. You should be authorized by RAM.如何处理?

步骤五中使用RAM用户扮演RAM角色获取临时访问凭证时,必须使用RAM用户的访问密钥(AccessKey ID和AccessKey Secret),不能使用阿里云账号的访问密钥发起请求。

报错The Min/Max value of DurationSeconds is 15min/1hr.如何处理?

报错原因是设置的临时访问凭证有效期超出允许的时间范围。请遵循以下原则设置有效期:

  • 如果没有自定义角色最大会话时间,则当前角色会话时间默认值为3600秒。此时,通过durationSeconds设置的临时访问凭证有效时间允许的最小值为900秒,最大值为3600秒。

  • 如果自定义了角色最大会话时间,则通过durationSeconds设置的临时访问凭证有效时间的最小值为900秒,最大值以角色最大会话时间为准。角色会话时间允许设置的取值范围为3600秒~43200秒。

您可以通过RAM控制台查看角色最大会话时间。具体步骤,请参见查看RAM角色

报错The security token you provided is invalid.如何处理?

请确保完整填写步骤五获取到的SecurityToken。

报错The OSS Access Key Id you provided does not exist in our records.如何处理?

临时访问凭证已过期,过期后自动失效。请使用临时访问密钥(AccessKeyId和AccessKeySecret)向App服务器申请新的临时访问凭证。具体操作,请参见步骤五

报错AccessDenied : Anonymous access is forbidden for this operation.如何处理?

通过步骤五获取临时访问凭证时,您需要使用填写步骤一生成的RAM用户访问密钥AccessKey ID和AccessKey Secret,非阿里云账号AccessKey ID和AccessKey Secret。

报错NoSuchBucket如何处理?

出现该报错的原因是指定的Bucket不存在。请检查并配置正确的Bucket名称。

通过临时访问凭证操作OSS资源时报错You have no right to access this object because of bucket acl.如何处理?

出现该报错通常是Policy设置错误。关于Policy中涉及各元素的填写要求,请参见RAM Policy。如果您需要获取具有分片上传、追加上传等权限的临时访问凭证,您需要通过Policy中的Action元素授予对应权限。关于OSS Action的更多信息,请参见OSS Action分类

通过临时访问凭证操作OSS资源时报错Access denied by authorizer's policy.如何处理?

出现该报错通常是无权限执行相关操作。申请临时访问凭证之前,需要创建用于获取临时访问凭证的RAM角色并完成角色授权(本文档步骤四)。向STS服务器发起扮演该角色的请求,以获取临时访问凭证时可以通过policy参数进一步限制临时访问凭证的权限(本文档步骤五)。

  • 如果设置policy,则临时访问凭证最终的权限是RAM角色权限策略与policy权限策略的交集。

    • 示例1

      如下图所示,A代表RAM角色的权限,B代表通过policy参数设置的权限,C代表临时访问凭证最终的权限。

      1.jpg

    • 示例2

      如下图所示,A代表RAM角色权限,B代表通过policy参数设置的权限,且policy参数设置的权限是RAM角色权限的子集。因此,B代表临时访问凭证的最终权限。

      2.jpg

  • 如果不设置policy,则临时访问凭证具有与RAM角色相同的权限策略。

报错The bucket you are attempting to access must be addressed using the specified endpoint.如何处理?

出现该报错的原因是步骤六中的Endpoint参数填写错误。您需要根据Bucket所在Region填写对应的Endpoint。关于Region与Endpoint对应关系的说明,请参见访问域名和数据中心

是否支持同时获取多个临时访问凭证?

支持。发起一次请求仅返回一个临时访问凭证。如果您希望获取多个临时访问凭证,您需要发起多次请求。在有效期内,您可以同时使用获取到的多个临时访问凭证。

报错时间格式不正确如何处理?

如果调用时报错时间格式不正确,可能是由于Timestamp参数中间多余空格,请排查修改。

请求的时间戳日期格式按照ISO8601标准表示,并需要使用UTC时间。格式为:YYYY-MM-DDThh:mm:ssZ。例如,2014-05-26T12:00:00Z(为北京时间2014年5月26日20点0分0秒)。

返回0003-0000301怎么处理?

返回0003-0000301原因是临时访问凭证不具有执行OSS相关操作的权限,解决方案请参见0003-00000301

相关文档

  • 如果您希望从服务端获取STS临时访问凭证后,通过客户端上传文件,且上传文件时需要限制上传的文件大小、上传的文件类型、上传到Bucket的具体路径等,请参见客户端直传

  • 通过STS临时访问凭证授权上传文件到OSS后,您可以通过签名URL的方式将文件分享给第三方用户进行预览或者下载。具体操作,请参见使用文件URL分享文件