Prerequisites
Before deploying BucketDrive, ensure you have the following:
- AWS Account — An active AWS account with permissions to create CloudFormation stacks, Lambda functions, DynamoDB tables, Cognito user pools, and CloudFront distributions.
- S3 Buckets — One or more S3 buckets containing the files you want to share. These can be existing buckets — BucketDrive does not modify your data.
- AWS Marketplace Access — Ability to subscribe to products on AWS Marketplace (requires a valid payment method on the AWS account).
- Admin Email — An email address for the initial admin user account.
Step 1: Deploy from AWS Marketplace
BucketDrive deploys as a CloudFormation stack directly into your AWS account. The entire process takes about 5 minutes.
Subscribe on AWS Marketplace
Navigate to the BucketDrive listing on AWS Marketplace and click Continue to Subscribe. Accept the terms and wait for the subscription to activate (usually instant).
Launch the CloudFormation Stack
Click Continue to Configuration, select your preferred AWS region, and then click Continue to Launch. Choose Launch CloudFormation as the deployment method.
Configure Stack Parameters
You'll be prompted for a few parameters:
| Parameter | Description |
|---|---|
AdminEmail | Email for the initial admin user. A temporary password will be sent here. |
StackName | A name for the CloudFormation stack (e.g., bucketdrive). |
Wait for Deployment
Click Create stack. CloudFormation will create all resources — Cognito user pool, Lambda functions, API Gateway, DynamoDB tables, CloudFront distribution, and the frontend. This typically takes 3–5 minutes.
When the status changes to CREATE_COMPLETE, find your portal URL in the Outputs tab. It will look like: https://d1234abcde.cloudfront.net
Step 2: First Admin Login
After deployment completes, you'll receive a temporary password by email.
Open the Portal URL
Navigate to the CloudFront URL from the stack outputs. You'll see the BucketDrive login page.
Sign In with Temporary Password
Enter your admin email and the temporary password from the email. You'll be prompted to set a new permanent password.
Access the Admin Portal
After setting your password, you'll be signed in. Navigate to /admin to access the admin portal. Your account is automatically assigned to the admins Cognito group during deployment.
<your-cloudfront-url>/admin. Only users in the admins Cognito group can access it.
Step 3: Connect S3 Buckets
Tell BucketDrive which S3 buckets your users should be able to access.
Navigate to Bucket Settings
In the admin portal, go to Buckets in the sidebar. Click Add Bucket.
Enter Bucket Details
Provide the following:
| Field | Description |
|---|---|
Bucket Name | The exact name of the S3 bucket (e.g., company-shared-files). |
Display Name | A friendly name shown to users (e.g., "Shared Files"). |
Prefix | Optional. Restrict access to a specific folder prefix (e.g., public/). Leave empty for full bucket access. |
Region | The AWS region where the bucket is located. |
Grant Access to the Bucket
BucketDrive needs read access to your S3 bucket. The deployment creates a Lambda execution role — you'll need to add a bucket policy or IAM policy that allows this role to perform s3:ListBucket and s3:GetObject actions.
The admin portal shows the exact IAM role ARN and a sample bucket policy you can copy and apply.
Step 4: Create Access Groups
Groups control which users can see which buckets. Each group maps to a Cognito group and defines what the members can access.
Create a New Group
In the admin portal, go to Groups and click Create Group. Enter a group name (e.g., "Engineering", "Clients", "Partners").
This creates a corresponding Cognito group automatically.
Assign Bucket Access
For each group, select which buckets (and optional prefixes) the group members can access. You can grant access to multiple buckets per group.
Set Access Level
Choose the permission level for each bucket assignment:
- Read — Users can browse and download files.
- Read/Write — Users can also upload files to the bucket prefix.
Step 5: Add Users
Invite team members, partners, or clients to access the file portal.
Invite Users
Go to Users in the admin portal and click Add User. Enter the user's email address and select which groups they should belong to.
The user will receive an email with a temporary password and a link to the portal.
Manage Group Membership
You can add or remove users from groups at any time. Changes take effect immediately — the user's accessible buckets update on their next page load.
Promote Admins
To give a user admin access, add them to the admins group. Admin users can access both the user portal and the admin portal.
Step 6: Set Permissions
Fine-tune access controls for each group-bucket combination.
Configure Download Settings
For each bucket assignment, you can configure:
- Pre-signed URL expiry — How long download links remain valid (default: 1 hour).
- Allowed file types — Restrict downloads to specific file extensions.
Configure Upload Settings
If the group has read/write access:
- Max file size — Limit the size of uploaded files.
- Allowed upload types — Restrict which file types can be uploaded.
- Upload prefix — Optionally direct uploads to a specific sub-folder.
Configure SSO (Optional)
Connect your existing identity provider so users can sign in with their corporate credentials.
Add an Identity Provider
In the admin portal, go to Settings > SSO. Click Add Provider and select your identity provider type:
- SAML — For Okta, Azure AD, OneLogin, PingFederate, and other SAML 2.0 providers.
- OIDC — For Google Workspace, Auth0, or any OpenID Connect provider.
Configure the Provider
Enter the provider's metadata URL or upload the metadata XML. BucketDrive will display the Cognito callback URLs you need to configure on the provider side.
| Provider | What You'll Need |
|---|---|
| Okta | Metadata URL from your Okta SAML app |
| Azure AD | Federation metadata XML URL |
| Google Workspace | Client ID and Client Secret from Google Console |
Map Groups
Configure attribute mapping so that your IdP groups are automatically mapped to BucketDrive access groups. Users will be assigned to the correct groups on sign-in.
Custom Branding (Optional)
Customize the portal's appearance to match your organization.
Update Branding Settings
In the admin portal, go to Settings > Branding. You can customize:
- Logo — Upload your company logo (displayed in the navigation bar and login page).
- Primary color — Set the accent color used for buttons, links, and highlights.
- Portal title — Change the page title and heading shown to users.
- Favicon — Upload a custom browser tab icon.
Audit Logs
BucketDrive logs every file access to DynamoDB, giving you full visibility into who accessed what, when, and from where.
View Audit Logs
In the admin portal, go to Audit Logs. Each entry includes:
- User — The email of the user who performed the action.
- Action — What they did (e.g., file download, file upload, login).
- Resource — The bucket and object key accessed.
- Timestamp — When the action occurred.
- IP Address — The source IP address.
Filter and Search
Filter logs by user, action type, bucket, or date range. Use the search bar to find specific events by file name or user email.
Export Logs
Export audit data as CSV for compliance reports, internal reviews, or integration with external SIEM tools.
Architecture Overview
BucketDrive is a fully serverless application that runs entirely in your AWS account. Here's what gets deployed:
CloudFront
CDN distribution serving the React frontend and proxying API requests. Provides HTTPS, caching, and global edge delivery.
S3 (Frontend)
Hosts the static React application files. Served through CloudFront — not publicly accessible directly.
API Gateway + Lambda
REST API handling authentication, file listing, pre-signed URL generation, and admin operations. Five Lambda functions, each with a single responsibility.
Cognito
User pool managing authentication, user accounts, groups, and optional SSO federation. Supports SAML and OIDC providers.
DynamoDB
Two tables — one for configuration (bucket mappings, group permissions, branding) and one for audit logs. Single-table design with pk/sk pattern.
Your S3 Buckets
Your existing data buckets. BucketDrive only reads listings and generates pre-signed URLs — files are never copied or proxied.
CORS & Security
When you connect an S3 bucket, BucketDrive automatically sets a CORS (Cross-Origin Resource Sharing) policy on it. This section explains what that means and why it's necessary.
Why is CORS needed?
BucketDrive uses pre-signed URLs for file uploads and downloads. Instead of routing files through a server, users' browsers interact directly with S3 — this is faster, cheaper, and more scalable. However, browsers block cross-origin requests by default. Since your portal (e.g., files.company.com) and S3 (s3.amazonaws.com) are different origins, S3 needs a CORS policy to tell the browser "yes, this request is allowed."
What exactly is configured?
BucketDrive applies the following CORS rule to your bucket:
| Setting | Value | Why |
|---|---|---|
AllowedOrigins | * | Your portal domain may vary (CloudFront URL, custom domain, etc.), so all origins are permitted. |
AllowedMethods | GET, PUT, HEAD | Required for file downloads (GET), uploads (PUT), and metadata checks (HEAD). |
AllowedHeaders | * | Allows the browser to send required headers like Content-Type. |
MaxAgeSeconds | 3600 | Browsers cache the CORS preflight response for 1 hour, reducing extra requests. |
Does this make my bucket public?
No. CORS and bucket access control are completely separate mechanisms:
- Bucket privacy (Block Public Access, IAM policies, bucket policies) controls who can access your data. These are not changed.
- CORS is a browser-level setting. It tells the browser whether to allow a cross-origin request to proceed. It does not grant any access that doesn't already exist.
Your bucket remains fully private. Every file download and upload requires a pre-signed URL — a temporary, cryptographically signed link that expires after 1 hour. Without a valid pre-signed URL, requests to your bucket are rejected regardless of CORS settings. Tools like curl or Postman bypass CORS entirely (it's purely a browser restriction), and they still can't access your bucket without a valid pre-signed URL.
Troubleshooting
I didn't receive the temporary password email
Check your spam/junk folder. The email comes from Cognito (usually no-reply@verificationemail.com). If you still can't find it, you can reset the password through the Cognito console in the AWS Management Console — find the user pool created by BucketDrive, locate the admin user, and choose "Reset password".
The CloudFormation stack failed to create
Check the Events tab of the CloudFormation stack for error details. Common causes:
- Insufficient IAM permissions — ensure your AWS user/role has permission to create the required resources.
- Service limit reached — request a limit increase for Lambda functions, Cognito user pools, or CloudFront distributions.
- Region not supported — make sure you're deploying in a region that supports all required services.
Users can't see any buckets after logging in
This usually means the user isn't assigned to any access groups, or the groups don't have bucket permissions configured. In the admin portal:
- Check that the user is added to at least one group under Users.
- Check that the group has at least one bucket assigned under Groups.
- Verify the bucket policy allows the BucketDrive Lambda role to access the bucket.
Download links aren't working or return "Access Denied"
Pre-signed URLs require the Lambda execution role to have s3:GetObject permission on the target bucket/objects. Verify the bucket policy includes the IAM role ARN shown in the admin portal under Buckets > [your bucket] > IAM Role.
Also check that the URL hasn't expired — default expiry is 1 hour.
File uploads fail with a CORS error
BucketDrive automatically configures CORS on your S3 bucket when you connect it. If uploads still fail with a CORS error, the CORS configuration may have been removed or overwritten. To fix this:
- In the admin portal, go to Buckets and click Edit on the affected bucket, then Save. This re-applies the CORS configuration.
- If the issue persists, verify that the BucketDrive Lambda role has
s3:PutBucketCorspermission on the bucket.
See CORS & Security for more details on what BucketDrive configures and why.
How do I update BucketDrive to a newer version?
Updates are delivered through CloudFormation stack updates. When a new version is available on AWS Marketplace, navigate to the stack in CloudFormation and choose Update stack. Your configuration, users, and audit logs are preserved.
How do I delete BucketDrive from my account?
Delete the CloudFormation stack from the AWS console. This removes all BucketDrive resources (Lambda functions, DynamoDB tables, CloudFront distribution, Cognito user pool). Your S3 data buckets are never deleted — only the BucketDrive infrastructure is removed.
Don't forget to cancel your AWS Marketplace subscription as well.
Need Help?
Can't find what you're looking for? Reach out and we'll help you get set up.