SpaceFinder is a reference mobile app that allows users to book conference rooms, work desks, and other shared resources. The app showcases serverless authentication and authorization using the AWS platform.
The mobile front-end is built using the Ionic2 framework and client libraries to call AWS services and mobile backend APIs. The backend APIs themselves are powered by AWS services. The backend APIs are built using a serverless architecture, which makes it easy to deploy updates, and it also means that there are no servers to operationally manage.
SpaceFinder is primarily developed and maintained by Jim Tran and Justin Pirtle, Solutions Architects at Amazon Web Services. The project code is released under the Apache 2.0 license. Please feel free to make use of the code in this project, and spread the word. We hope you enjoy it, and we certainly welcome all feedback, pull requests and other contributions!
SpaceFinder is built using the following AWS services:
- AWS Cognito - Amazon Cognito lets you easily add user sign-up and sign-in to your mobile and web apps. With Amazon Cognito, you also have the options to authenticate users through social identity providers such as Facebook, Twitter, or Amazon, with SAML identity solutions, or by using your own identity system.
- AWS Lambda - AWS Lambda lets you run code without provisioning or managing servers. You pay only for the compute time you consume - there is no charge when your code is not running. With Lambda, you can run code for virtually any type of application or backend service - all with zero administration.
- Amazon DynamoDB - Amazon DynamoDB is a fast and flexible NoSQL database service for all applications that need consistent, single-digit millisecond latency at any scale. It is a fully managed cloud database and supports both document and key-value store models.
- Amazon API Gateway - Amazon API Gateway is a fully managed service that makes it easy for developers to create, publish, maintain, monitor, and secure APIs at any scale. You can create an API that acts as a “front door” for applications to access data, business logic, or functionality from your back-end services, such as workloads running on Amazon Elastic Compute Cloud (Amazon EC2), code running on AWS Lambda, or any Web application. Amazon API Gateway handles all the tasks involved in accepting and processing up to hundreds of thousands of concurrent API calls, including traffic management, authorization and access control, monitoring, and API version management.
- AWS CloudFormation - AWS CloudFormation gives developers and systems administrators an easy way to create and manage a collection of related AWS resources, provisioning and updating them in an orderly and predictable fashion.
Spacefinder uses a Serverless API built using Amazon API Gateway, Lambda, DynamoDB, and CloudFormation. The API has the following REST methods, and some methods can only be called by users with "Admin" privileges.
If you only want to quickly run the mobile app to try out the app and see how it leverages different authorization patterns, you do not need to deploy the backend API to your account.
For full visibility into how everything works, you're able to setup the backend API in a fully automated way in your personal AWS account, which will then allow you to tweak settings and better understand the key interactions.
The framework relies on Node.js and npm.
# install the latest Gulp CLI tools globally (you will need a newer version of Gulp CLI which supports Gulp v4)
npm install gulpjs/gulp-cli -g
# Checkout the git repo
git clone https://github.com/awslabs/aws-serverless-auth-reference-app.git
# install the Node modules for the bootstrapping process
cd aws-serverless-auth-reference-app/api
npm install
# install the Node modules for the Lambda run-time
cd ./lambda
npm install
# Optional: Update the API config file if you'd like to use a specific non-default AWS profile or different region than us-east-1 to install to.
# vi aws-serverless-auth-reference-app/api/config.js
# Run the API automated bootstrapping process to deploy all AWS resources to your account
# gulp commands need to be run from 'api' directory
cd ..
gulp deploy
# Generate some sample data
gulp generate_sample_users
gulp generate_sample_data
The mobile app is a hybrid mobile app, and is built on the Ionic2 framework, which relies on Angular 2 and TypeScript 2.0. The hybrid mobile app can run on Android devices and iOS devices, as well as a modern web browser.
The application framework relies on Node.js and npm. It also uses Apache Cordova plugins to support certain native functionality on mobile devices.
# install latest version of the Ionic2 CLI, Cordova, and Bower tools
npm install -g ionic cordova bower
# install the Node modules
cd aws-serverless-auth-reference-app/app
npm install
# install the Bower crypto components (for AWS request signing)
bower install
# install Cordova platform components if you would like to build the app for mobile
cordova platform remove android
cordova platform remove ios
cordova platform add android@5.X.X
cordova platform add ios@4.X.X
As a hybrid mobile app, SpaceFinder can run in web browser, on Android devices, and on Apple iOS devices.
This useful for development purposes. If prompted for address/port to bind to, choose 'localhost'
ionic serve
You can run the app in an actual Android mobile device, or in an Android emulator. The following command generates an Android APK file, and run it in an Android emulator. Note that this requires previous installation of the Android SDK and existence of the ANDROID_HOME environmental variable.
ionic run android
Alternatively, to generate just the Android APK file, which can then be loaded onto an Android device:
ionic build android
Remote debug live content on an Android device from your Windows, Mac, or Linux computer,
using Chrome's remote debugger tool, and visiting chrome://inspect in your Chrome browser.
There are also third-party tools such as Vysor which can allow you to view your mobile device screen on your computer.
ionic run ios
As part of the bootstrapping process, sample users and location/resource data were created for you.
Use the following users to login to the application. You may additionally create your own personal accounts.
-
Standard user
- Username:
user1 - Password:
Test123! - Can browse resources, make bookings, and upload profile picture
- Username:
-
Admin user
- Username:
admin1 - Password:
Test123! - Can additionally create and delete locations and resources
- Username:
Enable the browser developer console (or remote debugging for Android) to view all of the log messages.
The log messages will show you all tokens retrieved as part of the sign-in process, as well as all API calls made and the corresponding authorization for each call.
When you're through testing and using the application, you may run the following command to delete any previously created backend resources that are hosted in your AWS account.
cd aws-serverless-auth-reference-app/api
gulp undeploy