This site is a folder of HTML files in a private S3 bucket. Nobody on the internet is allowed to read that bucket, and yet this page reached you. What let your request through, and what would have stopped it?
Two cases:
- A reader opens a page: how your browser gets this page.
- A new version is pushed: how the site updates, with no AWS key stored in the repo.
Three parties take part:
-
Cloudflare: this site,
aws.jialin00.com, is a subdomain ofjialin00.com, andjialin00.com's DNS lives in Cloudflare. Cloudflare holds four NS records foraws, pointing at AWS name servers (placeholders below, see the note above the resource table):aws NS ns-2048.awsdns-64.com aws NS ns-2049.awsdns-65.net aws NS ns-2050.awsdns-66.org aws NS ns-2051.awsdns-67.co.ukWhen someone looks up
aws.jialin00.com, Cloudflare sees these four and answers "ask these AWS name servers", and Route 53 answers with the real IP. That is all Cloudflare does for this subdomain; its proxy and cache features are not used, so once the browser has the IP, the HTTP request goes straight to CloudFront and never passes through Cloudflare. -
AWS: Route 53, ACM, CloudFront and S3 deliver the page; IAM and STS hold the permissions for deploying.
-
GitHub: holds the code; on a push, GitHub Actions builds and deploys it.
A reader opens a page
On its way from the browser and back with this page, a request passes these places:
browser
→ Cloudflare: jialin00.com's DNS, hands the name aws over to Route 53
→ Route 53: answers with a CloudFront IP
→ CloudFront: shows the ACM certificate, add-index-html appends index.html, then the cache
→ on a cache miss, asks S3 for the file, signed with OAC
→ S3: the bucket policy lets only this distribution in, and returns index.html
The first two stops only look up an IP; the HTTP request itself starts at CloudFront.
The walk below follows your browser's first request for one page. Press Next stop to move it along, or Play. Then pick one of the broken setups: the request stops at the place that needed what is missing.
Why each piece is there
Why not turn on S3 static website hosting?
Website hosting would do two jobs by itself: it serves index.html for a URL that ends in /, and it redirects /page to /page/. But the website endpoint only serves buckets that are public, and CloudFront cannot sign its requests to it. To keep the bucket private, CloudFront has to use the REST endpoint, and the REST endpoint looks up the exact key it is given. A request for /acm-auto-renew-https/ asks for a key named acm-auto-renew-https/, which does not exist.
So the CloudFront Function add-index-html does the two jobs instead, on every request, before the cache:
function handler(event) {
var uri = event.request.uri;
if (uri.endsWith('/')) { // /page/ → /page/index.html
event.request.uri = uri + 'index.html';
return event.request;
}
var last = uri.substring(uri.lastIndexOf('/') + 1);
if (last.indexOf('.') === -1) { // /page → 301 to /page/
return {
statusCode: 301,
statusDescription: 'Moved Permanently',
headers: { location: { value: uri + '/' } }
};
}
return event.request; // /fav.svg, /_next/… as they are
}Pick "CloudFront has no add-index-html function" in the walk above: the request goes all the way to S3, then gets a 403. The same slash problem on a website endpoint, where S3 answers 302 and 404 instead.
OAC and the bucket policy both seem to restrict access. Do they overlap?
No, and both are needed. Pick "CloudFront asks S3 without OAC" in the walk and CloudFront sends the request unsigned, so S3 sees an anonymous caller and the bucket policy denies it. Delete the bucket policy instead and the request arrives signed, but nothing allows that caller to read, so it is also a 403.
The two answer different questions:
- OAC: who is asking. CloudFront signs the request as
cloudfront.amazonaws.com, on behalf of distributionEDFDVBD6EXAMPLE. - Bucket policy: may that caller read.
Allow s3:GetObjectwhenPrincipal == cloudfront.amazonaws.com && SourceArn == distribution/EDFDVBD6EXAMPLE.
The certificate goes in us-east-1
CloudFront only accepts certificates from ACM in us-east-1, whatever region the bucket is in. ACM proves the domain once through a CNAME in Route 53 and renews the certificate before it expires, as long as that CNAME is still there and the certificate is attached to CloudFront (ACM renews only certificates in use). Without the CNAME nothing breaks until the expiry date; then every browser refuses the site. From Let's Encrypt to ACM auto-renew is the longer story.
A new version is pushed
The repo holds no AWS key. A push to main still ends with new files in the bucket and every edge dropping its old copies. In between:
push to main
→ GitHub Actions runs deploy.yml and asks GitHub for an OIDC token
→ STS checks the token against the OIDC provider registered in IAM
→ the role's trust policy confirms the token comes from this repo, and STS hands out one-hour credentials
→ those credentials sync out/ to S3
→ CloudFront is told to make every edge drop its old copies
The walk below follows that push; here too you can pick a setup with something missing.
The role site-deploy carries two policies, each with one job.
The trust policy decides who may assume the role, that is, get its temporary credentials. It accepts only an OIDC token signed by GitHub whose sub is this repo:
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Federated": "arn:aws:iam::111122223333:oidc-provider/token.actions.githubusercontent.com" },
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": { "token.actions.githubusercontent.com:aud": "sts.amazonaws.com" },
"StringLike": { "token.actions.githubusercontent.com:sub": "repo:your-org/your-site:*" }
}
}
]
}The inline policy deploy-permissions decides what those credentials may do: touch this one bucket, and invalidate this one distribution.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject", "s3:ListBucket"],
"Resource": ["arn:aws:s3:::example-site-bucket", "arn:aws:s3:::example-site-bucket/*"]
},
{
"Effect": "Allow",
"Action": "cloudfront:CreateInvalidation",
"Resource": "arn:aws:cloudfront::111122223333:distribution/EDFDVBD6EXAMPLE"
}
]
}Every resource, in the order to create it
All of it was set up by hand. Every account id, resource id, name server, bucket, role and repo name on this page, the walks above included, is a placeholder in the style of AWS's documentation examples; only the domains jialin00.com and aws.jialin00.com are real. The order matters because some resources need an id that exists only after an earlier one is created.
| # | Resource | Name or id | Needs |
|---|---|---|---|
| 1 | Route 53 hosted zone | Z0123456789EXAMPLE (aws.jialin00.com) |
Its four name servers go into Cloudflare as NS records |
| 2 | ACM certificate, us-east-1 | 12345678-1234-1234-1234-123456789012 |
The zone from 1, for the validation CNAME |
| 3 | S3 bucket | example-site-bucket, website hosting off |
|
| 4 | Origin access control | E2QWRUHEXAMPLE |
|
| 5 | CloudFront Function | add-index-html, viewer-request |
|
| 6 | CloudFront distribution | EDFDVBD6EXAMPLE, d111111abcdef8.cloudfront.net |
2, 3, 4 and 5 |
| 7 | Bucket policy | on example-site-bucket |
The distribution's ARN from 6 |
| 8 | Route 53 A alias | aws.jialin00.com → the distribution |
The distribution's domain from 6 |
| 9 | IAM OIDC provider | token.actions.githubusercontent.com |
|
| 10 | IAM role | site-deploy, inline policy deploy-permissions |
The provider from 9, the bucket and the distribution |
Rebuild the distribution and both its id and its cloudfront.net domain change. The bucket policy, the role's inline policy and deploy.yml have to name the new id, and the Route 53 A alias has to point at the new domain. And an alternate domain name can sit on only one distribution at a time (CloudFront docs), so aws.jialin00.com has to come off the old one before the new one can take it.