文档

在URL中包含V1签名

更新时间:

除了通过HTTP请求头部的Authorization字段进行签名授权外,您还可以生成一个包含签名和其他必要的请求信息的预签名URL。通过这种方式,您可以在不透露访问凭证的情况下,授予第三方在特定有效期内对OSS资源的访问权限。本文介绍如何使用V1签名算法实现在URL中包含签名。

重要

OSS支持更安全的V4签名算法,建议您使用V4签名。更多信息,请参见V4签名

SDK签名实现

OSS SDK已自动实现V1签名,您使用OSS SDK时无需关注签名问题。如果您想了解具体语言的签名实现,请参考OSS SDK的代码。OSS SDK签名实现的文件请参见下表。

SDK

签名实现

使用示例

Java

OSSV1Signer.java

Java

PHP

SignerV1.php

PHP

Node.js

signatureUrl.js

Node.js

Browser.js

Browser.js

Python

auth.py

Python

Android

ObjectURLPresigner.java

Android

iOS

OSSClient.m

iOS

Go

v1.go

Go

C++

SignerV1.cc

C++

C

oss_auth.c

C

.Net

OssClient.cs

.NET

Ruby

bucket.rb

Ruby

注意事项

  • 使用在URL中签名的方式,会将授权的数据在过期时间内暴露在互联网上,请预先评估使用风险。

  • OSS不支持同时在URL和Header中包含签名。

  • 您可以为PUT操作生成一个预签名的URL,该URL用于检查是否上传了正确的内容。SDK对请求进行预签名时,将计算请求正文的校验和,并生成包含在预签名URL中的MD5校验和。用户必须上传与SDK生成的MD5校验和相同的内容,否则操作失败。如果要验证MD5,只需在请求中增加Content-MD5头即可。

