Skip to content

Commit 858579e

Browse files
tiffanynwyeungtiffanynwyeung
committed
fix(storage): update instructions for adding/integrating with external S3 buckets
1 parent 198fbfc commit 858579e

File tree

1 file changed

+142
-23
lines changed
  • src/pages/[platform]/build-a-backend/storage/use-with-custom-s3

1 file changed

+142
-23
lines changed

‎src/pages/[platform]/build-a-backend/storage/use-with-custom-s3/index.mdx‎

Lines changed: 142 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -44,36 +44,41 @@ To do this, go to **Amazon S3 console** > **Select the S3 bucket** > **Permissio
4444

4545
![Showing Amplify console showing Storage tab selected](/images/gen2/storage/s3-console-permissions.png)
4646

47-
The policy will look something like this
47+
The policy will look something like this:
4848

4949
```json
5050
{
51-
"Version": "2012-10-17",
52-
"Statement": [
53-
{
54-
"Sid": "Statement1",
55-
"Principal": { "AWS": "arn:aws:iam::<AWS-account-ID>:role/<role-name>" },
56-
"Effect": "Allow",
57-
"Action": [
58-
"s3:PutObject",
59-
"s3:GetObject",
60-
"s3:DeleteObject",
61-
"s3:ListBucket"
62-
],
63-
"Resource": [
64-
"arn:aws:s3:::<bucket-name>/*"
65-
]
66-
}
67-
]
51+
"Version": "2012-10-17",
52+
"Statement": [
53+
{
54+
"Sid": "Statement1",
55+
"Principal": { "AWS": "arn:aws:iam::<AWS-account-ID>:role/<role-name>" },
56+
"Effect": "Allow",
57+
"Action": [
58+
"s3:PutObject",
59+
"s3:GetObject",
60+
"s3:DeleteObject",
61+
"s3:ListBucket"
62+
],
63+
"Resource": [
64+
"arn:aws:s3:::<bucket-name>/",
65+
"arn:aws:s3:::<bucket-name>/*"
66+
]
67+
}
68+
]
6869
}
6970
```
7071
Replace `<AWS-account-ID>` with your AWS account ID and `<role-name>` with the IAM role associated with your Amplify Auth setup. Replace `<bucket-name>` with the S3 bucket name.
7172

