Basic Serverless Applications- Front End

   

A Basic Serverless Application- The Front End

 

Serverless functions and databases operate up in the cloud within the walls of the web service provider. How do you know if they are working as expected or not? You can check things on various consoles, but the real end goal of this prototype is to have an application that a user can use to see how things work. For this, I have created the instructions and a simple set of web pages to allow you to verify that what you set up is working and give some example code on how to use JavaScript to process the information from services and databases. The API functions and database make up the back end software which is described in another article.

 

For purposes of this discussion, there are 3 components to this front end which are shown in the diagram of the overall application:

1. Serverless web server (Amplify).
2. Application web pages (they payload for this process, HTML and JavaScript).
3. User account management (Cognito).

In the above architecture, there are 3 custom-written pieces to this application. The other pieces are services or settings that are configured instead of being coded. The three places where unique application content exist are:

1. Application web pages (the front end).
2. Application database objects (persistent data storage on the back end).
3. Application serverless functions (the code that lets you access the database content).

Note- vendors may change their screens around over time as they update their products so you may have to adapt a little in terms screen labels and flows to get the job done (change is the only constant).
 

Serverless Web Service (Amplify, Step 5)

 
The basic means to get information to a web browser from the web is to make an http/https request to a web server that is designed to deliver HTML and JavaScript (in HTML5) to that web browser for processing and display. The serverless web server product at AWS is Amplify (there are a lot of product names to get used to with all vendors). This serverless tool eliminates the need to create a server running say Linux and then installing software (with something like Apache’s web server) on that server to listen for requests and deliver web content to the browsers. Instead of creating a server and installing products on it, you configure a serverless web service using the vendor’s management console or command line interface. For purposes of this prototype, I will go through the steps using the web-based management console.
 
The basic flow to make a request and get web pages from an Amplify web site is:

 

The AWS Amplify Management Console allows you to configure a web site (URL and options) and also upload the application web pages that people want to use. The steps to configure Amplify for this prototype are as follows:

1.    Download the prototype application from the following URL and store it in a folder on your workstation (it may seem like doing things out of order, but you must adapt to the flow of the service console, and it will not create an empty web site so give it this file):

https://jbgreene.the-greenes.com/uploads/protoweb.zip

2.    From the AWS Management Console, select the AWS Amplify product link.

3.    Click on the New App dropdown at the top of the page and select Host Web App option.

4.    Select the Deploy Without Git Provider tile and click the Continue button.

5.    Fill out the Application Name and Environment Name (whatever makes sense such as pApp and release).

6.    Select Method drag and drop.

7.    Choose zip file for the application (proto.zip) downloaded earlier.

8.    Select the Save & Deploy button.

9.    You should get a deployment completed successfully message along with the URL for the new  site (called Domain on this screen).

10.  Copy and paste this URL into your web browser to open your new web site and also into something like Notepad for future reference. Another note is that while you can download from various repositories, I chose to just download the application web pages to your workstation in zip file format which is what Amplify requires for uploads from a workstation.

 

If you have a domain that you own and want to configure an alias to this web site to use that domain (instead of amplifyapp.com), you can do that as follows:

1.    On the AWS Amplify Console, select the web application that you just created (i.e., pApp).

2.    On the menu on the left, select the Domain Management option.

3.    You will see the default URL link created by Amplify (with .amplifyapp.com extension).

4.    Click on the Add Domain button at the top right of the page.

5.    Enter a domain that you own/control in the Domain field (i.e., the-greenes.com) and click the Configure Domain button.

6.    Click the Exclude Root button.

7.    Where you see www in the text box put in a new name for this app (i.e., pApp) which will create an alias such as pApp.<your domain>.com for this web application’s web site).

8.    Click the Save button.

9.    You will then get a screen where it works on creating the new domain alias (takes minutes to perhaps half an hour usually).

10.  When this is done, when you select this app from the AWS Amplify Console, you will see the new domain name’s link for the application web site.

 

Prototype Application (Downloaded, Step 6)

 