签名实现

  • 签名示例

    https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2p***********&Expires=1141889120&Signature=****Pxyb****mGa%****272YEAiv****

    如果需要使用STS用户构造URL签名,则必须携带security-token

    https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2p***********&Expires=1141889120&Signature=****Pxyb****mGa%****272YEAiv****&security-token=CAIS****q6Ft5B2yfSjIr****Oz31blR9oWmWBf****DR/xm3Imc****IHxMdHJsCeAcs/Q0lGFR5/sflqJIR****EvCUcZr8szfWcsZos2****u5Jko1be0ewHKeQKZsebWZ+LmNpy/Ht6md1HDkAJq3LL+bk/Mdle5MJqP+/kFC9MMRVuAcCZhDtVbLRcYgq18D3bKMuu3ORPHm3fZCFES2jBxkmRi86+ysIP+phPVlw/90fRH5dazcJW0Zsx0OJo6Wcq+3+FqM6DQlTNM6hwNtoUO1fYUommb54nDXwQIvUjfbtC5qIM/cFVLAYEhAL****TGkvl1h/fejYyfyW****kFCHiPF****JCUSbr4a4sjF6zyPnPWycyCLYXleLzhxPWd/2kagAGaXG69BqwYNvrKKI3W8****bNc1wQDMXQfiHpFCRG6lYhh3****pwH90A3sTlxzRGvi8+****JwrluOHWs+Fj6S6s0cOhKvKRWYE8UuWeXIvv4l6DAGwH****LjLC11f5prUJ****b+3hwuBod32Jx+us/1p996Glao725orcb****

    您可以在签名URL中添加想要授权的IP地址、IP地址段或VPC ID,避免未授权的终端访问OSS资源。

    https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?&OSSAccessKeyId=44CF****************&Expires=1475462111&Signature=77Dv****************&x-oss-ac-subnet-mask=32
  • 参数说明

    名称

    类型

    是否必选

    描述

    OSSAccessKeyId

    字符串

    指定URL签名中使用的AccessKey ID。

    Expires

    数字

    Unix时间戳(自UTC时间1970年01月01号开始的秒数),用于标识该URL的超时时间,单位为秒。如果OSS接收到该URL请求的时间晚于签名中包含的Expires参数时,则返回请求超时的错误码。例如,当前时间是1141889060,开发者希望创建一个60秒后自动失效的URL,则可以设置Expires时间为1141889120。

    说明

    出于安全考虑,OSS控制台中默认URL的有效时间为3600秒,最大值为32400秒。关于修改URL超时时间的具体操作,请参见使用文件URL

    Signature

    字符串

    签名信息。格式如下:

    Signature = urlencode(base64(hmac-sha1(AccessKeySecret,
              VERB + "\n" 
              + CONTENT-MD5 + "\n" 
              + CONTENT-TYPE + "\n" 
              + EXPIRES + "\n" 
              + CanonicalizedOSSHeaders
              + CanonicalizedResource)))
    • 所有OSS支持的请求和各种Header参数,在URL中进行签名的算法和在Header中包含签名的算法类似。

    • 生成URL中的签名字符串时,除了将Date参数替换为Expires参数外,仍然包含CONTENT-TYPECONTENT-MD5CanonicalizedOSSHeaders签名版本1中定义的Header(请求中虽然仍有Date请求Header,但无需将Date加入签名字符串中)。

    • 在URL中包含签名时必须对URL进行编码。如果在URL中多次传入Signature、Expires或OSSAccessKeyId,则以第一次传入的值为准。

    • 使用URL签名时,OSS会先验证请求时间是否晚于Expires时间,然后再验证签名。

    security-token

    字符串

    安全令牌。只有当使用STS用户构造URL签名时,才需要设置此参数。

    说明

    关于搭建STS服务的具体操作,请参见使用STS临时访问凭证访问OSS。您可以通过调用STS服务的AssumeRole接口或者使用各语言STS SDK来获取临时访问凭证。临时访问凭证包括临时访问密钥(AccessKey ID和AccessKey Secret)和安全令牌(SecurityToken)。

    x-oss-ac-source-ip

    字符串

    指定IP地址或者IP地址段。

    重要
    • 该参数只需要在生成signature时使用,不需要在URL中携带该参数。

    • 如果在生成签名时添加了IP地址或IP地址段,则需要传递参数x-oss-ac-subnet-mask,用于标记子网掩码。

    x-oss-ac-subnet-mask

    数字

    子网掩码中1的个数。如果请求中携带该参数,OSS会将实际请求IP地址与子网掩码进行求与,然后用于计算签名是否正确。如果该参数被恶意篡改,将导致签名无法校验通过。

    x-oss-ac-vpc-id

    字符串

    指定VPC ID。指定该参数后,OSS会判断是否为对应VPC ID来源的请求。如果请求是从该VPC ID发起且该参数已赋值,则同时校验VPC ID和来源IP地址或IP地址段。

    x-oss-ac-forward-allow

    布尔型

    指定是否允许转发请求。OSS如果检测到该字段并且请求中带有X-Forwarded-For(可能为多个IP地址),则将X-Forwarded-For的值用于计算签名校验。

    取值如下:

    • true:表示允许转发请求。

      重要

      设置为true存在请求头被篡改劫持的风险。

    • false(默认值):不允许转发请求。

  • 生成签名的Python示例代码(只涉及必选参数)

    import base64
    import hmac
    import hashlib
    import urllib
    h = hmac.new("accesskey",
                 "GET\n\n\n1141889120\n/examplebucket/oss-api.pdf",
                 hashlib.sha1)
    urllib.quote(base64.encodestring(h.digest()).strip())

错误码

错误码

返回消息

描述

AccessDenied

403 Forbidden

在URL中添加签名时,Signature、Expires和OSSAccessKeyId顺序可以调换,但不能缺少Signature、Expires或OSSAccessKeyId中的一个或者多个。

AccessDenied

403 Forbidden

访问的当前时间晚于请求中设定的Expires时间或时间格式错误。

InvalidArgument

400 Bad Request

URL中包含Signature、Expires、OSSAccessKeyId中的一个或者多个,并且Header中也包含签名消息。