How to start

This guide is a step-by-step tutorial on how to deploy a noback boilerplate project into your AWS account.

This solution will offer you login functionality through Cognito and Google SSO (we’ll need a Google OAuth 2.0 client).

Note

The authorized redirect URI for the OAuth client id will be unknown until we deploy noback (it will be available inside Cognito App Client).

1 - Create a Google SSO client

1. Go to the API section on Google Cloud

   https://console.cloud.google.com/apis/

2. Create a new project or reuse a existing one

3. Configure OAuth consent screen

   • Configure OAuth consent screen
   • Use type: external
   • Fill the rest of the parameters with you own data
   • Add the following scopes
     • openid
     • ./auth/userinfo.email
     • ./auth/userinfo.profile
   • We don’t need test users to run the demo
   • For testing we don’t need to publish it (it’s going to be limited to 100 users)

4. Go to API & Services ➡️ Credentials ➡️ Create credentials ➡️ OAuth Client ID

   • type: web application
   • 🚨 Add the authorized redirect URI that will be found on AWS Cognito once deployed.

Note

At this point we are already able to get the client ID and client secret. Save those values on a secured place.

2 - Create an AWS account

1. You can create an account from scratch here

   https://aws.amazon.com/free/

2. You will be asked to fill some forms about personal information, and a credit card (while noback for development is unexpensive, please beware if activating additional services or expecting high demand)

Note

If you are familiar with AWS, it’s recommended to create accounts from AWS Organization within a master account

3 - Prepare noback env variables

#if switching between account_id's, remove hidden .aws-sam folder to avoid conflicts
ACCOUNT_ID={aws_account_id} # this is to avoid deploying into the wrong account
ENVIRONMENT=dev
REGION={region}
PROJECT_NAME=simpleback
ENABLE_WAF=false
WHITELISTED_IPS=
ALLOWED_COUNTRIES=
GOOGLE_CLIENT_ID={your_client_id_from_google}
GOOGLE_CLIENT_SECRET={your_client_secret_from_google}
COGNITO_CALLBACK=http://localhost:3004/welcome/ # your development URL
ENABLE_XRAY=true
AUTH_CACHE_TIME=3600
SESSION_EXPIRATION_TIME=28800
DISABLE_USER_CONFIRMATION=false
EMAIL_IDENTITY={your_domain_from_where_we_can_send_mails_from}

Note

To deploy to production, create config_PRD.env file, but you can create as many environments as needed as far as deploy.sh is adapted accordingly

4 - Time to deploy! 🚀

N0back provide a script to deploy to AWS (for more advanced deploying options, check CI/CD section).

Export your access key (from AWS) to your console, and execute:

./deploy.sh

This is the quicker and simpler way to deploy. It uses the variables from the config_DEV.env or config_PRD.env. It will build a new file samconfig.toml file using the template-samconfig structure and the env variables, and will automatically deploy it to the AWS account configured on your terminal (you will be prompt to confirm changes).

You can review the process on real time using CloudFormation, and it will take around 10 minutes to be fully deployed.

Caution

AWS CLI tools and AWS SAM CLI extension should be ready on your terminal before starting this process:

• Install AWS CLI
• Install AWS SAM CLI extension

Make sure you have the latest SAM CLI version on your system. It will require version 1.107.0 or newer (it may work with 1.103.x)

Review your AWS account

The following resources should be created/updated.

• API Gateway
• Lambda authorizers
• Lambda functions and layers
• Amazon DynamoDB
• Amazon Cognito
• Cloudwatch & X-Ray
• Amazon S3
• EventBridge, Queues and Event
• IAM roles
• Web Application Firewall (disabled by default. It will increase daily costs)

All these resources are defined in the template.yaml file in this project. You can update the template to add AWS resources through the same deployment process that updates your application code (more info on how to extend functionality here 🔴 https://github.com/aknibit/noback/blob/main/docs/extend-functionality.md).

All non-critical resources required for essential behaviour, like X-Ray, could be disabled to avoid extra costs. Here you can see how much it will cost you with essential and full set of features.

5 - Connect from UI

To test the backend, there is a frontend as a proposal on how to interact with it. Clone the following repo and run it locally in order to be able to interact with noback https://github.com/aknibit/simpleback-ui

First, update authorized redirect URI on the credentials section of the APIs & Services within your Google Cloud account. It will be your cognito domain + /oauth2/idpresponse . Should be something like:

https://noback-simpleback-dev-{YOUR_ACCOUNT_ID}-pool.auth.us-east-1.amazoncognito.com/oauth2/idpresponse

Within Google Cloud, we can check that the authorized domains within the OAuth consent screen was updated automatically once the credential section was updated (if not, paste the cognito domain manually)

To be able to interact with the backend from your UI, you’ll need to copy the .env.local.TEMPLATE file into .env.local and replace the following values:

• backend url (api gateway’s invoke URL)
• cognito clientId
• cognito domain
• cognito redirect uri (because of the oauth double handshake, while google needs a redirect uri back to cognito, cognito will need a valid redirect uri back to the UI. If runing on local port 3004, the default value was already propagated to cognito while deploying)

You will find all details about how to run simpleback-ui on its readme, but it’s mainly 2 steps:

npm i # (tested with node 18.x)
npm run devios # and go to http://localhost:3004/

While it will be developing over time, It’s intended to be as simple as possible, and right now is able to:

• Authenticate a user using a Google account, and establish the session.
• If it’s a new user, the UI will ask about username, and will persist user info on DynamoDB.
• Endpoint to ask for user information.
• SQS & SNS to communicate events between the same user on different devices.
• Close session and invalidate tokens.

On top of this, there are helper functions to publish on Eventbridge, allowing us to do anything else afterwards (🔴 check **extend functionality)

Protected endpoints are using cognito and some extra layers of security that will not allow anyone except you to use your token. (check security)