Generate signed URLs for object preview and download using OSS SDK for Browser.js - Object Storage Service

OSS objects are private by default and accessible only to the bucket owner. Use the signatureUrl method to generate a time-limited signed URL that grants others access to a specific object — either to preview it in the browser or to download it.

Prerequisites

Before you begin, ensure that you have:

Installed OSS SDK for Browser.js. If you use Webpack or Browserify, run npm install ali-oss
Configured CORS rules for your bucket. Without CORS rules, the browser rejects cross-origin requests. See Installation
Obtained temporary access credentials from Security Token Service (STS). A set of temporary credentials consists of an AccessKey ID, an AccessKey secret, and a security token. Never hardcode a permanent AccessKey pair in browser code — always use STS instead. See Use STS for temporary access authorization

How it works

signatureUrl generates a signed URL by embedding your credentials and an expiry timestamp as query parameters. Anyone with the URL can access the object until it expires. The signed URL inherits the permissions of the credentials used to generate it.

The default validity period is 1,800 seconds. Pass expires: <seconds> to override.

Whether the URL triggers a preview or a download depends on the Content-Disposition response header — not the URL itself. See Preview an object and Download an object for details.

Preview an object

To preview an object in the browser instead of downloading it, both of the following conditions must be met:

The object's Content-Disposition metadata is set to inline. Configure this in the object's metadata settings. See Configure object metadata.
The signed URL uses a custom domain name mapped to the bucket. Browsers block inline rendering when the URL uses an OSS default domain. See Use custom domain names.

The following example generates a signed URL for example.jpg in examplebucket.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <!-- Import the SDK file -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // Specify the region where the bucket is located.
        // Example: oss-cn-hangzhou for the China (Hangzhou) region.
        region: "yourRegion",
        authorizationV4: true,
        // Temporary AccessKey ID obtained from STS.
        accessKeyId: "yourAccessKeyId",
        // Temporary AccessKey secret obtained from STS.
        accessKeySecret: "yourAccessKeySecret",
        // Security token obtained from STS.
        stsToken: "yoursecurityToken",
        // Name of the bucket.
        bucket: "examplebucket",
      });

      // Specify the full path of the object. Do not include the bucket name.
      const url = client.signatureUrl("example.jpg", {
        // To apply an image style, set the process parameter in "style/<image style name>" format.
        // process: "style/imagestyle",
      });
      console.log(url);

      // To set a custom validity period, pass the expires parameter (in seconds).
      // Default: 1800 seconds.
      // url = client.signatureUrl('example.jpg', { expires: 3600 });
      // console.log(url);
    </script>
  </body>
</html>

Download an object

To trigger a download when a user opens the signed URL, set the content-disposition response header to attachment with the target filename. Use encodeURIComponent to handle filenames with special characters or non-ASCII characters.

The following example generates a signed URL that downloads exampleobject.txt from examplebucket and saves it locally as examplefile.txt. The URL is valid for 1,800 seconds by default.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>Document</title>
  </head>

  <body>
    <!-- Import the SDK file -->
    <script
      type="text/javascript"
      src="https://gosspublic.alicdn.com/aliyun-oss-sdk-6.18.0.min.js"
    ></script>
    <script type="text/javascript">
      const client = new OSS({
        // Specify the region where the bucket is located.
        // Example: oss-cn-hangzhou for the China (Hangzhou) region.
        region: "yourRegion",
        authorizationV4: true,
        // Temporary AccessKey ID obtained from STS.
        accessKeyId: "yourAccessKeyId",
        // Temporary AccessKey secret obtained from STS.
        accessKeySecret: "yourAccessKeySecret",
        // Security token obtained from STS.
        stsToken: "yoursecurityToken",
        // Name of the bucket.
        bucket: "examplebucket",
      });

      // Set the response header to trigger a download and specify the local filename.
      const filename = "examplefile.txt";
      const response = {
        "content-disposition": `attachment; filename=${encodeURIComponent(filename)}`,
      };
      // Specify the full path of the object. Do not include the bucket name.
      const url = client.signatureUrl("exampleobject.txt", { response });
      console.log(url);
    </script>
  </body>
</html>

What's next

Configure object metadata — set Content-Disposition: inline to enable browser previews
Use custom domain names — required for browser previews with signed URLs
Use STS for temporary access authorization — generate temporary credentials for browser-side use