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.
- Run
serverless install --url https://github.com/laardee/serverless-authentication-boilerplate
, clone or download the repository - Change directory to
authentication
and rename example.env.yml in authentication to env.yml and set environmental variables. - Run
npm install
. - Run
serverless deploy
on the authentication folder to deploy authentication service to AWS. - (optional) Change directory to
../test-token
and runserverless 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:
- authentication/signin
- endpoint: /authentication/signin/{provider}, redirects to oauth provider login page
- handler: signin function creates redirect url to oauth provider and saves
state
to DynamoDB
- authentication/callback
- endpoint: /authentication/callback/{provider}, redirects back to client webapp with token url parameter
- handler: function is called by oauth provider with
code
andstate
parameters and it creates authorization and refresh tokens
- authentication/refresh
- endpoint: /authentication/refresh/{refresh_token}, returns new authentication token and refresh token
- handler: function revokes refresh token
- authentication/authorize
- endpoint: no endpoint
- handler: is used by Api Gateway custom authorizer
Simulates content API.
Functions:
- test-token/test-token
- endpoint: /test-token
- handler: test-token function can be used to test custom authorizer, it returns principalId of custom authorizer policy. It is mapped as the username in request template.
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"
- facebook serverless-authentication-facebook
- google serverless-authentication-google
- windows live serverless-authentication-microsoft
- more to come
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:
- configure
FAUNADB_SECRET
inauthentication/env.yml
with a server secret for your database - uncomment
return faunaUser.saveUser(profile);
fromauthentication/lib/storage/usersStorage.js
- change the last line of
authentication/lib/storage/cacheStorage.js
tomodule.exports = faunaCache;
- Run
STAGE=dev npm run setup:fauna
To use DynamoBD to save user data:
- uncomment
UsersTable
block fromauthentication/serverless.yml
resources - uncomment
return dynamoUser.saveUser(profile);
fromauthentication/lib/storage/usersStorage.js
To use Cognito User Pool as user database:
- create new user pool (http://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-cognito-user-identity-pools.html)
- copy user pool id to
authentication/env.yml
- uncomment
return saveCognito(profile);
fromauthentication/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"
- Run
npm install
in project root directory - Run
npm test