Amplify Libraries

FeedbackFeedbackEditEditDiscord LogoChat with usWe'd love your feedback

Storage

Getting started

Prerequisite: Install and configure the Amplify CLI

Storage with Amplify

AWS Amplify Storage module provides a simple mechanism for managing user content for your app in public, protected or private storage buckets. The Storage category comes with built-in support for Amazon S3.

There are two ways to add storage with Amplify - manual and automated. Both methods require the auth category with Amazon Cognito to also be enabled. If you are creating an S3 bucket from scratch, you should use the Automated Setup. However if you are reusing existing Cognito and S3 resources, you should opt for Manual Setup.

Automated Setup: Create storage bucket

To start from scratch, run the following command from the root of your project:

amplify add storage

amplify add storage

and select Content in prompted options:

? Please select from one of the below mentioned services (Use arrow keys) ❯ Content (Images, audio, video, etc.) NoSQL Database

? Please select from one of the below mentioned services (Use arrow keys) ❯ Content (Images, audio, video, etc.) NoSQL Database

The CLI will walk you though the options to enable Auth, if not enabled previously, and name your S3 bucket. To update your backend run:

amplify push

amplify push

When your backend is successfully updated, your new configuration file aws-exports.js is copied under your source directory, e.g. ‘/src’.

Configure your application

Add Amplify to your app with yarn or npm:

npm install -S aws-amplify

npm install -S aws-amplify

In your app’s entry point i.e. App.js, import and load the configuration file aws-exports.js which has been created and replaced into /src folder in the previous step.

import Amplify, { Storage } from 'aws-amplify'; import awsconfig from './aws-exports'; Amplify.configure(awsconfig);

import Amplify, { Storage } from 'aws-amplify'; import awsconfig from './aws-exports'; Amplify.configure(awsconfig);

Manual Setup: Import storage bucket

To configure Storage manually, you will have to configure Amplify Auth category as well. In other words, you will not be importing the autogenerated aws-exports.js - instead, you will be adding your own existing Amazon Cognito and Amazon S3 credentials in your app like this:

