Generic authentication boilerplate for Serverless framework
This project is aimed to be a generic authentication boilerplate for the Serverless framework.
This boilerplate is compatible with the Serverless v.1.30.3+, to install Serverless framework run npm install -g serverless
.
Web app demo that uses this boilerplate: http://laardee.github.io/serverless-authentication-gh-pages
If you are using Serverless framework v.0.5, see branch https://github.com/laardee/serverless-authentication-boilerplate/tree/serverless-0.5
The installation will create one DynamoDB table for OAuth state and refresh tokens.
serverless install --url https://github.com/laardee/serverless-authentication-boilerplate
, clone or download the repositoryauthentication
and rename example.env.yml in authentication to env.yml and set environmental variables.npm install
.serverless deploy
on the authentication folder to deploy authentication service to AWS.../test-token
and run serverless deploy
to deploy test-token service.If you wish to change the cache db name, change CACHE_DB_NAME
in .env file and TableName
in serverless.yml in Dynamo resource.
The redirect URI that needs to be defined in OAuth provider's application settings is the callback endpoint of the API. For example, if you use facebook login, the redirect URI is https://API-ID.execute-api.us-east-1.amazonaws.com/dev/authentication/callback/facebook and for google https://API-ID.execute-api.us-east-1.amazonaws.com/dev/authentication/callback/google.
If you have a domain that you can use, the configuration is explained in the custom domain name section.
In this example project authentication and authorization services are separated from the content API (test-token).
Authentication service and authorization function for content API. These can also be separated if needed.
Functions:
state
to DynamoDBcode
and state
parameters and it creates authorization and refresh tokensSimulates content API.
Functions:
Open authentication/env.yml
, fill in what you use and other ones can be deleted.
dev:
# General
SERVICE: ${self:service}
STAGE: ${opt:stage, self:provider.stage}
REGION: ${opt:region, self:provider.region}
REDIRECT_CLIENT_URI: http://127.0.0.1:3000/
# Custom Redirect Domain
# REDIRECT_DOMAIN_NAME: ${opt:stage, self:provider.stage}.my-custom-domain-for-callback.com
# REDIRECT_CERTIFICATE_ARN: arn:aws:acm:us-east-1:111122223333:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3
# REDIRECT_URI: https://${self:provider.environment.REDIRECT_DOMAIN_NAME}/authentication/callback/{provider}
# REDIRECT_HOSTED_ZONE_ID: XXXXXXXX
TOKEN_SECRET: token-secret-123
# Database
FAUNADB_SECRET: SERVER_SECRET_FOR_YOUR_FAUNADB_DATABASE
CACHE_DB_NAME: ${self:service}-cache-${opt:stage, self:provider.stage}
USERS_DB_NAME: ${self:service}-users-${opt:stage, self:provider.stage}
# Cognito
USER_POOL_ID: user-pool-id
# Providers
PROVIDER_FACEBOOK_ID: "fb-mock-id"
PROVIDER_FACEBOOK_SECRET: "fb-mock-secret"
PROVIDER_GOOGLE_ID: "g-mock-id"
PROVIDER_GOOGLE_SECRET: "cg-mock-secret"
PROVIDER_MICROSOFT_ID: "ms-mock-id"
PROVIDER_MICROSOFT_SECRET: "ms-mock-secret"
PROVIDER_CUSTOM_GOOGLE_ID: "cg-mock-id"
PROVIDER_CUSTOM_GOOGLE_SECRET: "cg-mock-secret"
Package contains example /authentication/lib/custom-google.js how to implement a custom authentication provider using generic Provider class. To test custom provider go to http://laardee.github.io/serverless-authentication-gh-pages and click 'custom-google' button.
To use FaunaDB to save user data. First create a database here, then:
FAUNADB_SECRET
in authentication/env.yml
with a server secret for your databasereturn faunaUser.saveUser(profile);
from authentication/lib/storage/usersStorage.js
authentication/lib/storage/cacheStorage.js
to module.exports = faunaCache;
STAGE=dev npm run setup:fauna
To use DynamoBD to save user data:
UsersTable
block from authentication/serverless.yml
resourcesreturn dynamoUser.saveUser(profile);
from authentication/lib/storage/usersStorage.js
To use Cognito User Pool as user database:
authentication/env.yml
return saveCognito(profile);
from authentication/lib/storage/usersStorage.js
If you have a domain, a hosted zone, and a certificate for the domain defined in your AWS account, you may use API Gateway Custom Domain Name in your setup.
Your domain name goes to the REDIRECT_DOMAIN_NAME
environment variable, if this is set, CloudFormation will create a custom domain name to API Gateway and recordset to the Route 53
REDIRECT_DOMAIN_NAME: "authentication.my-domain.com"
Certificate ARN for your domain,
REDIRECT_CERTIFICATE_ARN: "arn:aws:acm:us-east-1:111122223333:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3"
Callback path, leave this like it is
REDIRECT_URI: "https://${self:provider.environment.REDIRECT_DOMAIN_NAME}/authentication/callback/{provider}"
Route 53 hosted zone id, go to Route 53 and get the id from there or with CLI aws route53 list-hosted-zones --query 'HostedZones[*].[Name,Id]' --output text
. The CLI will output something like this authentication.my-domain.com. /hostedzone/Z10QEETUEETUAO
copy the Z10QEETUEETUAO
part to the REDIRECT_HOSTED_ZONE_ID
environment variable.
REDIRECT_HOSTED_ZONE_ID: "Z10QEETUEETUAO"
npm install
in project root directorynpm test