This is the first part, of three, that make up the application that does what you need to have done. For this prototype, I have included a download (https://jbgreene.the-greenes.com/uploads/protoweb.zip) that can be used to test the functionality and show how to make the calls to the various pieces of the application. When uploaded to the Amplify web application site that you just created, you will get the web page shown below.

The prototype web application is a collection of web pages written in HTML and JavaScript that will test the various functions of this application and show some of the things that you can do with data downloaded from the API such as parsing the JSON data arrays into specific text variables. There is a big emphasis on settings. When you go serverless and use services provided by the vendor as opposed to writing the code yourself, you need to know how to connect to those services, which requires you to know what the services want (i.e., how they are configured). The landing page just shows the key settings for this prototype which will be empty for the most part now but that you will fill in as you work through setting up the services.

 

The menu at the top has 6 buttons that will test the key functions of this prototype plus a few convenience pages with some links and notes as follows.

1.    Settings- this shows you the current settings for the application (stored as session variables in your web session). It will let you know that the settings that you put in the configuration file are entered and let you know information about your login status.

2.    Login- this button makes a call to the Cognito login page once it is configured.

3.    Logout- this button makes a call to the Cognito logout function once it is configured.

4.    API Calls- this calls up a page with function buttons that will call the API (one button for before it is secured to require the Cognito login and one for after it is secured). Popup windows will show the result from a database query to prove it is working.

5.    AWS Links- these are just a few links to the AWS consoles to make it easier to access them.

6.    Notes- a few notes on the prototype that might help show examples of how to make the calls and how to process the results.

 

One thing that I prefer to do is store configuration information in a few central places as opposed to hard coding it in many different places. This prototype is controlled by a config.js file. Real applications may want to have the service configuration information such as database passwords on the server side, but this prototype seeks to ley you see what is going on versus implementing normal security features. Unzip the proto.zip file in a local directory on your workstation and open this file in Visual Studio or even just a text file. There will be several settings when working through this prototype where you will have to fill in values from the service between quotation marks as shown below in this file. You then must zip up this directory again and upload the modified zip file to the Amplify web site that you created.

User Authorization Service (Cognito, Steps 7a and 7b)

 

There are two types of web sites- those open to anyone and those where you want to control who can access it via some form of login. Public web pages work for advertising but if you have an application (as is the purpose of this prototype) you would typically want to control who can perform various functions. In the past, you had to write code yourself to add users, remove users, let users log in and log out. Since there are so many people who need this functionality, vendors have designed services help implement these security functions. For this prototype, we are using the Amazon Cognito service to handle the login and follow-on access security functions.

 

When using a service versus creating your own security application, the first challenge is to understand how the service “thinks” and how to configure it. For purposes of this prototype, the following are the key components. Of course, being a general purpose security product, there are a lot of other options that Cognito has on its menus to support other requirements.

-    User Pool- a collection of users, perhaps federated (i.e., LinkedIn).

-    Domain- tied to a user pool in a 1:1 relationship, is used to host the signup/login/challenge pages for the application.

-    App Client- an application connection to pool where OAuth2 grants are set up. Has a list of associated scopes for which it can allow requests. Scopes are declared by resource services in the user pool.

-    Resource Server- server for accessing protected resources. Handles authenticated requests from an application that has an access token (perhaps using API Gateway). The application treats access tokens as opaque when passing the token as part of the request. Resource server determines if access should be granted.

 

The basic flow, from a developer’s perspective, is that the user logs in to a Cognito user pool, receives an access token and then passes that access token to resources (such as the API Gateway) to show that they are entitled to access those resources. The access tokens are valid for 1 hour so they are only a temporary access credential as opposed to something that could be downloaded and used forever.

The basic flow of information for Cognito user authorization for this prototype application is: 

The first step is to create the container into which users are added. To create an Amazon Cognito User Pool for a REST API, do the following:

1.    From the AWS Management Console, select the Cognito to get the Cognito Management Console.

2.    Click on the Manage User Pools button.

3.    Click on the Create a User Pool button at the top of the screen.

4.    Enter a Pool Name (i.e., pPool) and click the Review Defaults button.

5.    For this prototype, accept the defaults and click on the Create Pool button.

6.    Note the Cognito User Pool Name setting for use configuring your application connection.

7.    Note: by default, users can sign up for accounts themselves, but you can change this by changing the User Sign Ups Allowed setting for the Cognito User Pool.

 

You could write your own sign up, sign in, and sign out web pages or you could just use the Cognito built in web pages to support that. To do this, you need to add an App Client to the Cognito User Pool to enable the hosted web user interface:

1.    From the AWS Management Console, select Cognito to get the Cognito Management Console.

2.    Select the Manage User Pools button and choose the User Pool that you just created.

3.    Under General Settings on the left menu, select the App Clients option.

4.    Enter an App Name (i.e., pClient) at the top of the page.

5.    Click on the Add an App Client link.

6.    Clear the Generate Client Secret checkbox (for mobile apps).

7.    Click on the Create App Client button.

8.    Note the app client ID on the settings sheet (a generated string of letters and characters).

9.    Select App Client Settings on the left menu.

10.   Select Cognito User Pool as an Enabled Identity Provider.

11.   Enter a callback URL for Cognito Authorization (for example https://<amplify URL>/process_login.html). This is the page Cognito returns to you after the login.

12.   Enter a sign out URL for Cognito (for example https://<amplify URL>/process_logout.html>). This is the page Cognito returns to you after the logout.

13.   Select the Implicit Grant check box under Allowed OAuth Flows.

14.   Select the aws.cognito.signin.user.admin check box under Allowed OAuth Scopes.

15.   Click the Save Change button.

16.   Click the Choose Domain link at the bottom of the screen.

17.   Enter an Amazon Cognito Domain (i.e., pdomain, must be lower case) and click the Check Availability button. The URL shown will be the URL called to access the Cognito Login/Logout/Signup functions.

18.    Note and save the domain and base URL on the settings sheet for future use.

19.   Click on the Save Changes button.

20.   Select App Client Settings on the left menu.

21.   Test by launching the user interface by clicking on the Launch Hosted UI button, note the URL on the settings sheet. This is just  a check that you have set up the Cognito pool and domain correctly, you will add a user and log in later in this process.

22.   Click on the Save Changes button.

 

The URL for the sign in web page to get an authorization grant code returned is:

https://<prototype Amplify URL>/login?response_type=token&client_id=<client_id>&redirect_url =<your_url>

 

This is basically and empty user pool. To test the setup using the console and create a user for testing:

1.    On the Cognito management console, select the user pool created for this prototype.

2.    Select App Client Settings on the left menu.

3.    Click on the Launch Hosted UI link near the bottom of the screen.

4.    Since this is your first time using this Cognito User Pool, click on the Sign Up button at the bottom.

5.    Fill in the Username, Email and Password fields and click on the Sign Up button.

6.    Cognito will send an email to the email address that you provided with a verification code that you can enter on the verification screen that pops up next then click the Confirm Account button.

7.    You are now logged into Cognito and will be take back to the prototype application page that you entered when creating the App Client in the callback URL field.

 

To test the basic user pool functionality with the prototype application, you must configure the Cognito information into the config.js file for the prototype web application. My rationale behind this was to show which of the many settings are needed to “wire” the services together. To update the settings to work with Cognito in this prototype:

1.    Unzip the protoweb.zip file downloaded earlier.

2.    Open the config.js file in Visual Studio or a text editor.

3.    Edit the file to insert the settings for Amplify and Cognito noted earlier in this article for your prototype (see Parameters/Settings to Remember table at the end of this article):

a.       amplifyUrl

b.       cognitoAppClientId

c.       cognitoBaseUrl

d.       cognitoDomainProfile

4.    Save your changes to config.js.

5.    Using the tools on your workstation, zip all of the files (not just config.js, be sure to include the uploads directory) into a new zip file (perhaps call it protoweb2.zip). I used the Windows File Explorer, highlighted the files, right clicked on Send To and then Compressed (Zipped) Folder option. The other zip utilities that I tried under windows did not handle sub-directories in a way that worked for Amplify.

6.    Go to the Amplify Management Console URL (which is on the AWS Links tab of the prototype application or it can be accessed from the AWS Management Console).

7.    Select the tile for this prototype application.

8.    Select the Choose Files button near the bottom of the page.

9.    Select the zip file that you just created and click the open button (titles for that button may vary based on your operating system and web browser combination).

10.    AWS should deploy the new web pages and give you the Deployment Successfully Completed message.

 

To test the setup for Cognito, do the following:

1.    Close any open browser windows to clear session settings.

2.    Open the URL for the application prototype that you created in Amplify.

3.    Check that the Amplify and Cognito settings are now showing on the Settings page

4.    Click on the Login button on the top menu. This will take you to the Cognito sign in page.

5.    Log in using the user ID and password that you created earlier.

6.    You will be taken back to the application prototype and can now see an Access Token under settings to show that you have logged in correctly.

7.    Next time you log in, you will be able to supply the Username and Password directly to log in without going through the setup again.

8.    Next click the Logout button on the menu at the top. You will be logged out of Cognito and will be taken back to the settings screen where you can see the Access Token field says "none".

 

For other AWS resources to verify that you are logged into a group that is has the appropriate access, you need to set up a Cognito Resource Server. To define a Resource Server (step 7b):

1.    From the AWS Management Console, select the Cognito link to get the Cognito Management Console.

2.    Click on the Manage User Pools tile.

3.    Choose the Resource Servers option on the menu on the left.

4.    Click on the Add a Resource Server button.

5.    Enter a name for the resource server (i.e., pServer).

6.    Enter an identifier (i.e., pId).

7.    Enter the names of the custom scope (i.e., pScope) and a description for the scope.

8.    Click the Save Changes button.

9.    Note the Resource Server Identifier and Custom Scope for later when configuring access to the API.

Parameters/Settings to Remember

prototype Amplify URL	<i.e., https://protoapp2.mydomain.com>
Cognito pool name	<i.e., protopool2>
Cognito client ID	<i.e., 3pcjgkrv8hs1aqelbj64hnntr4>
Cognito Domain URL	<i.e., https://protodomain2.auth.us-east-1.amazoncognito.com>