Wild Rydes

Wild Rydes is a simple web application that allows users to request unicorn rides. The application presents a user interface for selecting a location on the map where they would like to be picked up. The interface is connected to an API that will invoke a unicorn to be dispatched to their location. Each user will also be required to register for an account.

Technologies used:

• AWS Lambda

• Amazon API Gateway

• Amazon S3

• Amazon DynamoDB

• AWS Amplify

• Amazon Cognito

• AWS Cloud9 IDE

• AWS IAM

The entirety of this lab will need to be deployed in a single region. Ensure that all services are using the same region.

Cloud9 will be used for this lab. It is an IDE provided by AWS. Any other IDE can also be used.

Navigate to Cloud9 and create an environment. Name the environment and select New EC2 instance.

Select t3.small. The other settings can be kept as default.

Create the environment and let it provision.

Once the Cloud9 environment is deployed, open up the IDE.

Static Web Hosting

AWS Amplify will be used to host the static resources for the application. Users will visit the site using a public URL exposed by the Amplify console.

Repository

AWS CodeCommit will be used to host the site's repository.

Create a new CodeCommit repository.

aws codecommit create-repository \
  --repository-name wild-rydes

Clone the repository from GitHub.

git clone https://github.com/aws-samples/aws-serverless-webapp-workshop.git

Navigate to the aws-serverless-webapp-workshop directory.

cd aws-serverless-webapp-workshop

Install git-subtree and then split the WildRydesVue code into its branch.

sudo yum install git-subtree -y

git subtree split -P resources/code/WildRydesVue -b WildRydesVue

Create a new directory for the CodeCommit repository.

mkdir ../wild-rydes && cd ../wild-rydes

Initialize a new git repository.

git init

Pull the WildRydesVue branch into the new repository.

git pull ../aws-serverless-webapp-workshop WildRydesVue

Add the CodeCommit repository as a remote.

git remote add origin codecommit://wild-rydes

Push the code to the new CodeCommit repository.

git push -u origin master

Remove the local repository that was created earlier.

rm -rf ../aws-serverless-webapp-workshop

Deploy

AWS Amplify Console will be used to deploy the site that was committed to git.

To confirm that the repository was created in CodeCommit, you can navigate to CodeCommit in the AWS console.

Navigate to AWS Amplify within the console and select Amplify Hosting Host your web app.

Select AWS CodeCommit.

Select the dropdown and the repository should show up.

Select Create New Environment and name it “prod”.

Next, a role needs to be created. IAM > Roles > Create Role. Select AWS service and Amplify as the use case.

Ensure AdministratorAccess-Amplify is attached.

Name the role amplifyconsole-backend-role.

After creating, select attach policies.

Attach the AWSCodeCommitReadOnly policy.

Return to the AWS Amplify Console. Under wild-rydes, the new role should be available to assign.

Select Save and Deploy.

The process can take a few minutes.

Once complete, visit the URL to launch the Wild Rydes site.

Modify

AWS Amplify has the ability to rebuild and redeploy the web application when changes are detected in the repository. This Modify section shows how changes to the title affect the site.

In the Cloud9 IDE, navigate to wild rydes > public > index.html.

Change the on line 8 and save the file.

Commit the git repository.

git add .

git commit -m "updated title"

git push

Revisit the site and you can see that the title changed.

User Management

Amplify CLI

The site will require users to authenticate to the application. If the user does not have an account, they will need to register (email/password). For this lab, Amazon Cognito will be the IAM solution.

After registration, users will be sent a confirmation email containing a verification code. They will then need to return to the application, log in, and enter the code. Once the account is confirmed, a JavaScript function reaches out to Cognito, authenticates using Secure Remote Password (SRP), and sends back a JSON Web Token (JWT). The token will contain information about the user's identity and be used to authenticate against the API in a later section.

Install the Amplify CLI.

npm install -g @aws-amplify/cli

Configure the default AWS profile.

echo '[profile default]' > ~/.aws/config

Ensure you are in the root directory for wild-rydes and initialize the CLI.

amplify init

The Amplify CLI will be used to create a user pool within Cognito.

amplify add auth

Add the Cognito user pool

> Do you want to use the default authentication and security configuration? "Default configuration"

> How do you want users to be able to sign in? "Username"

> Do you want to configure advanced settings? "No, I am done."

Commit the changes to the git repository. Once the application is successfully deployed, a user pool will be created in Cognito.

git add .

git commit -m "Configure Cognito"

git push

Amplify will pick up the changes and begin building and deploying.

Navigate to the Amazon Cognito Console. Under User Pools, you should see the new user pool created.

Rather than configuring each service through a constructor or constants file, Amplify supports configuration through a centralized file called aws-exports.js which defines all the regions and service endpoints to communicate. Whenever you run amplify push or rebuild your web application by running git commit, this file is automatically created, allowing you to focus on your application code. The Amplify CLI places this file in the appropriate source directory configured with amplify init.

You won’t see updates to this file in your local file store because it is included in the .gitignorefile.

Create a New User for the User Pool

Visit the /auth directory of the Wild Rydes website domain. You could also choose the Giddy Up! Button on the homepage.

Click on Create Account and complete registration. You can choose a real email or a fake email. I chose a real email for this lab to test the email delivery capabilities. Ensure that the password meets the minimum requirements (one uppercase letter, a number, and a special character).

