# Upload files securely from the client

> Learn how to use presigned URLs to give your clients secure, high-performance large-file uploads.

## Why we don't recommend uploading with client-side SDKs such as the JavaScript SDK

1. Your ak / sk can be exposed if the client is decompiled.
2. It isn't flexible enough.

> **Warning**
>
> Security best practice: never hand out ak / sk through an API.

## A better approach

### Generate a presigned URL on the backend and return it through your API

The frontend can send a PUT request directly to the presigned URL. This gives you several benefits:

1. More secure: your critical AccessKey and SecretKey can never leak through `exposed client code` or `decompilation`.
2. More flexible: by explicitly specifying `Content-Type` and `Content-Length`, you prevent a tampered client from bypassing your business rules.
3. Lower cost: the server hands out presigned URLs in one place, so client developers only need to make a PUT HTTP request. They don't have to learn and debug the S3 SDK in different languages. (In practice, each language version of the AWS SDK is maintained by a different team, and their conventions and features vary widely, which hurts project stability.)
4. High performance: upload requests still go directly to Bitiful S4, with no relay through your server.

### How it works

### Generate a presigned upload URL through your backend API: putObject-presigned-url

Have your backend (Go, Python, PHP, Node.js) call the appropriate SDK to generate a presigned URL authorized for the PutObject method, and pass it to the JavaScript on your web page.

### The client sends a PUT request to putObject-presigned-url to upload the file

The JavaScript uses an HTTP client library (such as axios) to PUT the local file to the presigned PutObject URL described above.

**Presigned URL API**

> **Tip**
>
> Bitiful has open-sourced a full-featured, self-hosted presigned URL API project. It's stateless, so you can quickly plug it into your existing system as a microservice.

Github: <https://github.com/bitiful/s3-presigned-api-server>

### Examples: generating PutObject presigned URLs in different backend languages

```python main.py
import boto3
from flask import Flask
from flask import render_template_string
from flask import request

app = Flask(__name__)

@app.get('/s3_upload_url')
def get_upload_url():
    # Config
    s3endpoint = 'https://s3.bitiful.net' # Use the value from the "Endpoint" label at the bottom of the "Bucket settings" page in the console
    s3region = 'cn-east-1'
    s3accessKeyId = '<--sub-account accessKey-->' # Create a sub-account in the console, then create an accessKey for it
    s3SecretKeyId = '<--sub-account secretKey-->' # Important: when you create a sub-account, you must grant it specific permissions manually!

    # Connect to S3
    client = boto3.client(
        's3',
        aws_access_key_id = s3accessKeyId,
        aws_secret_access_key = s3SecretKeyId,
        endpoint_url = s3endpoint,
        region_name = s3region
    )
    url = client.generate_presigned_url(
        'put_object',
        Params={
            'Bucket': '<--Bitiful bucket name-->',
            'Key': request.args.get('key'),
        },
        ExpiresIn=3600
    )
    return {'url': url}
```

```javascript main.js
// Reference 1: https://juejin.cn/post/7019216042220077092
// Reference 2: https://northflank.com/guides/connect-nodejs-to-minio-with-tls-using-aws-s3
const {
  S3Client
} = require("@aws-sdk/client-s3");
const s3Client = new S3Client({
  endpoint: "https://s3.bitiful.net",
  credentials: {
    accessKeyId: "<--sub-account accessKey-->",
    secretAccessKey: "<--sub-account secretKey-->",
  }
});

// Import the required modules
const {
  PutObjectCommand,
} = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");

app.get("/s3_upload_url", (req, res, next) => {
  // Create the command
  const putCmd = new PutObjectCommand({
    Bucket: "<--Bitiful bucket name-->",
    Key: req.query.key
  });
  // Get the signature
  getSignedUrl(s3Client, putCmd, { expiresIn: 3600 }).then((url) => {
      // Send the signed URL back to the frontend
    res.send(url);
    next();
  });
});
```

```rust main.rs
// Reference: https://developer.qiniu.com/kodo/12572/aws-sdk-rust-examples
// [dependencies]
// actix-web = "4"
// serde = { version = "1.0", features = ["derive"] }
// serde_json = "1.0"
// anyhow = "1.0.75"
// aws-config = "1.3.0"
// aws-credential-types = { version = "1.2.0", features = ["hardcoded-credentials"] }
// aws-sdk-s3 = "1.25.0"
// aws-sdk-sts = "1.22.0"
// aws-smithy-types = { version = "1.1.8", features = ["rt-tokio"] }
// tokio = { version = "1.32.0", features = ["full"] }

use actix_web::{web, App, HttpResponse, HttpServer, Responder};
use aws_config::{BehaviorVersion, SdkConfig};
use aws_credential_types::{provider::SharedCredentialsProvider, Credentials};
use aws_sdk_s3::{config::Region, presigning::PresigningConfig, Client};
use std::time::Duration;

async fn get_upload_url(query: web::Query<serde_json::Value>) -> impl Responder {
    let key = query.get("key").and_then(|v| v.as_str()).unwrap_or("");
    let url = get_url(key);

    let response_data = serde_json::json!({ "url": url.await.unwrap_or("".to_string())});
    HttpResponse::Ok()
        .content_type("application/json") // Set the response Content-Type
        .json(response_data)
}

#[actix_web::main]
async fn main() -> std::io::Result<()> {
    HttpServer::new(|| {
        App::new()
            .route("/s3_upload_url", web::get().to(get_upload_url))
    })
    .bind("127.0.0.1:8080")?
    .run()
    .await
}

async fn get_url(key: &str) -> anyhow::Result<String> {
    let client = Client::new(
        &SdkConfig::builder()
            .region(Region::new("cn-east-1"))
            .endpoint_url("https://s3.bitiful.net")
            .behavior_version(BehaviorVersion::v2023_11_09())
            .credentials_provider(SharedCredentialsProvider::new(Credentials::from_keys(
                "<--sub-account accessKey-->",
                "<--sub-account secretKey-->",
                None,
            )))
            .build(),
    );

    let request = client
        .put_object()
        .bucket("<--Bitiful bucket name-->")
        .key(key)
        .presigned(
            PresigningConfig::builder()
                .expires_in(Duration::from_secs(36000))
        .build()?,
        )
        .await?;

    Ok(request.uri().to_string())
}
```

