Private Static Site (Auth@Edge) Quickstart

Deploying the Private Static Site

The Runway built-in sample generation of a basic React app will be used as a simple demonstration of creating an authentication backed single page application.

Prerequisites

  • An AWS account, and configured terminal environment for interacting with it with an admin role.

  • The following installed tools:

    • npm

    • git (Available out of the box on macOS)

Setup

Project Setup

  1. Download/install Runway. Here we are showing the curl option. To see other available install methods, see Installation.

    macOS

    curl -L https://oni.ca/runway/latest/osx -o runway
    chmod +x runway
    

    Ubuntu

    curl -L https://oni.ca/runway/latest/linux -o runway
    chmod +x runway
    

    Windows

    iwr -Uri oni.ca/runway/latest/windows -OutFile runway.exe
    
  2. From a directory of your choosing run the following to generate a sample React project:

    pipenv run runway gen-sample static-react
    
  3. A new folder will be created entitled static-react. If you’d like your project to have a different name feel free to change it at this time:

    mv static-react my-static-site
    
  4. Change directories into the new project folder and prepare the project directory. See Repo Structure for more details.

    cd my-static-site
    git init
    git checkout -b ENV-dev
    

User Pool Setup

  1. The default runway.yml document that is provided with gen-sample static-react is a good baseline document for deploying a standard static single page application without the need of authentication. In this example we’ll be leveraging Auth@Edge to provide protection to our application, not allowing anyone to view or download site resources without first authenticating. To accomplish this we need to create a Cognito UserPool. Login to your AWS Console and search for cognito.

    ../_images/cognito-home.png
  2. Click Manage User Pools

    ../_images/cognito-manage-user-pools.png
  3. Click Create a user pool

    ../_images/cognito-create-user-pool.png
  4. You will be asked to provide a name for your User Pool. For our example we will be using a default Cognito User Pool, but you can Step through settings to customize your pool if you so choose. After entering your Pool name click the Review defaults button.

    ../_images/cognito-name-and-defaults.png
  5. Review all the settings are accurate prior to clicking Create pool.

    ../_images/cognito-defaults.png
  6. Next let’s create a test user to verify our authentication functionality after deployment. Click the Users and groups list link.

    ../_images/cognito-users-and-groups.png
  7. Click Create user

    ../_images/cognito-create-user.png
  8. In the form provided give a valid email address for the Username (Required) and Email entries. Ensure Send an invitation to this new user? is checked so you can receive the temporary password to access the site. Click the Create user button.

    ../_images/cognito-create-user-form.png
  9. Check the email address provided, you should receive a notification email from Cognito with the username and password that will need to be used for initial authentication.

    ../_images/cognito-temporary-password.png
  10. Now we need to retrieve the ARN for the User Pool we just created and add it to the deployments -> modules -> environments -> dev section of our runway.yml document. Click the General Settings list link to retrieve the ARN.

    ../_images/cognito-arn.png
    staticsite_user_pool_arn: YOUR_USER_POOL_ARN
    

Domain Aliases with ACM Certificate

  1. In this example we are going to be using an alias custom domain name to identify the CloudFront Distribution. This series of steps is optional, a domain will still be provided with the Distribution if you choose not to use a custom domain. This guide assumes that you have already purchased and registered a custom domain and created and validated an ACM certficate.

  2. The ARN of the ACM certificate is required when providing an alias domain name. From the search bar of the AWS console locate certificate manager. In this screen dropdown the details of your issued and validated certificate and locate the ARN.

    ../_images/acm-arn.png
  3. Create two entries in the runway.yml configuration file under the deployments -> modules -> environments -> dev heading. One for the alias we’re looking to provide, and the other for it’s ARN:

    staticsite_aliases: YOUR_CUSTOM_DOMAIN_NAMES_COMMA_SEPARATED
    staticsite_acmcert_arn: YOUR_ACM_ARN
    

Cleanup

  1. By default the gen-sample static-react sample runway.yaml document comes with staticsite_cf_disable: true added. Due to the nature of the authorization a Distribution is required. Remove this line from your config file.

Deploying

Execute pipenv run runway deploy, enter y. Deployment will take some time (mostly waiting for the CloudFront distribution to stabilize).

The CloudFront domain at which the site can be reached will be displayed near the last lines of output once deployment is complete, e.g.:

staticsite: sync & CF invalidation of E17B5JWPMTX5Z8 (domain ddy1q4je03d7u.cloudfront.net) complete

Since we’re using a custom domain alias the Distribution will also be accessible by that domain.

Accessing and Authorizing

Authorizing

  1. From your browser enter either the CloudFront Distribution domain or the alias you provided. You will be greeted with the Cognito login screen. Enter the username and temporary password you received in step 9 of User Pool Setup:

    ../_images/site-login.png
  2. You will be asked to change your password based on the validation requirements you specified when creating the User Pool. Once you have satisified the requirements click Send

    ../_images/site-change-password.png
  3. You will be greeted with the default React App home page:

    ../_images/site-home.png

Sign-Out

  1. By default a /sign-out path is provided to sign out of Cognito.

Teardown

Execute pipenv run runway destroy, enter y.