Repository files navigation

This project is aimed to be a generic authentication boilerplate for theServerless framework.

This boilerplate is compatible with the Serverless v.1.30.3+, to install Serverless framework runnpm 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 branchhttps://github.com/laardee/serverless-authentication-boilerplate/tree/serverless-0.5

The installation will create one DynamoDB table for OAuth state and refresh tokens.

1. Runserverless install --url https://github.com/laardee/serverless-authentication-boilerplate, clone or download the repository
2. Change directory toauthentication and renameexample.env.yml inauthentication toenv.yml and setenvironmental variables.
3. Runnpm install.
4. Runserverless deploy on the authentication folder to deploy authentication service to AWS.
5. (optional) Change directory to../test-token and runserverless deploy to deploy test-token service.

If you wish to change the cache db name, changeCACHE_DB_NAME in.env file andTableName inserverless.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 ishttps://API-ID.execute-api.us-east-1.amazonaws.com/dev/authentication/callback/facebook and for googlehttps://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 thecustom 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 savesstate to DynamoDB
• authentication/callback
  • endpoint: /authentication/callback/{provider}, redirects back to client webapp with token url parameter
  • handler: function is called by oauth provider withcode 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.

Openauthentication/env.yml, fill in what you use and other ones can be deleted.

dev:# GeneralSERVICE:${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: XXXXXXXXTOKEN_SECRET:token-secret-123# DatabaseFAUNADB_SECRET:SERVER_SECRET_FOR_YOUR_FAUNADB_DATABASECACHE_DB_NAME:${self:service}-cache-${opt:stage, self:provider.stage}USERS_DB_NAME:${self:service}-users-${opt:stage, self:provider.stage}# CognitoUSER_POOL_ID:user-pool-id# ProvidersPROVIDER_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"

• facebookserverless-authentication-facebook
• googleserverless-authentication-google
• windows liveserverless-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 tohttp://laardee.github.io/serverless-authentication-gh-pages and click 'custom-google' button.

To use FaunaDB to save user data. Firstcreate a database here, then:

1. configureFAUNADB_SECRET inauthentication/env.yml with a server secret for your database
2. uncommentreturn faunaUser.saveUser(profile); fromauthentication/lib/storage/usersStorage.js
3. change the last line ofauthentication/lib/storage/cacheStorage.js tomodule.exports = faunaCache;
4. RunSTAGE=dev npm run setup:fauna

To use DynamoBD to save user data:

1. uncommentUsersTable block fromauthentication/serverless.yml resources
2. uncommentreturn dynamoUser.saveUser(profile); fromauthentication/lib/storage/usersStorage.js

To use Cognito User Pool as user database:

1. create new user pool (http://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-cognito-user-identity-pools.html)
2. copy user pool id toauthentication/env.yml
3. uncommentreturn 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 theREDIRECT_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 CLIaws route53 list-hosted-zones --query 'HostedZones[*].[Name,Id]' --output text. The CLI will output something like thisauthentication.my-domain.com. /hostedzone/Z10QEETUEETUAO copy theZ10QEETUEETUAO part to theREDIRECT_HOSTED_ZONE_ID environment variable.

REDIRECT_HOSTED_ZONE_ID:"Z10QEETUEETUAO"

• Runnpm install in project root directory
• Runnpm test