```go main.go
// go get github.com/aws/aws-sdk-go

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "time"

    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/credentials"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)

const (
    bucket     = "<--Bitiful bucket name-->"
    endpoint   = "https://s3.bitiful.net"
    region     = "cn-east-1"
    accessKey  = "<--sub-account accessKey-->"
    secretKey  = "<--sub-account secretKey-->"
)

func main() {
    http.HandleFunc("/s3_upload_url", handleS3UploadURL)
    log.Println("Server started at http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", nil))
}

func handleS3UploadURL(w http.ResponseWriter, r *http.Request) {
    // Parse query parameter
    keys, ok := r.URL.Query()["key"]
    if !ok || len(keys[0]) < 1 {
        http.Error(w, "Missing 'key' query parameter", http.StatusBadRequest)
        return
    }
    key := keys[0]

    // Create AWS session
    sess := session.Must(session.NewSession(&aws.Config{
        Region:      aws.String(region),
        Endpoint:    aws.String(endpoint),
        Credentials: credentials.NewStaticCredentials(accessKey, secretKey, ""),
    }))

    // Create S3 service client
    svc := s3.New(sess)

    // Generate the URL
    req, _ := svc.PutObjectRequest(&s3.PutObjectInput{
        Bucket: aws.String(bucket),
        Key:    aws.String(key),
    })
    urlStr, err := req.Presign(15 * time.Minute) // URL expires in 15 minutes
    if err != nil {
        http.Error(w, "Failed to sign request: "+err.Error(), http.StatusInternalServerError)
        return
    }

    // Create JSON response
    response := struct {
        URL string `json:"url"`
    }{
        URL: urlStr,
    }
    jsonResponse, err := json.Marshal(response)
    if err != nil {
        http.Error(w, "JSON encoding error: "+err.Error(), http.StatusInternalServerError)
        return
    }

    // Set Content-Type and write the response
    w.Header().Set("Content-Type", "application/json")
    w.Write(jsonResponse)
}
```

```php main.php
# composer require aws/aws-sdk-php

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

// Configuration
$bucket = '<--Bitiful bucket name-->';
$region = 'cn-east-1';
$keyId = '<--sub-account accessKey-->';
$secret = '<--sub-account secretKey-->';
$endpoint = 'https://s3.bitiful.net';

// Create the S3 client
$s3Client = new S3Client([
    'version'     => 'latest',
    'region'      => $region,
    'credentials' => [
        'key'    => $keyId,
        'secret' => $secret,
    ],
    'endpoint' => $endpoint,
    'use_path_style_endpoint' => true,
]);

// Check for the key parameter
if (!isset($_GET['key']) || empty($_GET['key'])) {
    header('Content-Type: application/json');
    echo json_encode(['error' => 'Missing key parameter']);
    http_response_code(400);
    exit;
}

$key = $_GET['key'];

// Generate the presigned URL
try {
    $cmd = $s3Client->getCommand('PutObject', [
        'Bucket' => $bucket,
        'Key'    => $key
    ]);

    $request = $s3Client->createPresignedRequest($cmd, '+20 minutes');

    // Get the presigned URL
    $presignedUrl = (string) $request->getUri();

    header('Content-Type: application/json');
    echo json_encode(['url' => $presignedUrl]);
} catch (AwsException $e) {
    header('Content-Type: application/json');
    echo json_encode(['error' => $e->getMessage()]);
    http_response_code(500);
}
```

### Frontend upload example

```html upload_demo.web.html
<!DOCTYPE html>
<html>
<head>
  <title>S3 File Upload</title>
</head>
<body>
<div>
  <h1>S3 File Upload</h1>
  <input type="file" id="file">
  <button onclick="handleClick()">Upload</button>
</div>
<script src="https://cdn.bootcdn.net/ajax/libs/axios/1.3.6/axios.min.js"></script>
<script>
    let file;
    let fileContent;

    const fileInput = document.getElementById('file');
    const fileReader = new FileReader();

    fileInput.addEventListener('change', function (event) {
        file = event.target.files[0];
        console.log("file is: ", file);
        fileReader.readAsArrayBuffer(file);
    });

    fileReader.onload = function (event) {
        fileContent = event.target.result;
        // console.log("fileContent is: ", fileContent);
    };

    function handleClick() {
        console.log('click');

        const url = `/s3_upload_url`;
        const params = {key: '1.jpg'};

        axios.get(url, {params: params})
            .then(function (res) {
                console.log(res);
                const url = res.data.url;
                const config = {
                    headers: {
                        'Content-Type': null,
                    },
                };
                axios.put(url, file, config)
                    .then(function (res) {
                        console.log("res is: ", res);
                    });
            });

    }
</script>

</body>
</html>
```

> **Tip**
>
> The JavaScript above sets `Content-Type` to an empty value when it sends the PUT request. We recommend using Bitiful's exclusive [automatic MIME detection](/en/best-practice/auto-detect-mime) feature.