If you use a real email, you will receive a code. If you use a fake email, you must confirm the user through the Cognito console.

Verification code sent to my email.

After confirmation, sign back into the application console.

After successfully logging in, you will be redirected to /ride. There should be a notification that the API has not been configured and an authentication token.

Just for fun, let’s decode the auth token. Find a JWT decoder and paste the token. We can see that this token contains my user information (username, phone number, email), authentication time, expiration date, etc.

Serverless Backend

The next step is configuring the serverless backend using DynamoDB. AWS Lambda will be used to build a backend process for handling requests from the web app. Each time a user requests a unicorn, the Lambda function will be invoked. The Lambda function will select a unicorn, record the request in the DynamoDB table, and provide a response to the front-end application about the unicorn that was dispatched.

DynamoDB

Navigate to the DynamoDB console.

Create a table and name it Rides.

The Partition Key will be RideId and a String value.

Ensure Table settings is set to Default settings.

Create the table. Once created and active, click on the table to open the settings.

Under Overview > General Information > Additional Info, find the Amazon Resource Name (ARN) and record this value.

IAM

Next, an IAM role will need to be created for the Lambda function.

Navigate to the IAM Console > Roles > Create Role

Select AWS Service and Lambda under Use Case.

After clicking Next, add AWSLambdaBasicExecutionRole policy.

Name the role WildRydesLambda and create the role.

Back in the IAM console, navigate to the role that was just created. Under Permission policies, select Add permissions > Create inline policy.

Click the drop down under Select a service and type in DynamoDB.

Ensure the details are correct and paste in the ARN that was copied earlier from the DymanoDB table. Click Add ARN.

Name the policy DynamoDBWriteAccess and create the policy.

Lambda

This next step involves creating the Lambda function to process API requests.

1. Navigate to the AWS Lambda console.

2. Select Create function

3. Author from scratch

4. Name the function RequestUnicorn

5. Select Node.js 20.x for Runtime

6. Under Change default execution role, select the drop down to expand the section

7. Select WildRydesLambda under the Existing role drop down

8. Create the function

Scroll down to the Code source section and replace the code in index.js with requestUnicorn.js. Deploy the code afterward by clicking the “Deploy” button.

Navigate to the Test tab and configure a test event.

Create new event.

Name the event TestRequestEvent.

Copy and paste this JSON Event into the editor.

{
    "path": "/ride",
    "httpMethod": "POST",
    "headers": {
        "Accept": "*/*",
        "Authorization": "eyJraWQiOiJLTzRVMWZs",
        "content-type": "application/json; charset=UTF-8"
    },
    "queryStringParameters": null,
    "pathParameters": null,
    "requestContext": {
        "authorizer": {
            "claims": {
                "cognito:username": "the_username"
            }
        }
    },
    "body": "{\"PickupLocation\":{\"Latitude\":47.6174755835663,\"Longitude\":-122.28837066650185}}"
}

Save and Test.

Under the Details section, verify that the execution was successful.

RESTful API

REST API

API Gateway will be configured to expose the Lambda function as a RESTful API. Although the API will be exposed, it will be secured using the Cognito user pool.

Navigate to the API Gateway console.

Scroll down and select REST API.

1. Select New API

2. Name the API WildRydes

3. Under API endpoint type, select Regional

4. Create the API

You should see the API successfully created in the console.

Cognito

1. In the API Gateway Console, create a new Cognito user pool authorizer for the API.

2. Under the API, choose Authorizers and Create New Authorizer

3. Name the Authorizer WildRydes

4. Select Cognito for Authorizer type

5. Under Cognito user pool, select the Region where the Cognito user pool was created and the name of the Cognito user pool

6. The token source is Authorization

7. Create authorizer

Verify the authorizer configuration

1. Open a new browser tab and visit the /ride endpoint under the application domain.

2. Copy the authentication token from the notification window.

3. Return to the Authorizer page in AWS

4. Paste the authentication token into the Token Value under Test Authorizer

Click the Test button and ensure that you receive a 200 response code.

API Resource

Return to the API Gateway console and select Resources under the new API.

1. Under Actions, select Create Resource

2. Enter ride as the Resource Name

3. Enable CORS

4. Create Resource

1. Within the console, the new /ride resource should have populated.

1. Select Create Method

2. Method Type is POST

3. Select Lambda function

4. Enable Lambda Proxy Integration

5. Select the correct region where the Lambda function is located

6. Enter the name of the Lambda function

7. Create Method

Edit the method request.

Under Authorization, select WildRydes

Deploy

1. Under the Actions drop-down list, select Deploy API

2. Choose New Stage under Stage

3. The Stage Name is prod

4. Deploy the API

Take note of the Invoke URL

Update Configuration

Return to the Cloud9 IDE. Under /src/config.js, update the invoke URL to the one that was copied in the previous step. Save the changes.

Commit the changes to the git repository.

git add src/config.js 
   
git commit -m "Configure API invokeURL"
   
git push

Under the Amplify console, you will see the app begin to deploy with the new changes under the Amplify console, you will see the app begin to deploy with the new changes.

Navigate to the /ride endpoint for the web application.

Sign in if requested to.

The map should now load without the notification window.

Select a location on the map to set a pickup location.

Choose Request Unicorn and you will see a message in the upper right corner that says a unicorn is on its way. A unicorn icon will then fly to the selected location.