In addition to adding 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 Number Yes The time when the signed URL expires. The value of this parameter is a , which is the number of seconds that have elapsed since January 1, 1970 00:00:00 UTC. If a request timeout error is returned, the time when OSS receives the request is later than the value of this parameter that is included in the signature. For example, the current time is 1141889060. 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 modify 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 sample 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 add 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 Expires value, 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 a temporary credential provided by STS to access OSS. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain temporary access credentials. A temporary access credential contains a security token and a temporary AccessKey pair that 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 Number 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 parameter value 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 is allowed to be forwarded. Default value: false. If the x-oss-ac-forward-allow and X-Forwarded-For parameters are included in the request, the X-Forwarded-For value is used to verify the signature. The X-Forwarded-For parameter may be specified as multiple IP addresses.
    Valid values:
    • true: The request is allowed to be forwarded.
      Notice This may cause the request header to be tampered with.
    • false: The request is not allowed to be forwarded.
  • Sample Python code used to generate a signature
    • Example 1 (Only required parameters contained)
      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 (Optional parameters contained)
      • When you sign a URL, you must sort the optional parameters in alphabetical order. If you do not need some of the parameters, leave them empty.
      • If you want to specify an IP address for access, you need only to set 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()

Implementation methods by using OSS SDKs

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

SDKs

You can use OSS SDKs for the following programming languages to generate a signed URL for object upload and download:

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 Expires value 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.