OSS-服务端签名Web端直传+STS获取临时凭证+POST签名v4版本开发过程中的细节

本文主要结合服务端STS获取临时凭证(签名)直传官方文档对开发中比较容易出错的地方加以提醒；建议主要还是以官方文档为主。本文中的代码几乎就是官方给的代码示例。
阅读前请先比对OSS版本，这可能关系到本文中列举的坑是否能解决你的问题

		<dependency><groupId>com.aliyun.oss</groupId><artifactId>aliyun-sdk-oss</artifactId><version>3.17.4</version></dependency><dependency><groupId>com.aliyun</groupId><artifactId>sts20150401</artifactId><version>1.1.6</version></dependency>

只不过重要的OSS基本参数官方建议给到环境变量中；本文直接将重要的OSS基础信息给到了Spring主配置文件中（方便后期迁移到Nacos的配置中心管理），知道了这一点，在接下来代码阅读的过程中看到如下的代码片段也就不陌生了。

接下来也将OSS基本参数封装成AliOSSProp的代码顺手贴出来

/*** oss的基础信息* prefix = "alibaba.oss"表示Spring、Springboot主配置文件中以alibaba.oss打头的自定义参数值，都将一 一映射到当前类的属性上*/
@ConfigurationProperties(prefix = "alibaba.oss")
@Component
@Getter
@Setter
public class AliOSSProp {private String accessKeyId;private String secretAccessKey;/*** 确保获取临时访问凭证时Endpoint使用STS域名，例如String endpoint = "sts.cn-hangzhou.aliyuncs.com"。* 更多信息，请参见步骤五：获取临时访问凭证。* https://help.aliyun.com/document_detail/100624.html?spm=api-workbench.Troubleshoot.0.0.5ba77185ILElOT#section-5xa-zdn-s0q*/private String endpoint;private String bucket;/*** RAM 访问控制/身份管理/角色/ARN属性值*/private String roleArn;private String region;
}

配置OSS

这个在官方文档中有很详细的教程，不多赘述

服务端代码

服务端最主要的事情：使用STS生成一个临时的凭证给客户端使用；客户端拿到该临时凭证就可以直接将文件上传至OSS

初始化STS Client

这里有个点需要注意：endpoint 需要添加sts.前缀,
考虑到STS Client只需要初始化一次，所以将其注册为一个Bean

