This topic describes how to authorize temporary access to OSS by using STS or a signed URL.

Use STS to authorize temporary access

You can use Alibaba Cloud Security Token Service (STS) to authorize temporary access to OSS. STS is a web service that provides temporary access tokens for cloud computing users. You can use STS to grant a third-party application or your RAM user an access credential with a customized validity period and permissions. For more information about STS, see What is STS?

STS has the following benefits:

  • You need only to generate an access token and send the access token to a third-party application, instead of exposing your long-term AccessKey pair to the third-party application. You can customize the access permissions and validity period of this token.
  • The access token automatically expires when the validity period ends.

For more information about how to access OSS by using STS, see Access OSS with a temporary access credential provided by STS in OSS Developer Guide.

The following code provides an example on how to set stsToken when you use STS to access OSS:

let OSS = require('ali-oss');
let STS = OSS.STS;
let sts = new STS({
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>'
});
async function assumeRole () {
  try {
    let token = await sts.assumeRole(
    '<role-arn>', '<policy>', '<expiration>', '<session-name>');
    let client = new OSS({
      region: '<region>',
      accessKeyId: token.credentials.AccessKeyId,
      accessKeySecret: token.credentials.AccessKeySecret,
      stsToken: token.credentials.SecurityToken,
      bucket: '<bucket-name>'
    });
  } catch (e) {
    console.log(e);
  }
}
assumeRole();

The following list describes the parameters used in the preceding code:

  • role-arn: the name of the custom permission policy.
  • policy: the permission conditions specified for users that assume the role. For more information, see Create RAM policies.

    The added policy is used to control the permissions of the temporary access credential after the user assumes a role. The permissions obtained by the temporary credential are restricted by both the role and the added policy. When a role is assumed, a policy can be added to further control the permissions. For example, when you upload objects, you can add a policy to control upload paths for different users.

  • expiration: the validity period of the temporary access credential. Unit: seconds. Valid values: 900 to 3600.
    Note The validity period must be set for both an STS temporary account and a signed URL. When you use an STS temporary account to generate a signed URL to perform operations such as object upload and download, the minimum validity period takes precedence. For example, you can set the validity period of your STS temporary account to 1200 seconds, and that of the signed URL to 3600 seconds. After 1200 seconds, you cannot use the signed URL generated by the STS temporary account to upload objects.
  • session-name: the custom parameter. This parameter can be used to identify the RAM user who assumes the RAM role. For more information about the format of this parameter, see AssumeRole.

You can customize an STS policy when you apply for a temporary token from STS. The temporary permission that you apply for is determined by your role and the policy. The following code provides an example on how to specify an STS policy to apply for the read-only permission on my-bucket and set the validity period of the temporary token to 15 minutes:

let OSS = require('ali-oss');
let STS = OSS.STS;
let sts = new STS({
  // Security risks may arise if you use the AccessKey pair of an Alibaba Cloud account to log on to OSS because the account has permissions on all API operations. We recommend that you use your RAM user's credentials to call API operations or perform routine operations and maintenance. To create a RAM user, log on to the RAM console.
  accessKeyId: '<Your AccessKeyId>',
  accessKeySecret: '<Your AccessKeySecret>'
});
let policy = {
  "Statement": [
    {
      "Action": [
        "oss:Get*"
      ],
      "Effect": "Allow",
      "Resource": ["acs:oss:*:*:my-bucket/*"]
    }
  ],
  "Version": "1"
};
async function assumeRole () {
  try {
    let token = await sts.assumeRole(
    '<role-arn>', policy, 15 * 60, '<session-name>');
    let client = new OSS({
      region: '<region>',
      accessKeyId: token.credentials.AccessKeyId,
      accessKeySecret: token.credentials.AccessKeySecret,
      stsToken: token.credentials.SecurityToken,
      bucket: '<bucket-name>'
    });
  } catch (e) {
    console.log(e);
  }
}
assumeRole();

Use a signed URL to authorize temporary access

This section provides examples on how to use a signed URL to authorize temporary access.

  • Generate a signed URL

    You can generate a signed URL and provide it to a visitor to grant temporary access. When you generate a signed URL, you can specify the validity period of the URL to limit the period of access from visitors.

  • Generate a signed URL for an object

    name {String} indicates the name of the object stored in OSS. [expires] {Number} indicates the validity period of the URL. The default value is 1800 seconds. For more information about other parameters, visit GitHub.

    The following code provides an example on how to generate a signed URL for an object:
    let OSS = require('ali-oss');
    let store = new OSS({
        bucket: '<your bucket>',
        region: '<your region>',
        accessKeyId: '<your accessKeyId>',
        accessKeySecret: '<your accessKeySecret>'
    })
    const url = store.signatureUrl('ossdemo.txt');
    console.log(url);
    // --------------------------------------------------
    const url = store.signatureUrl('ossdemo.txt', {
      expires: 3600,
      method: 'PUT'
    });
    console.log(url);
    
    //  put object with signatureUrl
    // -------------------------------------------------
    
    const url = store.signatureUrl('ossdemo.txt', {
      expires: 3600,
      method: 'PUT',
      'Content-Type': 'text/plain; charset=UTF-8',
    });
    console.log(url);
    
    // --------------------------------------------------
    const url = store.signatureUrl('ossdemo.txt', {
      expires: 3600,
      response: {
        'content-type': 'text/custom',
        'content-disposition': 'attachment'
      }
    });
    console.log(url);
    
    // put operation
  • Generate a signed URL that includes IMG parameters

    The following code provides an example on how to generate a signed URL that includes IMG parameters:

    let OSS = require('ali-oss');
    let store = new OSS({
        bucket: '<your bucket>',
        region: '<your region>',
        accessKeyId: '<your accessKeyId>',
        accessKeySecret: '<your accessKeySecret>'
    })
    const url = store.signatureUrl('ossdemo.png', {
      process: 'image/resize,w_200'
    });
    console.log(url);
    // --------------------------------------------------
    const url = store.signatureUrl('ossdemo.png', {
      expires: 3600,
      process: 'image/resize,w_200'
    });
    console.log(url);