This topic describes how to use temporary access credentials provided by Security Token Service (STS) or a signed URL to temporarily access Object Storage Service (OSS) resources.

Important A validity period must be specified for temporary access credentials and a signed URL. When you use temporary access credentials to generate a signed URL that is used to perform operations, such as object upload and download, the minimum validity period takes precedence. For example, you can set the validity period of the temporary access credentials that are provided by STS to 1,200 seconds and the validity period of the signed URL generated by using the credentials to 3,600 seconds. In this case, you cannot use the signed URL to upload objects after the temporary access credentials expire, even if the signed URL is within the validity period.

Use STS for temporary access authorization

You can use Alibaba Cloud STS to authorize temporary access to OSS. STS is a web service that provides temporary access tokens for users. You can use STS to grant temporary access credentials that have a custom validity period and custom permissions to a third-party application or a RAM user that is managed by you. For more information about STS, see What is STS?

STS provides the following benefits:

  • You need to only generate an access token and send the access token to a third-party application. You do not need to expose your AccessKey pair to the third-party application. You can specify the access permissions and the validity period of the token.
  • The token automatically expires after the validity period. Therefore, you do not need to manually revoke the access permissions of a token.

To access OSS by using temporary access credentials provided by STS, perform the following operations:

  1. Obtain temporary access credentials.

    The temporary access credentials consist of an AccessKey pair and a security token. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. The minimum validity period of temporary access credentials is 900 seconds. The maximum validity period of temporary access credentials is the maximum session duration specified for the current role. For more information, see Specify the maximum session duration for a RAM role.

    You can use one of the following methods to obtain temporary access credentials:

  2. Use STS credentials to sign a request.
    // Obtain temporary access credentials from STS. 
    fetch('http://your_sts_server/')
      .then(resp => resp.json())
      .then(result => {
        const store = new OSS({
          // Specify the temporary AccessKey pair obtained from STS. An AccessKey pair consists of an AccessKey ID and an AccessKey secret. 
          accessKeyId: result.AccessKeyId,
          accessKeySecret: result.AccessKeySecret,
          // Specify the security token that you obtained from STS. 
          stsToken: result.SecurityToken,
          // Specify the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the region to oss-cn-hangzhou. 
          region: 'oss-cn-hangzhou',
          // Specify the name of the bucket. Example: examplebucket. 
          bucket: 'examplebucket'
        });
        // Generate the signed URL. 
        // Specify the full path of the object. Example: ossdemo.txt. Do not include the bucket name in the full path of the object. 
        const url = store.signatureUrl('ossdemo.txt');
        console.log(url);
      })

Use a signed URL for temporary access authorization

Important To use a signed URL that contains custom parameters to access an object from a browser, make sure that the value of the Content-Type parameter contained in the URL is the same as the Content-Type value specified in the request. Otherwise, OSS may report the SignatureDoesNotMatch error. For more information about how to configure Content-Type, see How do I specify the Content-Type header?.
  • Generate a signed URL
    • Generate a signed URL for an object
      Note name {String} specifies the name of the object stored in OSS. [expires] {Number} specifies the validity period of the URL. By default, the validity period is 1,800 seconds. For more information about other parameters, visit GitHub.
      The following sample code provides an example on how to generate a signed URL for an object:
      const url = store.signatureUrl('exampleobject.txt');
      console.log(url);
      
      // Obtain the signed URL that is used to upload the exampleobject.txt object. 
      const url = store.signatureUrl('exampleobject.txt', {
        // Set the validity period of the URL to 3,600 seconds. 
        expires: 3600,
        // Set the request method to PUT. By default, the request method is GET. 
        method: 'PUT'
      });
      console.log(url);
      
      const url = store.signatureUrl('exampleobject.txt', {
        expires: 3600,
        method: 'PUT',
        // Specify Content-Type. 
        'Content-Type': 'text/plain; charset=UTF-8',
      });
      console.log(url);
      
      // Obtain the signed URL used to download the exampleobject.txt object. By default, if you use the signed URL in a browser to access the object, the object is previewed but not downloaded. 
      const url = store.signatureUrl('exampleobject.txt', {
        expires: 3600,
        response: {
          'content-type': 'text/custom',
          // Obtain the signed URL used to download the exampleobject.txt object, and set the Content-Disposition header to attachment. This way, if you use the signed URL to access the object in a browser, the object is automatically downloaded, and you can specify the name of the downloaded object. 
          // To preview the object when you use the signed URL to access the object in a browser, set the Content-Disposition header to inline and use the custom domain name that is mapped to the bucket to access the object. 
          'content-disposition': 'attachment'
        }
      });
      console.log(url);
    • Generate a signed object URL that includes Image Processing (IMG) parameters
      // Obtain the signed URL that is used to access an image object named exampleobject.png. 
      // Specify the full path of the object. Do not include the bucket name in the full path. 
      const url = store.signatureUrl('exampleobject.png', {
        // Configure IMG parameters used to process the image. 
        process: 'image/resize,w_200'
      });
      console.log(url);
      // Set the validity period of the URL to 3,600 seconds. 
      const url = store.signatureUrl('exampleobject.png', {
        expires: 3600,
        process: 'image/resize,w_200'
      });
      console.log(url);
  • Use a signed URL

    After a signed URL is generated, you can use the URL to upload, preview, or download an object.

    • Use a signed URL to upload an object
      // Set signatureUrl to the generated signed URL. 
      const url = 'signatureUrl'; 
      
      var xhr = new XMLHttpRequest();
      xhr.open('PUT', url, true);
      
      xhr.onload = function () {
         // Add code for further operations. 
      };
      
      xhr.send(null);
      // xhr.send('string');
      // xhr.send(new Blob());
      // xhr.send(new Int8Array());
      // xhr.send({ form: 'data' });
      // xhr.send(document);
    • Use a signed URL to preview or download an object

      You can use the download attribute of the <a> HTML element or the window.open API to obtain the URL of an object.

References

  • For the complete sample code that is used to authorize temporary access by using STS, visit GitHub.
  • For the complete sample code that is used to authorize temporary access by using a signed URL, visit GitHub.