import Amplify, { Auth, Storage } from 'aws-amplify'; Amplify.configure({ Auth: { identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', //REQUIRED - Amazon Cognito Identity Pool ID region: 'XX-XXXX-X', // REQUIRED - Amazon Cognito Region userPoolId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito User Pool ID userPoolWebClientId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito Web Client ID }, Storage: { AWSS3: { bucket: '', //REQUIRED - Amazon S3 bucket name region: 'XX-XXXX-X', //OPTIONAL - Amazon service region } } });

import Amplify, { Auth, Storage } from 'aws-amplify'; Amplify.configure({ Auth: { identityPoolId: 'XX-XXXX-X:XXXXXXXX-XXXX-1234-abcd-1234567890ab', //REQUIRED - Amazon Cognito Identity Pool ID region: 'XX-XXXX-X', // REQUIRED - Amazon Cognito Region userPoolId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito User Pool ID userPoolWebClientId: 'XX-XXXX-X_abcd1234', //OPTIONAL - Amazon Cognito Web Client ID }, Storage: { AWSS3: { bucket: '', //REQUIRED - Amazon S3 bucket name region: 'XX-XXXX-X', //OPTIONAL - Amazon service region } } });

Using Amazon S3

If you set up your Cognito resources manually, the roles will need to be given permission to access the S3 bucket.

There are two roles created by Cognito: an Auth_Role that grants signed-in-user-level bucket access and an Unauth_Role that allows unauthenticated access to resources. Attach the corresponding policies to each role for proper S3 access. Replace {enter bucket name} with the correct S3 bucket.

Inline policy for the Auth_Role:

{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/public/*", "arn:aws:s3:::{enter bucket name}/protected/${cognito-identity.amazonaws.com:sub}/*", "arn:aws:s3:::{enter bucket name}/private/${cognito-identity.amazonaws.com:sub}/*" ], "Effect": "Allow" }, { "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/uploads/*" ], "Effect": "Allow" }, { "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/protected/*" ], "Effect": "Allow" }, { "Condition": { "StringLike": { "s3:prefix": [ "public/", "public/*", "protected/", "protected/*", "private/${cognito-identity.amazonaws.com:sub}/", "private/${cognito-identity.amazonaws.com:sub}/*" ] } }, "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::{enter bucket name}" ], "Effect": "Allow" } ] }

{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/public/*", "arn:aws:s3:::{enter bucket name}/protected/${cognito-identity.amazonaws.com:sub}/*", "arn:aws:s3:::{enter bucket name}/private/${cognito-identity.amazonaws.com:sub}/*" ], "Effect": "Allow" }, { "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/uploads/*" ], "Effect": "Allow" }, { "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/protected/*" ], "Effect": "Allow" }, { "Condition": { "StringLike": { "s3:prefix": [ "public/", "public/*", "protected/", "protected/*", "private/${cognito-identity.amazonaws.com:sub}/", "private/${cognito-identity.amazonaws.com:sub}/*" ] } }, "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::{enter bucket name}" ], "Effect": "Allow" } ] }

Inline policy for the Unauth_Role:

{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/public/*" ], "Effect": "Allow" }, { "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/uploads/*" ], "Effect": "Allow" }, { "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/protected/*" ], "Effect": "Allow" }, { "Condition": { "StringLike": { "s3:prefix": [ "public/", "public/*", "protected/", "protected/*" ] } }, "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::{enter bucket name}" ], "Effect": "Allow" } ] }

{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:GetObject", "s3:PutObject", "s3:DeleteObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/public/*" ], "Effect": "Allow" }, { "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/uploads/*" ], "Effect": "Allow" }, { "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::{enter bucket name}/protected/*" ], "Effect": "Allow" }, { "Condition": { "StringLike": { "s3:prefix": [ "public/", "public/*", "protected/", "protected/*" ] } }, "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::{enter bucket name}" ], "Effect": "Allow" } ] }

The policy template that Amplify CLI uses is found here.

Amazon S3 Bucket CORS Policy Setup

To make calls to your S3 bucket from your App, you need to set up a CORS Policy for your S3 bucket. This callout is only for manual configuration of your S3 bucket, CORS Policy configuration is done automatically via Amplify CLI when running amplify add storage.

The following steps will set up your CORS Policy:

  1. Go to Amazon S3 Console and click on your project’s userfiles bucket, which is normally named as [Project Name]-userfiles-mobilehub-[App Id].
  2. Click on the Permissions tab for your bucket, and then click on the CORS configuration tile.
  3. Update your bucket’s CORS Policy to look like:

[ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "GET", "HEAD", "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "*" ], "ExposeHeaders": [ "x-amz-server-side-encryption", "x-amz-request-id", "x-amz-id-2", "ETag" ], "MaxAgeSeconds": 3000 } ]

[ { "AllowedHeaders": [ "*" ], "AllowedMethods": [ "GET", "HEAD", "PUT", "POST", "DELETE" ], "AllowedOrigins": [ "*" ], "ExposeHeaders": [ "x-amz-server-side-encryption", "x-amz-request-id", "x-amz-id-2", "ETag" ], "MaxAgeSeconds": 3000 } ]

Note: You can restrict the access to your bucket by updating AllowedOrigin to include individual domains.

For information on Amazon S3 file access levels, please see file access levels.

Using a Custom Plugin

You can create your custom pluggable for Storage. This may be helpful if you want to integrate your app with a custom storage backend.

To create a plugin implement the StorageProvider interface:

import { Storage, StorageProvider } from 'aws-amplify'; export default class MyStorageProvider implements StorageProvider { // category and provider name static category = 'Storage'; static providerName = 'MyStorage'; // you need to implement these seven methods // configure your provider configure(config: object): object; // get object/pre-signed url from storage get(key: string, options?): Promise<String|Object> // upload storage object put(key: string, object, options?): Promise<Object> // remove object remove(key: string, options?): Promise<any> // list objects for the path list(path, options?): Promise<any> // return 'Storage'; getCategory(): string; // return the name of you provider getProviderName(): string;

import { Storage, StorageProvider } from 'aws-amplify'; export default class MyStorageProvider implements StorageProvider { // category and provider name static category = 'Storage'; static providerName = 'MyStorage'; // you need to implement these seven methods // configure your provider configure(config: object): object; // get object/pre-signed url from storage get(key: string, options?): Promise<String|Object> // upload storage object put(key: string, object, options?): Promise<Object> // remove object remove(key: string, options?): Promise<any> // list objects for the path list(path, options?): Promise<any> // return 'Storage'; getCategory(): string; // return the name of you provider getProviderName(): string;

You can now register your pluggable:

// add the plugin Storage.addPluggable(new MyStorageProvider()); // get the plugin Storage.getPluggable(MyStorageProvider.providerName); // remove the plugin Storage.removePluggable(MyStorageProvider.providerName); // send configuration into Amplify Storage.configure({ [MyStorageProvider.providerName]: { // My Storage provider configuration } });

// add the plugin Storage.addPluggable(new MyStorageProvider()); // get the plugin Storage.getPluggable(MyStorageProvider.providerName); // remove the plugin Storage.removePluggable(MyStorageProvider.providerName); // send configuration into Amplify Storage.configure({ [MyStorageProvider.providerName]: { // My Storage provider configuration } });

The default provider (Amazon S3) is in use when you call Storage.put( ) unless you specify a different provider: Storage.put(key, object, {provider: 'MyStorageProvider'}).

Mocking and Local Testing with Amplify CLI

Amplify CLI supports running a local mock server for testing your application with Amazon S3. Please see the CLI toolchain documentation for more details.

API Reference

For the complete API documentation for Storage module, visit our API Reference.

next

Concepts

Next Page
Discord Logo
Amplify open source, documentation and community are supported by Amazon Web Services © 2021, Amazon Web Services, Inc. and its affiliates. All rights reserved. View the site terms and privacy policy.
    Flutter and the related logo are trademarks of Google LLC. We are not endorsed by or affiliated with Google LLC.