Amazon S3 Storage Integration

Audience: System/Security Administrators

Skill Prerequisites: Amazon S3, AWS IAM, File Management

The Amazon S3 Storage Integration stores the files of chosen portal folders in an Amazon S3 bucket instead of on the web server's disk. You create an S3 folder type that points to a bucket, then create folders with that type. Files uploaded to those folders are saved in S3. Files that other tools put in the bucket appear in the folder after it's synchronized.

Users and actions work with these folders like any other folder. Files are still served through your site, so folder permissions apply and the bucket doesn't need to be public.

note

This integration is a separate add-on (DnnSharp.S3StorageProvider) and needs the S3PRVD feature in your license. If DnnSharpS3FolderProvider isn't in the list of folder providers, the add-on isn't installed.

Typical Use Cases

• Keep large or fast-growing uploads, such as documents and media, off the web server's disk
• Give each customer or tenant their own bucket, or their own path in a shared bucket
• Share storage between the servers of a web farm
• Exchange files with other systems that read or write the same bucket

Guide

Click here for a step-by-step video on using Amazon S3 Storage Integration

Setting up S3 storage

Step 1: Create the bucket

1. In the AWS console, open Amazon S3 and click Create bucket.
2. Give the bucket a globally unique name and choose its region. The region list in Plant an App comes from the AWS SDK that ships with it, so regions AWS added recently may be missing. Choose a region you can also select in Step 4.
3. Leave Block all public access on. Plant an App reads the files with its own credentials, so the bucket doesn't need to be public.

Plant an App doesn't create buckets. The bucket must exist before you set up the folder type.

Step 2: Create an IAM user with access to the bucket

1. In the AWS console, open IAM and create a user for Plant an App. It doesn't need console access.

2. Attach a policy that only allows the bucket you created, rather than full S3 access. Replace your-bucket-name with your bucket's name:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:ListBucket",
                   "s3:GetBucketLocation",
                   "s3:GetBucketAcl"
               ],
               "Resource": "arn:aws:s3:::your-bucket-name"
           },
           {
               "Effect": "Allow",
               "Action": [
                   "s3:GetObject",
                   "s3:PutObject",
                   "s3:DeleteObject",
                   "s3:GetObjectAcl",
                   "s3:PutObjectAcl",
                   "s3:AbortMultipartUpload",
                   "s3:ListMultipartUploadParts"
               ],
               "Resource": "arn:aws:s3:::your-bucket-name/*"
           }
       ]
   }

   The ACL permissions are used when folders are renamed or moved, because the provider copies each file's access list to its new location. The multipart permissions are used for large uploads.

3. On the user's Security credentials tab, click Create access key and copy the Access key and Secret access key. AWS only shows the secret once.

Step 3: Add the S3 folder type

1. In Plant an App, go to File Management and click Manage Folder Types.
2. Add a new type. Give it a name that describes what it's for, for example S3 Customer Files.
3. Choose DnnSharpS3FolderProvider as the folder provider.
4. Fill in the settings (see the table below) and click Update.

When you click Update, Plant an App connects to AWS with the keys and checks that the bucket exists. If it can't see the bucket, the settings aren't saved.

Setting	Description
Aws Access Key	The access key ID of the IAM user from Step 2. Required.
Aws Secret Key	The secret access key of the IAM user. Required. When you edit the folder type later, type the secret key again, otherwise the bucket check fails.
Aws Region	The region the bucket is in. Required.
Bucket Name	The name of the existing bucket. Required.
Base Path Inside Bucket	Optional. A path inside the bucket that this folder type starts from, for example customers/acme. Leave empty to use the root of the bucket. Use different base paths to let several folder types share one bucket.
Map Path Structure	How portal folders are turned into paths in the bucket. See Map Path Structure. The default is Relative to Portal Root.

The access key and secret key are stored encrypted in the database.

Step 4: Create a folder with the S3 type

1. In Files, click New Folder.
2. Enter a name and choose your S3 folder type as the Folder Type.
3. Set the folder's permissions, then save.

The folder is created in the bucket too. Subfolders you add inside it use the same folder type, and are also created in S3.

Step 5: Check that it works

1. Upload a test file to the new folder.
2. In the AWS console, check that the file is in the bucket, at the path you expect.
3. Open the file from Plant an App. Its link goes through your site (LinkClick.aspx), not straight to S3.

Map Path Structure

This setting decides where a folder's files go in the bucket. In both cases the path starts at the Base Path Inside Bucket, if you set one.

For example, the portal folder Customers/Acme/ uses the S3 folder type, and Customers/ is a standard folder:

Option	File Customers/Acme/invoice.pdf is stored as	Use it when
Relative to Portal Root (default)	Customers/Acme/invoice.pdf	The bucket should mirror the portal's folder tree.
Relative to Folder	Acme/invoice.pdf	The S3 folder sits deep in the portal, and you don't want the parent folders repeated in the bucket.

Choose the option before you add files. Changing it later doesn't move files that are already in the bucket, so Plant an App looks for them in the wrong place.

Setting it up from actions

To create storage for each new customer automatically, use actions instead of the steps above:

1. Manage S3 Service Connection creates the folder type and returns its ID.
2. Get or Create Folder creates a folder with that type, using the ID as its Storage Connection.
3. Alter Folder Permissions sets who can use the folder.

The bucket and the IAM user still have to be created in AWS first. Get or Create Folder and Alter Folder Permissions are part of the File Management add-on. See it and the core File Management actions for the other file and folder actions.

Considerations

• Existing files aren't moved. The integration only applies to folders created with the S3 type. Files already in other folders stay where they are. To put them in S3, copy them into an S3 folder.
• Files added outside Plant an App. Files that another tool writes to the bucket appear after the folder is synchronized, for example with Synchronize Folder or the sync option in Files. In 1.28, a sync only reads the first 1,000 files in each S3 folder.
• Replacing a file. In 1.28, overwriting an existing file with a new upload of the same name may leave the old content in S3, because the provider doesn't implement file updates. Delete the old file first, or upload under a new name, and check the result.
• Deleting a folder type. Move or delete the folders that use it first. Deleting folders in Plant an App also deletes their files from S3.
• Rotating keys. Create a new access key in IAM, enter it together with the secret key in the folder type settings, then deactivate the old key. With actions, use the Update mode of Manage S3 Service Connection, which needs every setting entered again.
• Performance and cost. Every file is read from S3 through your web server, and listing or syncing a folder makes requests to AWS. Choose a bucket region close to your web server. Keep often-used static files, such as images in your theme, in standard folders.
• Security. Anyone with access to the database and the application can recover the stored AWS keys. Limit the IAM user to the bucket it needs, as in Step 2, and never reuse keys from an account administrator.

Troubleshooting

Problem	What to check
The folder type won't save, with The specified bucket does not exist. or an AWS error	The bucket name, the region, and that the IAM user can list the bucket. When editing an existing folder type, type the secret key again.
Manage S3 Service Connection fails with AWS S3 Bucket ... already exists	The message is misleading. It means the bucket wasn't found, or the keys can't see it.
Uploads fail with S3 Credentials invalid	The access key was deleted or deactivated in IAM, or the secret key is wrong.
Files uploaded through another tool don't appear	Synchronize the folder, and check that the files are under the path Map Path Structure expects.
Renaming or moving a folder fails	The IAM user needs s3:GetObjectAcl and s3:PutObjectAcl.

Revised 10/02/2026