---
title: "Bucket Setup - Workshop Docs"
description: "Bucket Setup - Enterprise control plane for Santa. Manage rules, approvals, telemetry, and policies across your macOS fleet."
doc_version: "1"
last_updated: "2026-06-23"
canonical: "https://northpole.security/docs/workshop/binary-upload/bucket-setup"
---
# Bucket Setup

Binary upload stores files in your own cloud storage bucket. For each request, Workshop mints a short-lived presigned URL, and the host uploads straight to the bucket. Workshop never holds the file.

Two providers are supported: Amazon S3 (`s3://`) and Google Cloud Storage (`gs://`).

## Create a bucket

Create a private bucket with no public access.

Uploaded files are stored at the root of the bucket, keyed by their SHA-256. The Test Bucket check writes objects under a `__workshop_test__/` prefix so they are easy to find and remove. A lifecycle rule that expires `__workshop_test__/` objects is a good safety net in case a cleanup ever fails.

## Grant Workshop access

Workshop uses its own cloud credentials, the task role on AWS and the workload service account on Google Cloud. Grant that identity access to the bucket.

On S3:

-   `s3:PutObject` to store uploads. The presigned URL passes this permission to the host.
-   `s3:DeleteObject` to remove the Test Bucket object after a check.
-   `s3:ListBucket` to detect the bucket’s region.

On Google Cloud Storage:

-   `storage.objects.create` to store uploads.
-   `storage.objects.delete` to remove the Test Bucket object after a check.
-   The **Service Account Token Creator** role on the service account itself. Workshop signs the upload URL with the IAM `signBlob` API, which needs this role.

Read access is not required. A write-only role is enough.

## Connect the bucket

Open **Settings**, find the binary upload section, and enter your bucket URL as `s3://your-bucket` or `gs://your-bucket`. Workshop validates the scheme and bucket name. Clear the field to turn binary upload off.

## Test the bucket

Use **Test Bucket** to confirm the setup with an upload and cleanup round-trip. Run it in presigned mode, which exercises the same path real uploads use.

The check reports the stage that failed:

-   **presign**: Workshop could not sign an upload URL. Check credentials, and on Google Cloud the Service Account Token Creator role.
-   **upload**: the bucket rejected the write. Check the bucket policy and the `PutObject` permission.
-   **cleanup**: the upload worked but the test object could not be deleted. This is a soft warning. Delete the leftover `__workshop_test__/` object by hand.

## Bucket policy notes

Each presigned URL is bound to one exact object key, the file’s SHA-256. The host can write that single object and nothing else.

Do not require a content type on uploads. Santa does not send one, and a policy that requires a content type will reject every upload.

Each URL is valid for a few minutes, so an upload must finish within that window. No CORS configuration is needed, because the upload runs server to server rather than from a browser.

## See Also

-   [Binary Upload](https://northpole.security/docs/workshop/binary-upload)
-   [Filter Expressions](https://northpole.security/docs/workshop/binary-upload/filter-expressions)

## Sitemap

- [Home](https://northpole.security/index.md)
- [Workshop](https://northpole.security/workshop.md)
- [Santa](https://northpole.security/santa.md)
- [Features](https://northpole.security/features.md)
- [Cookbook](https://northpole.security/cookbook.md)
- [Docs](https://northpole.security/docs.md)
- [Blog](https://northpole.security/blog.md)
- [Glossary](https://northpole.security/glossary.md)
- [About](https://northpole.security/about.md)
- [Contact](https://northpole.security/contact.md)