7273
You can refer to [Amazon S3's Policies and Permissions documentation](https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-policy-language-overview.html) for more ways to customize access to the bucket.
7374

75+
<Callout warning>
76+
In order to make calls to your S3 bucket from your application, you must also set up a CORS Policy for your S3 bucket. This applies only to manually-configured S3 buckets. Learn more about [setting up a CORS Policy for your S3 bucket](/[platform]/build-a-backend/storage/extend-s3-resources/#for-manually-configured-s3-resources).
77+
</Callout>
78+
7479
### Specify S3 bucket in Amplify's backend config
7580

76-
Next, use the `addOutput` method from the backend definition object to define a custom s3 bucket by specifying the name and region of the bucket in your **amplify/backend.ts** file.
81+
Next, use the `addOutput` method from the backend definition object to define a custom S3 bucket by specifying the name and region of the bucket in your **amplify/backend.ts** file.
7782

7883
<Callout>
7984

@@ -85,7 +90,10 @@ If you specify a custom S3 bucket, no sandbox storage resource will be created.
8590

8691
</Callout>
8792

88-
```javascript
93+
Below is an example of configuring the backend to define a custom S3 bucket:
94+
95+
{/* cSpell:disable */}
96+
```ts title="amplify/backend.ts"
8997

9098
import { defineBackend } from '@aws-amplify/backend';
9199
import { auth } from './auth/resource';
@@ -100,9 +108,89 @@ const backend = defineBackend({
100108
backend.addOutput({
101109
storage: {
102110
aws_region: "<region>",
103-
bucket_name: "<bucket-name>"
111+
bucket_name: "<bucket-name>",
112+
// optional: `buckets` can be used when setting up more than one existing bucket
113+
buckets: [
114+
{
115+
aws_region: "<region>",
116+
bucket_name: "<bucket-name>",
117+
name: "<bucket-name>",
118+
// optional: `paths` can be used to set up access to specific bucket prefixes,
119+
// and configure access to those prefixes for different user types
120+
// @ts-expect-error: Amplify backend type issue — https://github.com/aws-amplify/amplify-backend/issues/2569
121+
paths: {
122+
"public/*": {
123+
guest: ["get", "list"],
124+
authenticated: ["get", "list", "write", "delete"],
125+
},
126+
"admin/*": {
127+
groupsadmin: ["get", "list", "write", "delete"],
128+
authenticated: ["get", "list", "write", "delete"],
129+
},
130+
},
131+
}
132+
]
104133
},
105134
});
135+
{/* cSpell:enable */}
136+
137+
// Define an inline policy to attach to Amplify's un-auth role
138+
// This policy defines how unauthenticated users can access your existing bucket
139+
const unauthPolicy = new Policy(backend.stack, 'customBucketUnauthPolicy', {
140+
statements: [
141+
new PolicyStatement({
142+
effect: Effect.ALLOW,
143+
actions: ['s3:GetObject'],
144+
resources: [`arn:aws:s3:::${customBucketName}/public/*`],
145+
}),
146+
new PolicyStatement({
147+
effect: Effect.ALLOW,
148+
actions: ['s3:ListBucket'],
149+
resources: [`arn:aws:s3:::${customBucketName}`],
150+
conditions: {
151+
StringLike: {
152+
's3:prefix': ['public/', 'public/*'],
153+
},
154+
},
155+
}),
156+
],
157+
});
158+
159+
// Define an inline policy to attach to Amplify's auth role
160+
// This policy defines how authenticated users can access your existing bucket
161+
const authPolicy = new Policy(backend.stack, "customBucketAuthPolicy", {
162+
statements: [
163+
new PolicyStatement({
164+
effect: Effect.ALLOW,
165+
actions: ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],
166+
resources: [
167+
`arn:aws:s3:::${customBucketName}/public/*`,
168+
`arn:aws:s3:::${customBucketName}/protected/*`,
169+
],
170+
}),
171+
new PolicyStatement({
172+
effect: Effect.ALLOW,
173+
actions: ["s3:ListBucket"],
174+
resources: [`arn:aws:s3:::${customBucketName}`],
175+
conditions: {
176+
StringLike: {
177+
"s3:prefix": ["public/*", "public/", "admin/*", "admin/"],
178+
},
179+
},
180+
}),
181+
],
182+
});
183+
184+
// Add the policies to the unauthenticated user role
185+
backend.auth.resources.unauthenticatedUserIamRole.attachInlinePolicy(
186+
unauthPolicy,
187+
);
188+
189+
// Add the policies to the authenticated user role
190+
backend.auth.resources.authenticatedUserIamRole.attachInlinePolicy(authPolicy);
191+
192+
// Add the policies to the admin user role
193+
backend.auth.resources.groups["admin"].role.attachInlinePolicy(adminPolicy);
106194
//highlight-end
107195

108196
```
@@ -137,7 +225,6 @@ In addition to manually configuring your storage options, you will also need to
137225
### Using Amplify configure
138226
Existing storage resource setup can be accomplished by passing the resource metadata to `Amplify.configure`. This will configure the Amplify Storage client library to interact with the additional resources. It's recommended to add the Amplify configuration step as early as possible in the application lifecycle, ideally at the root entry point.
139227

140-
141228
```ts
142229
import { Amplify } from 'aws-amplify';
143230

@@ -169,6 +256,7 @@ Amplify.configure({
169256

170257
Alternatively, existing storage resources can be used by creating or modifying the `amplify_outputs.json` file directly.
171258

259+
{/* cSpell:disable */}
172260
```ts title="amplify_outputs.json"
173261
{
174262
"auth": {
@@ -182,7 +270,37 @@ Alternatively, existing storage resources can be used by creating or modifying t
182270
{
183271
"name": "<your-default-bucket-friendly-name>",
184272
"bucket_name": "<your-default-bucket-name>",
185-
"aws_region": "<your-default-bucket-region>"
273+
"aws_region": "<your-default-bucket-region>",
274+
// optional: `paths` can be used to set up access to specific bucket prefixes,
275+
// and configure access to those prefixes for different user types
276+
"paths": {
277+
"public/*": {
278+
"guest": [
279+
"get",
280+
"list"
281+
],
282+
"authenticated": [
283+
"get",
284+
"list",
285+
"write",
286+
"delete"
287+
]
288+
},
289+
"admin/*": {
290+
"authenticated": [
291+
"get",
292+
"list",
293+
"write",
294+
"delete"
295+
],
296+
"groupsadmin": [
297+
"get",
298+
"list",
299+
"write",
300+
"delete"
301+
]
302+
}
303+
}
186304
},
187305
{
188306
"name": "<your-additional-bucket-friendly-name>",
@@ -193,4 +311,5 @@ Alternatively, existing storage resources can be used by creating or modifying t
193311
}
194312
}
195313
```
314+
{/* cSpell:enable */}
196315
</InlineFilter>

0 commit comments

Comments
 (0)