@Beanpublic com.aliyun.sts20150401.Client ossStsClient() throws Exception {// 工程代码泄露可能会导致 AccessKey 泄露，并威胁账号下所有资源的安全性。以下代码示例仅供参考。com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()// 必填，请确保代码运行环境设置了环境变量 OSS_ACCESS_KEY_ID。.setAccessKeyId(aliOSSProp.getAccessKeyId())// 必填，请确保代码运行环境设置了环境变量 OSS_ACCESS_KEY_SECRET。.setAccessKeySecret(aliOSSProp.getSecretAccessKey());// Endpoint 请参考 https://api.aliyun.com/product/Sts// 确保获取临时访问凭证时Endpoint使用STS域名config.endpoint = "sts."+aliOSSProp.getEndpoint();return new com.aliyun.sts20150401.Client(config);}

获取STS临时凭证

这部分没有什么需要注意的点，可以完全照搬

import com.aliyun.sts20150401.models.AssumeRoleResponseBody;
import com.aliyun.oss.OSSException;/*** 获取STS临时凭证* @return AssumeRoleResponseBodyCredentials 对象*/private AssumeRoleResponseBody.AssumeRoleResponseBodyCredentials getCredential(){com.aliyun.sts20150401.models.AssumeRoleRequest assumeRoleRequest = new com.aliyun.sts20150401.models.AssumeRoleRequest()// 必填，请确保代码运行环境设置了环境变量 OSS_STS_ROLE_ARN.setRoleArn(aliOSSProp.getRoleArn()).setRoleSessionName("idooyRoleSessionName");// 自定义会话名称com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();try {// 复制代码运行请自行打印 API 的返回值com.aliyun.sts20150401.models.AssumeRoleResponse response = ossStsClient.assumeRoleWithOptions(assumeRoleRequest, runtime);// credentials里包含了后续要用到的AccessKeyId、AccessKeySecret和SecurityToken。return response.body.credentials;} catch (TeaException error) {// 此处仅做打印展示，请谨慎对待异常处理，在工程项目中切勿直接忽略异常。// log.error("STS方式获取临时凭证失败原因===》{}",error.getMessage());throw new OSSException("STS方式获取临时凭证失败原因===》"+error.getMessage());} catch (Exception e) {throw new OSSException(e.getMessage());}}

创建policy计算SigningKey

这部分的代码很长，但是注释很清晰；当然也不需要完全搞懂，照搬就好。

• 这部分代码中的魔法值(String字面量)要小心，别无意间给修改或者给粘错了
• 这部分使用了三种日期格式，分别是：“yyyyMMdd’T’HHmmss’Z’”、“yyyyMMdd”、“yyyy-MM-dd’T’HH:mm:ss.SSS’Z’”。注意区分
• uploadDir 变量值请自定义修改
• 官方直接将结果塞进了map中，本文将其封装为了一个DTO对象

@Resourceprivate com.aliyun.sts20150401.Client ossStsClient;/***     指定过期时间，单位为秒。*/private static final Long EXPIRE_TIME = 3600L;private static final String TIME_FORMAT_PATTERN_1 = "yyyyMMdd'T'HHmmss'Z'";/*** 定义日期时间格式*/private static final String TIME_FORMAT_PATTERN_2 = "yyyyMMdd";@ResourceAliOSSProp aliOSSProp;/*** 还是“服务端验签web端直传的方式”只不过采用了更加安全的STS方式* @return*/@Overridepublic STSPolicyDTO getSTSUploadPolicy() throws JsonProcessingException {String host = "https://" + aliOSSProp.getBucket() + "." + aliOSSProp.getEndpoint();// 设置上传到OSS文件的前缀，可置空此项。置空后，文件将上传至Bucket的根目录下;每一天产生一个文件夹// brand/是自定义目录String uploadDir = "brand/"+LocalDate.now();String region = aliOSSProp.getRegion();// 临时的凭证信息AssumeRoleResponseBody.AssumeRoleResponseBodyCredentials credential = getCredential();String accessKeyId =  credential.getAccessKeyId();String accessKeySecret =  credential.getAccessKeySecret();String securityToken =  credential.getSecurityToken();//获取x-oss-credential里的date，当前日期，格式为yyyyMMddZonedDateTime today = ZonedDateTime.now().withZoneSameInstant(ZoneOffset.UTC);DateTimeFormatter formatter = DateTimeFormatter.ofPattern(TIME_FORMAT_PATTERN_2);String date = today.format(formatter);//获取x-oss-dateZonedDateTime now = ZonedDateTime.now().withZoneSameInstant(ZoneOffset.UTC);DateTimeFormatter formatter2 = DateTimeFormatter.ofPattern(TIME_FORMAT_PATTERN_1);String x_oss_date = now.format(formatter2);// 步骤1：创建policy。String x_oss_credential = accessKeyId + "/" + date + "/" + region + "/oss/aliyun_v4_request";ObjectMapper mapper = new ObjectMapper();Map<String, Object> policy = new HashMap<>();policy.put("expiration", OSSUtil.generateExpiration(EXPIRE_TIME));List<Object> conditions = new ArrayList<>();Map<String, String> bucketCondition = new HashMap<>();bucketCondition.put("bucket", aliOSSProp.getBucket());conditions.add(bucketCondition);Map<String, String> securityTokenCondition = new HashMap<>();securityTokenCondition.put("x-oss-security-token", securityToken);conditions.add(securityTokenCondition);Map<String, String> signatureVersionCondition = new HashMap<>();signatureVersionCondition.put("x-oss-signature-version", "OSS4-HMAC-SHA256");conditions.add(signatureVersionCondition);Map<String, String> credentialCondition = new HashMap<>();credentialCondition.put("x-oss-credential", x_oss_credential); // 替换为实际的 access key idconditions.add(credentialCondition);Map<String, String> dateCondition = new HashMap<>();dateCondition.put("x-oss-date", x_oss_date);conditions.add(dateCondition);conditions.add(Arrays.asList("content-length-range", 1, 10240000));conditions.add(Arrays.asList("eq", "$success_action_status", "200"));conditions.add(Arrays.asList("starts-with", "$key", uploadDir));policy.put("conditions", conditions);String jsonPolicy = mapper.writeValueAsString(policy);// 步骤2：构造待签名字符串（StringToSign）。// String stringToSign = new String(Base64.encodeBase64(jsonPolicy.getBytes()));String stringToSign = cn.hutool.core.codec.Base64.encode(jsonPolicy.getBytes());// System.out.println("stringToSign: " + stringToSign);// 步骤3：计算SigningKey。byte[] dateKey = OSSUtil.getHmacSHA256(("aliyun_v4" + accessKeySecret).getBytes(), date);byte[] dateRegionKey = OSSUtil.getHmacSHA256(dateKey, region);byte[] dateRegionServiceKey = OSSUtil.getHmacSHA256(dateRegionKey, "oss");byte[] signingKey = OSSUtil.getHmacSHA256(dateRegionServiceKey, "aliyun_v4_request");// System.out.println("signingKey: " + BinaryUtil.toBase64String(signingKey));// 步骤4：计算Signature。byte[] result = OSSUtil.getHmacSHA256(signingKey, stringToSign);String signature = BinaryUtil.toHex(result);return new STSPolicyDTO().setPolicy(stringToSign).setX_oss_credential(x_oss_credential).setX_oss_date(x_oss_date).setSignature(signature).setSecurity_token(securityToken).setDir(uploadDir).setHost(host);}

OSSUtil.java

public class OSSUtil {private OSSUtil() {}/*** 定义日期时间格式，例如2023-12-03T13:00:00.000Z*/public static final String TIME_FORMAT_PATTERN = "yyyy-MM-dd'T'HH:mm:ss.SSS'Z'";public static byte[] getHmacSHA256(byte[] key, String data) {try {// 初始化HMAC密钥规格，指定算法为HMAC-SHA256并使用提供的密钥。SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");// 获取Mac实例，并通过getInstance方法指定使用HMAC-SHA256算法。Mac mac = Mac.getInstance("HmacSHA256");// 使用密钥初始化Mac对象。mac.init(secretKeySpec);// 执行HMAC计算，通过doFinal方法接收需要计算的数据并返回计算结果的数组。byte[] hmacBytes = mac.doFinal(data.getBytes());return hmacBytes;} catch (Exception e) {throw new RuntimeException("Failed to calculate HMAC-SHA256", e);}}/*** 通过指定有效的时长（秒）生成过期时间。** @param seconds 有效时长（秒）。* @return ISO8601 时间字符串，如："2014-12-01T12:00:00.000Z"。*/public static String generateExpiration(long seconds) {// 获取当前时间戳（以秒为单位）long now = Instant.now().getEpochSecond();// 计算过期时间的时间戳long expirationTime = now + seconds;// 将时间戳转换为Instant对象，并格式化为ISO8601格式Instant instant = Instant.ofEpochSecond(expirationTime);// 定义时区为UTCZoneId zone = ZoneOffset.UTC;// 将 Instant 转换为 ZonedDateTimeZonedDateTime zonedDateTime = instant.atZone(zone);// 定义日期时间格式，例如2023-12-03T13:00:00.000ZDateTimeFormatter formatter = DateTimeFormatter.ofPattern(TIME_FORMAT_PATTERN);// 格式化日期时间String formattedDate = zonedDateTime.format(formatter);// 输出结果return formattedDate;}}

STSPolicyDTO.java

@Getter
@Setter
@Accessors(chain = true)
public class STSPolicyDTO {/*** 官方代码示例中给的“"OSS4-HMAC-SHA256"”*/private String version="OSS4-HMAC-SHA256";private String policy;private String x_oss_credential;private String x_oss_date;private String signature;private String security_token;private String dir;private String host;
}

提供接口

@RestController
@RequestMapping("/oss")
@Api("OSS文件上传验签")
public class AliOSSController {final AliOSSService ossService;public AliOSSController(AliOSSService ossService) {this.ossService = ossService;}/*** oss上传文件：使用服务端验签web直传的方式* 该接口提供web直传所必须的验签信息* 文档地址：https://help.aliyun.com/zh/oss/use-cases/obtain-signature-information-from-the-server-and-upload-data-to-oss?spm=a2c4g.11186623.help-menu-31815.d_6_1_0_0.386b4acdkrwKDc&scm=20140722.H_31926._.OR_help-T_cn~zh-V_1* @return*/@GetMapping("policy")@ApiOperation("STS验签V4版")public R<STSPolicyDTO> policy() throws JsonProcessingException {// UploadPolicyDTO uploadPolicy = ossService.getUploadPolicy();STSPolicyDTO uploadPolicy = ossService.getSTSUploadPolicy();return R.ok().data(uploadPolicy);}}

接口的响应数据示例

{"success": true,"code": 2000,"message": "成功","data": {"version": "OSS4-HMAC-SHA256","policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wNy0zMFQxNToyMjowNy4wMDBaIiwiY29uZGl0aW9ucyI6W3siYnVja2V0IjoiaWRvb3ktbWFsbCJ9LHsieC1vc3Mtc2VjdXJpdHktdG9rZW4iOiJDQUlTelFKMXE2RnQ1QjJ5ZlNqSXI1blFFZXo1aDVzVjRZYXpZM1BjZ1ZFZGFkcGl2cFB5aWp6MklIaE1lWEJoQStrZHR2b3duMnBaN3Z3Y2xyMXlSNWhDVkhiRGFjWkw0NDlNOEFTblJZUEV0cFFiWm1DelpjYjNkMUtJQWp2WGdlWHdBWXlnUHY2L0Y5NnBiMWZiN0Z3UnBaTHhhVFNsV1hHOExKU05rdVFKUjk4TFh3NitIMUVrYlpVc1VXa0Vrc0lCTW1iTFB2dUFLd1BqaG5HcWJIQmxvUTFoazJoeW04L2RxNCsra2tPRzBnU2xsYkJPKzltdWNzUDdNWmxXVWMwaEE0dnY3b3RmYmJIYzFTTmMwUjlPK1pwdGdiWk1rVFc5NVluRlhnQUF1VXpkYTdTTHFZYytkRlVuZk00OUFMVUJzL1gyME9CZ3Z1dmFtNVJIYk9USnNUek1PczYyWmZkRG9LT3NjSXZCWHI2eUpRamxvSElPQzZpd0xHL3pxUzBtVjJBNTlmOG1GQ0haMG9hWjZOSDlvOXdiODBKR0ZZRURvL1phcHNKdXFzSkpPdUtlcEE2QVZ0VW44QVhuSzkwYWdBRWloRDByMzE0TnNadUp6UHFkbkF3aUVXWjhWdWFvWlZUUzl0eTdmTW1vUTRIaGsrODE3U3BqeWVvMloycGo3T21zaFVWRmpKNFN5cjVsMWo2VFM3aVBqcFZlRG1xZjhtZ0tRc2F0bFdReHFwdk9MQmIray9QTktNei9kRXA4RFF3clg3S2x6b1RVRTA4bndKK0dqeEFFd0FkVWh3blBBbk14dVlXTEZrdUtZQ0FBIn0seyJ4LW9zcy1zaWduYXR1cmUtdmVyc2lvbiI6Ik9TUzQtSE1BQy1TSEEyNTYifSx7Ingtb3NzLWNyZWRlbnRpYWwiOiJTVFMuTlplWlZNakQ0VkRYYVVtZVFIZVVOUVZZaC8yMDI1MDczMC9jbi1jaGVuZ2R1L29zcy9hbGl5dW5fdjRfcmVxdWVzdCJ9LHsieC1vc3MtZGF0ZSI6IjIwMjUwNzMwVDE0MjIwN1oifSxbImNvbnRlbnQtbGVuZ3RoLXJhbmdlIiwxLDEwMjQwMDAwXSxbImVxIiwiJHN1Y2Nlc3NfYWN0aW9uX3N0YXR1cyIsIjIwMCJdLFsic3RhcnRzLXdpdGgiLCIka2V5IiwiYnJhbmQvMjAyNS0wNy0zMCJdXX0=","x_oss_credential": "STS.NZeZVMjD4VDXaUmeQHeUNQVYh/20250730/cn-chengdu/oss/aliyun_v4_request","x_oss_date": "20250730T142207Z","signature": "e583ba3040d9ac4544b4008f7193edf30fdef75cca6d4ca0e449150cf4904165","security_token": "CAISzQJ1q6Ft5B2yfSjIr5nQEez5h5sV4YazY3PcgVEdadpivpPyijz2IHhMeXBhA+kdtvown2pZ7vwclr1yR5hCVHbDacZL449M8ASnRYPEtpQbZmCzZcb3d1KIAjvXgeXwAYygPv6/F96pb1fb7FwRpZLxaTSlWXG8LJSNkuQJR98LXw6+H1EkbZUsUWkEksIBMmbLPvuAKwPjhnGqbHBloQ1hk2hym8/dq4++kkOG0gSllbBO+9mucsP7MZlWUc0hA4vv7otfbbHc1SNc0R9O+ZptgbZMkTW95YnFXgAAuUzda7SLqYc+dFUnfM49ALUBs/X20OBgvuvam5RHbOTJsTzMOs62ZfdDoKOscIvBXr6yJQjloHIOC6iwLG/zqS0mV2A59f8mFCHZ0oaZ6NH9o9wb80JGFYEDo/ZapsJuqsJJOuKepA6AVtUn8AXnK90agAEihD0r314NsZuJzPqdnAwiEWZ8VuaoZVTS9ty7fMmoQ4Hhk+817Spjyeo2Z2pj7OmshUVFjJ4Syr5l1j6TS7iPjpVeDmqf8mgKQsatlWQxqpvOLBb+k/PNKMz/dEp8DQwrX7KlzoTUE08nwJ+GjxAEwAdUhwnPAnMxuYWLFkuKYCAA","dir": "brand/2025-07-30","host": "目标bucket的公网访问域名"}
}

Apifox模拟Web端文件直传

文件上传的地址，就是你自己目标bucket的公网访问域名，也可以直接从上面接口的响应字段host获取,这部分就是结合自己的前端项目自行开发。将上传的参数名称做个简单的说明。
请求参数名称：

{"success_action_status", "200""policy", data.policy"x-oss-signature", data.signature"x-oss-signature-version", "OSS4-HMAC-SHA256""x-oss-credential", data.x_oss_credential"x-oss-date", data.x_oss_date"key", data.dir + file.name // 文件名"x-oss-security-token", data.security_token"file", file); // file 必须为最后一个表单域
}                

没啥文章功底，主要是站在自己的角度一通记录而已；多包涵，欢迎在评论区讨论共同学习。