File access levels
When adding the Storage category, you configure the level of access users have to your S3 bucket. You can configure separate rules for authenticated vs. guest users. When using the Storage category to upload files, you can also specify an access level for each individual file: guest, protected, or private.
- Guest Accessible by all users of your application
- Protected Readable by all users, but only writable by the creating user
- Private Readable and writable only by the creating user
Guest access does not mean that your files are totally public. A "guest" is a user of your application who has not yet signed in. To enable access at this level, you will still be required to configured Authentication in your app. The user must be able to assume an unauthenticated role from your Cognito Identity Pool.
For protected and private access, the [IDENTITY_ID] below corresponds to the unique ID of the user. Once the user has signed in, the [IDENTITY_ID] can be retrieved from the session by accessing the identity id. See Accessing credentials to retrieve the identity id, and use this as the unique ID of the authenticated user.
Protected access
After the user has signed in, create an options object specifying the protected access level to allow other users to read the object:
import 'dart:io';import 'package:path_provider/path_provider.dart';
Future<void> uploadProtected() async { // Create a dummy file const exampleString = 'Example file contents'; final tempDir = await getTemporaryDirectory(); final exampleFile = File(tempDir.path + '/example.txt') ..createSync() ..writeAsStringSync(exampleString);
// Set the access level to `protected` for the current user // Note: A user must be logged in through Cognito Auth // for this to work. final uploadOptions = S3UploadFileOptions( accessLevel: StorageAccessLevel.protected, );
// Upload the file to S3 with protected access try { final UploadFileResult result = await Amplify.Storage.uploadFile( local: exampleFile, key: 'ExampleKey', options: uploadOptions, onProgress: (progress) { safePrint('Fraction completed: ${progress.getFractionCompleted()}'); } ); safePrint('Successfully uploaded file: ${result.key}'); } on StorageException catch (e) { safePrint('Error uploading protected file: $e'); }}This will upload with the prefix /protected/[IDENTITY_ID]/ followed by the key.
For other users to read the file, you must specify the user ID of the creating user in the passed options.
import 'dart:io';import 'package:path_provider/path_provider.dart';
Future<void> downloadProtected(String cognitoIdentityId) async { // Create a file to store downloaded contents final documentsDir = await getApplicationDocumentsDirectory(); final filepath = documentsDir.path + '/example.txt'; final file = File(filepath);
// Set access level and Cognito Identity ID. // Note: `targetIdentityId` is only needed when downloading // protected files of a user other than the one currently // logged in. final downloadOptions = S3DownloadFileOptions( accessLevel: StorageAccessLevel.protected,
// e.g. us-west-2:2f41a152-14d1-45ff-9715-53e20751c7ee targetIdentityId: cognitoIdentityId, );
// Download protected file and read contents try { await Amplify.Storage.downloadFile( key: 'ExampleKey', local: file, options: downloadOptions, ); final contents = file.readAsStringSync(); safePrint('Got protected file with contents: $contents'); } on StorageException catch (e) { safePrint('Error downloading protected file: $e'); }}Private Access
Create an options object specifying the private access level to only allow an object to be accessed by the creating user
Future<void> uploadPrivateFile() async { ... // Update the uploadOptions final uploadOptions = S3UploadFileOptions( // Add the private access level accessLevel: StorageAccessLevel.private, );
try { final UploadFileResult result = await Amplify.Storage.uploadFile( ... //Be sure to use the options options: uploadOptions, ... ); safePrint('Successfully uploaded file: ${result.key}'); }...}This will upload with the prefix /private/[IDENTITY_ID]/, followed by the key.
For the user to read the file, specify the same access level (private) and key you used to upload:
Future<void> downloadPrivateFile(String cognitoIdentityId) async { ... final downloadOptions = S3DownloadFileOptions( // Add the private access level accessLevel: StorageAccessLevel.private ... );
try { await Amplify.Storage.downloadFile( ... // Be sure to use the correct options options: downloadOptions, ); ... }...}