In addition to adding signatures to the Authorization header of requests, you can also add signatures 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 information about the data can be obtained by all users on the Internet within the validity period of the signed URL. We recommend that you evaluate the risks in advance.
  • If a request contains a URL, signatures cannot be added to the Authorization header of the request and the URL at the same time.
  • You can add signatures to URLs that are contained in PUT and GET requests.
  • You can generate a presigned URL for a PUT request to check whether the content to upload is valid. When you use OSS SDKs to generate a presigned URL for a request, OSS SDKs calculate the MD5 hash of the request body and include the MD5 hash in the presigned URL. The MD5 hash of the uploaded content must be the same as the MD5 hash calculated by OSS SDKs. Otherwise, the request fails. To verify the MD5 hash of the uploaded content, add the Content-MD5 header in the request.

Implementation methods

  • Example of a signed URL:
    http://oss-example.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2pc56s936****&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****
    To use a temporary access credential provided by Security Token Service (STS) to generate a signed URL, you must add the security-token parameter in the signature. The following example shows a URL that is signed by using an access credential provided by STS:
    http://oss-example.oss-cn-hangzhou.aliyuncs.com/oss-api.pdf?OSSAccessKeyId=nz2pc56s936****&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv****&security-token=SecurityToken
  • Parameters
    Parameter Required Description
    Expires 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 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, the current time is 1141889060. To create a URL that is valid within 60 seconds, you can set the value of this parameter to 1141889120.
    Note For security reasons, the validity period of a signed URL that is generated by using the OSS console is 3,600 seconds by default. The maximum value of the validity period is 32,400 seconds.
    OSSAccessKeyId Yes The AccessKey ID used to access OSS.
    Signature Yes The signature information that you want to add to the URL.
    The signature information is in the following format:
    Signature = urlencode(base64(hmac-sha1(AccessKeySecret,
              VERB + "\n" 
              + CONTENT-MD5 + "\n" 
              + CONTENT-TYPE + "\n" 
              + EXPIRES + "\n" 
              + CanonicalizedOSSHeaders
              + CanonicalizedResource)))

    The headers and algorithm used to calculate the signature that you want to add to a URL are similar to those used to calculate the signature that you want to add to the Authorization header of a request.

    When you calculate the signature string that you want 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 Add signatures to the Authorization header.

    The signature string added to a URL must be URL-encoded. If the value of Signature, Expires, and 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 the Expires header, and then verifies the signature.

    security-token No The security token provided by STS. You must configure this parameter only when you use a temporary access credential to sign the URL.
    Note For more information about how to set up STS, see Use a temporary credential provided by STS to access OSS in OSS Developer Guide. You can call the AssumeRole operation or use STS SDKs for various programming languages to obtain a temporary access credential. The temporary access credential contains a security token and a temporary AccessKey pair that consists of an AccessKey ID and an AccessKey secret.
  • Use OSS SDKs to generate a signed URL
    The following code provides an example on how to generate a signed URL in Python:
    import base64
    import hmac
    import hashlib
    import urllib
    h = hmac.new("OtxrzxIsfpFjA7SwPzILwy8Bw21TLhquhboDYROV",
                 "GET\n\n\n1141889120\n/oss-example/oss-api.pdf",
                 hashlib.sha1)
    urllib.quote (base64.encodestring(h.digest()).strip())
    The following table describes the methods used by OSS SDKs to generate a signed URL and provides sample files.
    SDK Method Sample file
    Java SDK OSSClient.generatePresignedUrl OSSClient.java
    Python SDK Bucket.sign_url api.py
    .Net SDK OssClient.GeneratePresignedUri OssClient.cs
    PHP SDK OssClient.signUrl OssClient.php
    JavaScript SDK signatureUrl Object.js
    C SDK oss_gen_signed_url oss_object.c
    C++ SDK OssClient::GeneratePresignedUrl OssClient.cc

SDK

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 one or more of the Signature, Expires, and OSSAccessKeyId parameters are missing. When a signature is added to a URL, the sequence of the Signature, Expires, and OSSAccessKeyId parameters can be swapped.
AccessDenied 403 Forbidden The error message returned because the access time of the request is later than the value of Expires in the request, or the time format of the request is invalid.
InvalidArgument 400 Bad Request The error message returned because one or more of the Signature, Expires, and OSSAccessKeyId parameters are included in the signed URL and in the request header at the same time.