You can add a signature to the Authorization header of a request. You can also add a signature to the URL of an Object Storage Service (OSS) resource and share the URL to allow authorized third-party users to access the resource.

Usage notes

  • If you use a signed URL to share data, the data can be accessed by all users on the Internet within the validity period of the signed URL. We recommend that you assess the risks in advance.
  • OSS does not allow you to contain a signature in the URL of a specific resource and in the Authorization header of a request for the resource at the same time.
  • You can add signatures to URLs so that third-party users can use the signed URLs to initiate PUT and GET requests.
  • You can generate a presigned URL for a PUT request to check whether the intended content is uploaded. If you use an OSS SDK to generate a presigned URL for a request, the OSS SDK calculates the MD5 hash of the request body and includes the MD5 hash in the presigned URL. The MD5 hash of the uploaded content must be the same as the MD5 hash calculated by the OSS SDK. Otherwise, the PUT request fails. To verify the MD5 hash of the uploaded content, add the Content-MD5 header to the request.

Implementation methods

  • Examples of signed URLs
    https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2pc56s936****&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****
    If you want to use temporary access credentials obtained from Security Token Service (STS) to generate a signed URL, you must include the security-token parameter in the signature.
    https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2pc56s936****&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****&security-token=CAISowJ1q6Ft5B2yfSjIr5bgIOz31blR9oWmWBfCs3kDR/xm3Imc1zz2IHxMdHJsCeAcs/Q0lGFR5/sflqJIRoReREvCUcZr8szfWcsZos2T1fau5Jko1be0ewHKeQKZsebWZ+LmNpy/Ht6md1HDkAJq3LL+bk/Mdle5MJqP+/kFC9MMRVuAcCZhDtVbLRcYgq18D3bKMuu3ORPHm3fZCFES2jBxkmRi86+ysIP+phPVlw/90fRH5dazcJW0Zsx0OJo6Wcq+3+FqM6DQlTNM6hwNtoUO1fYUommb54nDXwQIvUjfbtC5qIM/cFVLAYEhALNBofTGkvl1h/fejYyfyWwWYbkFCHiPFNr9kJCUSbr4a4sjF6zyPnPWycyCLYXleLzhxPWd/2kagAGaXG69BqwYNvrKKI3W8weP3bNc1wQDMXQfiHpFCRG6lYhh3iXFtpwH90A3sTlxzRGvi8+9p63JwrluOHWs+Fj6S6s0cOhKvKRWYE8UuWeXIvv4l6DAGwHDE8BLjLC11f5prUJgI2wb+3hwuBod32Jx+us/1p996Glao725orcb****

    You can add an IP address, a CIDR block, or a virtual private cloud (VPC) ID to the signed URL to prevent unauthorized terminals from accessing the shared OSS resources.

    https://examplebucket.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?&OSSAccessKeyId=44CF9590006BF252F707&Expires=1475462111&Signature=OjxkTUbT6rXCZcW8QhvlrXQr8vsP80EFdo6oG5qsBx****&x-oss-ac-subnet-mask=32
  • Parameters
    Parameter Type Required Description
    OSSAccessKeyId STRING Yes The AccessKey ID used in the signed URL.
    Expires NUMERIC Yes The time when the signed URL expires. The value of this parameter is a UNIX timestamp, which is the number of seconds that have elapsed since 00:00:00 Thursday, January 1, 1970. If the time when OSS receives the request that contains the URL is later than the value of this parameter that is included in the signature, a request timeout error is returned. For example, if the current time is 1141889060 and you want to create a URL that is valid within 60 seconds, you must set this parameter to 1141889120.
    Note For security reasons, the default validity period of URLs generated in the OSS console is set to 3,600 seconds and the maximum validity period is set to 32,400 seconds. For more information about how to change the validity period of a URL, see Share objects.
    Signature STRING Yes The signature information that you want to add to the URL. The following code provides an example on the valid format:
    Signature = urlencode(base64(hmac-sha1(AccessKeySecret,
              VERB + "\n" 
              + CONTENT-MD5 + "\n" 
              + CONTENT-TYPE + "\n" 
              + EXPIRES + "\n" 
              + CanonicalizedOSSHeaders
              + CanonicalizedResource)))
    • In OSS, the algorithm used to calculate the signature added to a URL is similar to that used to calculate the signature added to the Authorization header of a request.
    • When you calculate the signature string to be added to a URL, the Content-Type, Content-MD5, and CanonicalizedOSSHeaders headers are the same as those used to calculate the signature that you add to the Authorization header. However, you must replace the Date header with Expire in the signature string. You can include the Date header in the request. For more information about the headers, see Include signatures in the Authorization header.
    • You must encode a URL when you add a signature to the URL. If the value of Signature, Expires, or OSSAccessKeyId is imported multiple times, the first imported value is used.
    • If a request contains a signed URL, OSS first checks whether the time when the request is received is later than the value of Expires, and then verifies the signature.
    security-token STRING No The security token that is obtained from STS. You must configure this parameter only if you use temporary access credentials to sign the URL.
    Note For more information about how to configure STS, see Use temporary credentials provided by STS to access OSS. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential. Temporary access credentials contain a security token and a temporary AccessKey pair. The AccessKey pair consists of an AccessKey ID and an AccessKey secret.
    x-oss-ac-source-ip STRING No The specified IP address or CIDR block. This parameter must be used together with x-oss-ac-subnet-mask that specifies the subnet mask.
    x-oss-ac-subnet-mask NUMERIC No The number of 1's in the subnet mask. If this parameter is contained in the signed URL, OSS performs the AND operation based on the IP address from which the request is sent and the subnet mask. The result of the operation is used for signature verification. If the value of the parameter is maliciously modified, the signature cannot pass the verification.
    x-oss-ac-vpc-id STRING No The VPC ID. This parameter is used to determine whether the request is sent over the specified VPC. If the request is sent over the specified VPC, OSS verifies the VPC ID and the IP address or CIDR block from which the request is sent.
    x-oss-ac-forward-allow BOOLEAN No Specifies whether the request can be forwarded. If the x-oss-ac-forward-allow and X-Forwarded-For parameters are included in the request, the value of the X-Forwarded-For parameter is used to verify the signature. Multiple IP addresses may be specified in the X-Forwarded-For parameter. Default value: false.
    Valid values:
    • true: The request can be forwarded.
      Important This may cause the request header to be tampered with.
    • false: The request cannot be forwarded.
  • Sample Python code used to generate a signature
    • Example 1 (Only required parameters)
      Note The following sample code uses Secure Hash Algorithm 1 (SHA1) to generate a signature.
      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())
    • Example 2 (Including optional parameters)
      Important The following sample code uses the SHA256 algorithm in the SHA2 family. SHA256 is more secure and provides more flexible signing capabilities. You can add a specific request header in the signature to improve security.
      • Before you sign a URL, you must sort the optional parameters in alphabetical order. You can leave optional parameters empty based on your business requirements.
      • If you want to specify an IP address from which the access request is sent, you can specify the x-oss-ac-source-ip and x-oss-ac-subnet-mask parameters. Examples: x-oss-ac-source-ip=127.0.0.1 and x-oss-ac-subnet-mask=32.
      import base64
      import hmac
      import hashlib
      import urllib
      h = hmac.new(accesskey,
                   "GET\n\n\n1141889120\n%2Fexamplebucket%2Foss-api.pdf?\
                   &x-oss-ac-forward-allow=true\
                   &x-oss-ac-source-ip=127.0.0.1\
                   &x-oss-ac-subnet-mask=32\
                   &x-oss-signature-version=OSS2",
                   hashlib.sha256)
      Signature = base64.encodestring(h.digest()).strip()

