This topic describes how to use temporary access credentials provided by Security Token Service (STS) or a signed URL to authorize temporary access to Object Storage Service (OSS) resources.
Usage notes
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 your temporary access credentials to 1,200 seconds and the validity period of the signed URL generated by using the credentials to 3,600 seconds. In this case, the signed URL cannot be used to upload objects after the STS temporary access credentials expire, even if the signed URL is within its validity period.
In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS by using other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about the regions and endpoints supported by OSS, see Regions and endpoints.
In this topic, access credentials are obtained from environment variables. For more information about how to configure access credentials, see Configure access credentials.
In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization.
Use STS for temporary access authorization
You can use 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 has the following benefits:
You need to only generate a temporary access token and send the access token to a third-party application. You do not need to provide 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:
Use a signed URL for temporary access authorization
The following section provides examples on how to use a signed URL to authorize temporary access to OSS.
You can generate a signed URL and provide the URL to a third-party user for temporary access. When you generate a signed URL, you can specify the validity period of the URL to limit the period of time during which the third-party user can access OSS resources.
The signed URL generated by using the following sample code may contain a plus sign (+
). In this case, you must replace the plus sign (+
) in the URL with %2B
. Otherwise, the signed URL may be inaccessible.
You can add signature information to a URL and provide the URL to a third-party user for authorized access. For more information, see Add signatures to URLs.
Generate a signed URL that includes the versionId header
The following sample code provides an example on how to generate a signed URL that includes the versionId header:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import requests
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path.
object_name = 'exampledir/exampleobject.txt'
# Specify the headers.
headers = dict()
# Specify the version ID of the object.
headers["versionId"] = "CAEQARiBgID8rumR2hYiIGUyOTAyZGY2MzU5MjQ5ZjlhYzQzZjNlYTAyZDE3****"
# Generate a signed URL that is used to upload the object. Set the validity period of the signed URL to 60. Unit: seconds.
# By default, OSS identifies forward slashes (/) in the full path of an object as escape characters when a signed URL is generated. Therefore, the signed URL cannot be used directly.
# Set the slash_safe parameter to True. This way, OSS does not identify the forward slashes (/) in the full path of the object as escape characters. In this case, you can use the generated signed URL to upload the object.
url = bucket.sign_url('PUT', object_name, 60, slash_safe=True, headers=headers)
print ('The signed URL:', url)
Use a signed URL to upload an object
The following sample code provides an example on how to use a signed URL to upload an object:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import requests
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path.
object_name = 'exampledir/exampleobject.txt'
# Specify the headers.
headers = dict()
# Specify Content-Type.
# headers['Content-Type'] = 'text/txt'
# Specify the storage class of the object.
# headers["x-oss-storage-class"] = "Standard"
# Generate a signed URL that is used to upload the object. Set the validity period of the signed URL to 60. Unit: seconds.
# By default, OSS identifies forward slashes (/) in the full path of an object as escape characters when a signed URL is generated. Therefore, the signed URL cannot be used directly.
# Set the slash_safe parameter to True. This way, OSS does not identify the forward slashes (/) in the full path of the object as escape characters. In this case, you can use the generated signed URL to upload the object.
url = bucket.sign_url('PUT', object_name, 60, slash_safe=True, headers=headers)
print('The signed URL:', url)
# Use the signed URL to upload an object. requests is used as an example.
# Specify the full path of the local file. Example: D:\\exampledir\\examplefile.txt.
requests.put(url, data=open('D:\\exampledir\\examplefile.txt', 'rb').read(), headers=headers)
Use a signed URL to download an object
The following sample code provides an example on how to use the signed URL to download an object:
# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider
import requests
# Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
auth = oss2.ProviderAuth(EnvironmentVariableCredentialsProvider())
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
# Specify the name of the bucket. Example: examplebucket.
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')
# Specify the full path of the object. Example: exampledir/exampleobject.txt. Do not include the bucket name in the full path.
object_name = 'exampledir/exampleobject.txt'
# Specify the headers.
headers = dict()
# Specify Accept-Encoding.
headers['Accept-Encoding'] = 'gzip'
# Specify HTTP query parameters.
params = dict()
# Configure single-connection bandwidth throttling. Unit: bit/s. In this example, the maximum bandwidth is set to 100 KB/s.
# params['x-oss-traffic-limit'] = str(100 * 1024 * 8)
# Specify the IP address or CIDR block.
# params['x-oss-ac-source-ip'] = "127.0.0.1"
# Specify the number of the digit 1 in the subnet mask.
# params['x-oss-ac-subnet-mask'] = "32"
# Specify the ID of the virtual private cloud (VPC).
# params['x-oss-ac-vpc-id'] = "vpc-t4nlw426y44rd3iq4****"
# Specify whether the request can be forwarded.
# params['x-oss-ac-forward-allow'] = "true"
# Generate a signed URL that is used to download the object. The validity period of the URL is 60 seconds.
# By default, OSS identifies forward slashes (/) in the full path of an object as escape characters when a signed URL is generated. Therefore, the signed URL cannot be used directly.
# Set the slash_safe parameter to True. This way, OSS does not identify the forward slashes (/) in the full path of the object as escape characters. In this case, you can use the generated signed URL to upload the object.
url = bucket.sign_url('GET', object_name, 60, slash_safe=True, headers=headers, params=params)
print('The signed URL:', url)
# Use the signed URL to download the object. requests is used as an example.
resp = requests.get(url, headers=headers)
# Specify the full path of the local file. Example: D:\\exampledir\\examplefile.txt.
with open("D:\\exampledir\\examplefile.txt", "wb") as code:
code.write(resp.content)