OSS bucket objects are private by default — only the bucket owner can upload them. Generate a presigned URL to grant temporary upload access to other users without sharing your credentials. The URL is valid for a specified duration and can be reused until it expires. If multiple uploads are performed using the same URL, the object may be overwritten. After expiration, generate a new presigned URL.
Prerequisites
Before you begin, ensure that you have:
An OSS bucket in the
cn-hangzhouregion (or the region where your bucket is located)The
oss:PutObjectpermission on the bucket (required to authorize uploads via the presigned URL)The OSS C# SDK V2 (
AlibabaCloud.OSS.V2) installedOSS_ACCESS_KEY_IDandOSS_ACCESS_KEY_SECRETset as environment variables
No special permissions are required to generate a presigned URL. The oss:PutObject permission is only needed to authorize the actual upload operation.How it works
Presigned URL uploads use two separate parties:
The object owner (server side) generates a presigned URL using the C# SDK V2 and shares it.
The uploader (client side) uses the URL to upload via a standard HTTP PUT request — no OSS credentials required.
If you include request headers or custom metadata when generating the URL, the uploader must send the same headers in the PUT request. Mismatched headers cause a signature mismatch error.
The following diagram shows the end-to-end flow:
Generate a presigned URL (C# SDK V2)
The following example generates a presigned URL for a PUT request and immediately uses it to upload a string.
Important
If you include request headers when generating the presigned URL, send the same headers in the PUT request. Otherwise, OSS rejects the request with a signature mismatch error.
using System.Text;
using OSS = AlibabaCloud.OSS.V2; // Alias for the Alibaba Cloud OSS SDK.
var region = "cn-hangzhou"; // Region where the bucket is located.
var endpoint = null as string; // Optional. Override the default endpoint if needed.
var bucket = "your bucket name"; // The bucket name.
var key = "your object key"; // The object key (name in OSS after upload).
// Load SDK defaults. Credentials are read from OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
var cfg = OSS.Configuration.LoadDefault();
cfg.CredentialsProvider = new OSS.Credentials.EnvironmentVariableCredentialsProvider();
cfg.Region = region;
if (endpoint != null)
{
cfg.Endpoint = endpoint;
}
// Create an OSS client.
using var client = new OSS.Client(cfg);
// Generate a presigned URL for a PUT request.
var result = client.Presign(new OSS.Models.PutObjectRequest()
{
Bucket = bucket,
Key = key,
});
// Upload content using the presigned URL.
const string content = "hello oss!";
using var hc = new HttpClient();
var httpResult = await hc.PutAsync(result.Url, new ByteArrayContent(Encoding.UTF8.GetBytes(content)));
Console.WriteLine("PutObject done");
Console.WriteLine($"StatusCode: {httpResult.StatusCode}");The sample code uses the China (Hangzhou) region (cn-hangzhou) with the public endpoint. To access OSS from another Alibaba Cloud service in the same region, use an internal endpoint. For the full list of regions and endpoints, see OSS regions and endpoints.Share result.Url with the uploader. The URL is a standard HTTPS endpoint — the uploader needs no OSS SDK or credentials.
Upload using the presigned URL
All examples below use the presigned URL generated in the previous section. Replace <signedUrl> with the actual URL.
curl
curl -X PUT -T /path/to/local/file "https://exampleobject.oss-cn-hangzhou.aliyuncs.com/exampleobject.txt?x-oss-date=20241112T083238Z&x-oss-expires=3599&x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=LTAI****************%2F20241112%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-signature=ed5a******************************************************"Java
import org.apache.http.HttpEntity;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.FileEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.*;
import java.net.URL;
import java.util.*;
public class SignUrlUpload {
public static void main(String[] args) throws Throwable {
CloseableHttpClient httpClient = null;
CloseableHttpResponse response = null;
// Replace <signedUrl> with the authorized URL.
URL signedUrl = new URL("<signedUrl>");
// Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
String pathName = "C:\\Users\\demo.txt";
try {
HttpPut put = new HttpPut(signedUrl.toString());
System.out.println(put);
HttpEntity entity = new FileEntity(new File(pathName));
put.setEntity(entity);
httpClient = HttpClients.createDefault();
response = httpClient.execute(put);
System.out.println("Status code returned for the upload:"+response.getStatusLine().getStatusCode());
if(response.getStatusLine().getStatusCode() == 200){
System.out.println("Upload successful using network library.");
}
System.out.println(response.toString());
} catch (Exception e){
e.printStackTrace();
} finally {
if (response != null) {
response.close();
}
if (httpClient != null) {
httpClient.close();
}
}
}
} Go
package main
import (
"fmt"
"io"
"net/http"
"os"
)
func uploadFile(signedUrl, filePath string) error {
// Open the file.
file, err := os.Open(filePath)
if err != nil {
return fmt.Errorf("Unable to open file: %w", err)
}
defer file.Close()
// Create a new HTTP client.
client := &http.Client{}
// Create a PUT request.
req, err := http.NewRequest("PUT", signedUrl, file)
if err != nil {
return fmt.Errorf("Failed to create request: %w", err)
}
// Send the request.
resp, err := client.Do(req)
if err != nil {
return fmt.Errorf("Failed to send request: %w", err)
}
defer resp.Body.Close()
// Read the response.
body, err := io.ReadAll(resp.Body)
if err != nil {
return fmt.Errorf("Failed to read response: %w", err)
}
fmt.Printf("Status code returned for the upload: %d\n", resp.StatusCode)
if resp.StatusCode == 200 {
fmt.Println("Upload successful using network library.")
}
fmt.Println(string(body))
return nil
}
func main() {
// Replace <signedUrl> with the authorized URL.
signedUrl := "<signedUrl>"
// Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
filePath := "C:\\Users\\demo.txt"
err := uploadFile(signedUrl, filePath)
if err != nil {
fmt.Println("An error occurred:", err)
}
}
python
import requests
def upload_file(signed_url, file_path):
try:
# Open the file.
with open(file_path, 'rb') as file:
# Send a PUT request to upload the file.
response = requests.put(signed_url, data=file)
print(f"Status code returned for the upload: {response.status_code}")
if response.status_code == 200:
print("Upload successful using network library.")
print(response.text)
except Exception as e:
print(f"An error occurred: {e}")
if __name__ == "__main__":
# Replace <signedUrl> with the authorized URL.
signed_url = "<signedUrl>"
# Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
file_path = "C:\\Users\\demo.txt"
upload_file(signed_url, file_path)
Node.js
const fs = require('fs');
const axios = require('axios');
async function uploadFile(signedUrl, filePath) {
try {
// Create a read stream.
const fileStream = fs.createReadStream(filePath);
// Send a PUT request to upload the file.
const response = await axios.put(signedUrl, fileStream, {
headers: {
'Content-Type': 'application/octet-stream' // Adjust the Content-Type as needed.
}
});
console.log(`Status code returned for the upload: ${response.status}`);
if (response.status === 200) {
console.log('Upload successful using network library.');
}
console.log(response.data);
} catch (error) {
console.error(`An error occurred: ${error.message}`);
}
}
// Main function.
(async () => {
// Replace <signedUrl> with the authorized URL.
const signedUrl = '<signedUrl>';
// Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
const filePath = 'C:\\Users\\demo.txt';
await uploadFile(signedUrl, filePath);
})();browser.js
Important
If you encounter a 403 signature mismatch error when you use Browser.js to upload a file, it is usually because the browser automatically adds the Content-Type request header, and this header was not included when the presigned URL was generated. This mismatch causes a signature verification failure. To resolve this issue, you must specify the Content-Type request header when you generate the presigned URL.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>File Upload Example</title>
</head>
<body>
<h1>File Upload Example</h1>
<!-- Select a file -->
<input type="file" id="fileInput" />
<button id="uploadButton">Upload File</button>
<script>
// Replace this with the presigned URL generated in Step 1.
const signedUrl = "<signedUrl>";
document.getElementById('uploadButton').addEventListener('click', async () => {
const fileInput = document.getElementById('fileInput');
const file = fileInput.files[0];
if (!file) {
alert('Please select a file to upload.');
return;
}
try {
await upload(file, signedUrl);
alert('File uploaded successfully!');
} catch (error) {
console.error('Error during upload:', error);
alert('Upload failed: ' + error.message);
}
});
/**
* Upload the file to OSS.
* @param {File} file - The file to upload.
* @param {string} presignedUrl - The presigned URL.
*/
const upload = async (file, presignedUrl) => {
const response = await fetch(presignedUrl, {
method: 'PUT',
body: file, // Upload the entire file directly.
});
if (!response.ok) {
throw new Error(`Upload failed, status: ${response.status}`);
}
console.log('File uploaded successfully');
};
</script>
</body>
</html>C#
using System.Net.Http.Headers;
// Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
var filePath = "C:\\Users\\demo.txt";
// Replace <signedUrl> with the authorized URL.
var presignedUrl = "<signedUrl>";
// Create an HTTP client and open the local file stream.
using var httpClient = new HttpClient();
using var fileStream = new FileStream(filePath, FileMode.Open, FileAccess.Read);
using var content = new StreamContent(fileStream);
// Create a PUT request.
var request = new HttpRequestMessage(HttpMethod.Put, presignedUrl);
request.Content = content;
// Send the request.
var response = await httpClient.SendAsync(request);
// Process the response.
if (response.IsSuccessStatusCode)
{
Console.WriteLine($"Upload successful! Status code: {response.StatusCode}");
Console.WriteLine("Response headers:");
foreach (var header in response.Headers)
{
Console.WriteLine($"{header.Key}: {string.Join(", ", header.Value)}");
}
}
else
{
string responseContent = await response.Content.ReadAsStringAsync();
Console.WriteLine($"Upload failed! Status code: {response.StatusCode}");
Console.WriteLine("Response content: " + responseContent);
}C++
#include <iostream>
#include <fstream>
#include <curl/curl.h>
void uploadFile(const std::string& signedUrl, const std::string& filePath) {
CURL *curl;
CURLcode res;
curl_global_init(CURL_GLOBAL_DEFAULT);
curl = curl_easy_init();
if (curl) {
// Set the URL.
curl_easy_setopt(curl, CURLOPT_URL, signedUrl.c_str());
// Set the request method to PUT.
curl_easy_setopt(curl, CURLOPT_UPLOAD, 1L);
// Open the file.
FILE *file = fopen(filePath.c_str(), "rb");
if (!file) {
std::cerr << "Unable to open file: " << filePath << std::endl;
return;
}
// Get the file size.
fseek(file, 0, SEEK_END);
long fileSize = ftell(file);
fseek(file, 0, SEEK_SET);
// Set the file size.
curl_easy_setopt(curl, CURLOPT_INFILESIZE_LARGE, (curl_off_t)fileSize);
// Set the input file handle.
curl_easy_setopt(curl, CURLOPT_READDATA, file);
// Execute the request.
res = curl_easy_perform(curl);
if (res != CURLE_OK) {
std::cerr << "curl_easy_perform() failed: " << curl_easy_strerror(res) << std::endl;
} else {
long httpCode = 0;
curl_easy_getinfo(curl, CURLINFO_RESPONSE_CODE, &httpCode);
std::cout << "Status code returned for the upload: " << httpCode << std::endl;
if (httpCode == 200) {
std::cout << "Upload successful using network library." << std::endl;
}
}
// Close the file.
fclose(file);
// Clean up.
curl_easy_cleanup(curl);
}
curl_global_cleanup();
}
int main() {
// Replace <signedUrl> with the authorized URL.
std::string signedUrl = "<signedUrl>";
// Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
std::string filePath = "C:\\Users\\demo.txt";
uploadFile(signedUrl, filePath);
return 0;
}
Android
package com.example.signurlupload;
import android.os.AsyncTask;
import android.util.Log;
import java.io.DataOutputStream;
import java.io.FileInputStream;
import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URL;
public class SignUrlUploadActivity {
private static final String TAG = "SignUrlUploadActivity";
public void uploadFile(String signedUrl, String filePath) {
new UploadTask().execute(signedUrl, filePath);
}
private class UploadTask extends AsyncTask<String, Void, String> {
@Override
protected String doInBackground(String... params) {
String signedUrl = params[0];
String filePath = params[1];
HttpURLConnection connection = null;
DataOutputStream dos = null;
FileInputStream fis = null;
try {
URL url = new URL(signedUrl);
connection = (HttpURLConnection) url.openConnection();
connection.setRequestMethod("PUT");
connection.setDoOutput(true);
connection.setRequestProperty("Content-Type", "application/octet-stream");
fis = new FileInputStream(filePath);
dos = new DataOutputStream(connection.getOutputStream());
byte[] buffer = new byte[1024];
int length;
while ((length = fis.read(buffer)) != -1) {
dos.write(buffer, 0, length);
}
dos.flush();
dos.close();
fis.close();
int responseCode = connection.getResponseCode();
Log.d(TAG, "Status code returned for the upload: " + responseCode);
if (responseCode == 200) {
Log.d(TAG, "Upload successful using network library.");
}
return "Upload complete. Status code: " + responseCode;
} catch (IOException e) {
e.printStackTrace();
return "Upload failed: " + e.getMessage();
} finally {
if (connection != null) {
connection.disconnect();
}
}
}
@Override
protected void onPostExecute(String result) {
Log.d(TAG, result);
}
}
public static void main(String[] args) {
SignUrlUploadActivity activity = new SignUrlUploadActivity();
// Replace <signedUrl> with the authorized URL.
String signedUrl = "<signedUrl>";
// Specify the full path of the local file. If you do not specify a local path, the file is uploaded from the project path of the sample program by default.
String filePath = "C:\\Users\\demo.txt";
activity.uploadFile(signedUrl, filePath);
}
}
Scenarios
Troubleshooting
SignatureNotMatch errors
If the upload fails with a signature mismatch error, check the following:
Mismatched headers: Any request header included when generating the presigned URL must be sent in the PUT request with the exact same value. Missing or modified headers cause signature verification to fail.
Browser adds Content-Type automatically: When using Browser.js, specify
Content-Typewhen generating the presigned URL so the browser-added header is covered by the signature.Expired URL: Generate a new presigned URL if the existing one has expired.
FAQ
What's next
For the complete sample code, see PresignPutObject.cs.
For related permissions, see Authorize a RAM user to access multiple directories in a bucket.