SDKs

The following table describes the implementation methods to add signatures to a URL by using OSS SDKs for programming languages and provides links to sample code of uploading or downloading objects by using signed URLs.

SDK Method Sample code References
Java SDK OSSClient.generatePresignedUrl AuthorizedAccessSample.java Java
Python SDK Bucket.sign_url sts.py Python
PHP SDK OssClient.signUrl Signature.php PHP
Node.js SDK Url signatureUrl.js Node.js
Browser.js SDK Url signatureUrl.js Browser.js
Android SDK OSSClient.presignConstrainedObjectURL OSSClient.java Android
iOS SDK presignConstrainURLWithBucketName:withObjectKey:httpMethod:withExpirationInterval:withParameters OSSClient.h iOS
Go SDK signURL sign_url.go Go
C SDK oss_gen_signed_url oss_object.c C
C++ SDK OssClient::GeneratePresignedUrl OssClient.cc C++
.Net SDK OssClient.GeneratePresignedUri UrlSignatureSample.cs .NET

Error codes

Error code Error message Description
AccessDenied 403 Forbidden The error message returned because at least one of the Signature, Expires, and OSSAccessKeyId parameters is missing. When a signature is added to a URL, the sequence of the Signature, Expires, and OSSAccessKeyId parameters can be changed.
AccessDenied 403 Forbidden The error message returned because the access time of the request is later than the value of the Expires parameter specified in the request, or the time format of the request is invalid.
InvalidArgument 400 Bad Request The error message returned because at least one of the Signature, Expires, and OSSAccessKeyId parameters is included in the URL, and the signature information is also included in the request header.