Protect downloads of your content hosted on CloudFront with Cognito authentication using cookies and [email protected]
This repo accompanies the blog post.
In that blog post a solution is explained, that puts Cognito authentication in front of (S3) downloads from CloudFront, using [email protected]. JWT's are transferred using cookies to make authorization transparent to clients.
The sources in this repo implement that solution.
The purpose of this sample code is to demonstrate how [email protected] can be used to implement authorization, with Cognito as identity provider (IDP). Please treat the code as an illustration––thoroughly review it and adapt it to your needs, if you want to use it for serious things.
(More detailed diagrams and explanation in the blog post)
The solution can be deployed to your AWS account with a few clicks, from the Serverless Application Repository.
More deployment options below: Deploying the solution
This repo is the "sibling" of another repo here on aws-samples (authorization-lambda-at-edge). The difference is that the solution in that repo uses http headers (not cookies) to transfer JWT's. While also a valid approach, the downside of it is that your Web App (SPA) needs to be altered to pass these headers, as browsers do not send these along automatically (which they do for cookies).
The repo here contains a complete [email protected] solution, i.e. predefined [email protected] code, combined with a CloudFormation template and various CloudFormation custom resources that enable one-click deployment. This CloudFormation template has various parameters, to support multiple use cases (e.g. bring your own User Pool or CloudFront distribution).
You may want to have full control and implement an [email protected] solution yourself. In that case, the NPM library cognito-at-edge, may be of use to you. It implements the same functionalities as the solution here, but wrapped conveniently in an NPM package, that you can easily include in your [email protected] functions.
This repo contains (a.o.) the following files and directories:
RewritePathWithTrailingSlashToIndex, see below)
CloudFormation custom resources in src/cfn-custom-resources:
Other files and directories:
The solution can be deployed with a few clicks from the Serverless Application Repository.
NOTE: Run the deployment commands below in a Unix-like shell such as sh, bash, zsh, etc. (i.e. Windows users: please run this in "Linux Subsystem for Windows" or in Cygwin or something similar)
git clone https://github.com/aws-samples/cloudfront-authorization-at-edge && cd cloudfront-authorization-at-edge
npm run build
sam package --output-template-file packaged.yaml --s3-bucket
sam deploy --template-file packaged.yaml --stack-name --capabilities CAPABILITY_IAM --parameter-overrides EmailAddress=
Providing an email address (as above in step 6) is optional. If you provide it, a user will be created in the Cognito User Pool that you can sign-in with.
You may want to see how your existing application works with the authentication framework before investing the effort to integrate or automate. One approach involves creating a full deploy from one of the deploy options above, then dropping your application into the bucket that's created. There are a few points to be aware of:
index.htmland ensure your SPA entry page is named
index.html. The renamed sample REACT's page will still work when specifically addressed in a URL.
myapp.htmlyour test URL will look like
You may find that your application does not render properly -- the default Content Security Policy (CSP) in the CloudFormation parameter may be the issue. As a quick test you can either remove the
"Content-Security-Policy":"..."parameter from the CloudFormation's HttpHeaders parameter, or substitute your own. Leave the other headers in the parameter alone unless you have a good reason.
Deploy the solution (e.g. from the Serverless Application Repository) while setting parameter
false. This way, only the [email protected] functions will de deployed in your account. You'll also get a User Pool and Client (unless you're bringing your own). Then you can wire the [email protected] functions up into your own CloudFront distribution. Create a behavior for all path patterns (root, RedirectPathSignIn, RedirectPathSignOut, RedirectPathAuthRefresh, SignOutUrl) and configure the corresponding [email protected] function in each behavior.
The CloudFormation Stack's Outputs contain the Lambda Version ARNs that you can refer to in your CloudFront distribution.
See this example on how to do it: ./example-serverless-app-reuse/reuse-auth-only.yaml
When following this route, also provide parameter
AlternateDomainNamesupon deploying, so the correct redirect URL's can be configured for you in the Cognito User Pool Client.
Go for the more barebone deployment, so you can do more yourself––i.e. reuse your bucket. Refer to scenario: I already have a CloudFront distribution, I just want to add auth.
Go for the more barebone deployment, so you can do more yourself––i.e. bring your own origins. Refer to scenario: I already have a CloudFront distribution, I just want to add auth.
You can use a pre-existing Cognito User Pool (e.g. from another region), by providing the User Pool's ARN as a parameter upon deploying. Make sure you have already configured the User Pool with a domain for the Cognito Hosted UI.
In this case, also specify a pre-existing User Pool Client ID. Note that the solution's callback URLs wil be added to the User Pool Client you provide.
You should use the UserPoolGroupName parameter, to specify a group that users must be a member of in order to access the site.
Without this UserPoolGroupName, the [email protected] functions will allow any confirmed user in the User Pool access to the site. When an identity provider is added to the User Pool, anybody that signs in though the identity provider is immediately a confirmed user. So with a social identity provider where anyone can create an account, this means anyone can access the site you are trying to protect.
With the UserPoolGroupName parameter defined, you will need to add each user to this group before they can access the site.
If the solution is creating the User Pool, it will create the User Pool Group too. If the solution is creating the User Pool and a default user (via the EmailAddress parameter), then this user will be added User Pool Group.
If you are using a pre-existing User Pool, you will need to make a group that has a name matching the UserPoolGroupName.
You can deploy this solution to any AWS region of your liking (that supports the services used). If you choose a region other than us-east-1, this solution will automaticaly create a second CloudFormation stack in us-east-1, for the [email protected] functions. This is because [email protected] must be deployed to us-east-1, this is a CloudFront requirement. Note though that this is a deployment concern only (which the solution handles automatically for you), [email protected] will run in all Points of Presence globally.
The default deployment mode of this sample application is "SPA mode" - which entails some settings that make the deployment suitable for hosting a SPA such as a React/Angular/Vue app:
If you do not want to deploy a SPA but rather a static site, then it is more secure to use a client secret and http-only cookies. Also, SPA routing is not needed then. To this end, upon deploying, set parameter
EnableSPAModeto false (
--parameter-overrides EnableSPAMode="false"). This will:
In case you're choosing Static Site mode, it might make sense to set parameter
--parameter-overrides RewritePathWithTrailingSlashToIndex="true"). This will append
index.htmlto all paths that include a trailing slash, so that e.g. when the user goes to
/some/sub/dir/, this is translated to
/some/sub/dir/index.htmlin the request to S3.
To deploy changes to the react-app or static-site after successful inital deployment, you'll need to upload your react-app or static-site changes directly to the S3 bucket (with a utility like s3-spa-upload). Making changes to the code only and re-deploying with SAM will not pick up those code changes to be deployed to the S3 bucket. See Issue # 96 for an alternative to force your code changes to deploy.
The cookies that this solution sets, are compatible with AWS Amplify––which makes this solution work seamlessly with AWS Amplify.
Niche use case: If you want to use this solution as an [email protected] layer in front of AWS Elasticsearch Service with Cognito integration, you need cookies to be compatible with the cookie-naming scheme of that service. In that case, upon deploying, set parameter CookieCompatibilty to "elasticsearch".
If choosing compatibility with AWS Elasticsearch with Cognito integration:
If you want to contribute, please read CONTRIBUTING, and note the hints below.
The sources that are not webpacked but rather run through
sam buildshould have their dependencies listed in their own package.json files––to make
sam buildwork properly.
For the sources that are webpacked this doesn't matter.
This sample code is made available under a modified MIT license. See the LICENSE file.