Nerdiest Political Manifesto


    2.0.2 • Public • Published

    Serverless Authentication

    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.


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

    1. Run serverless install --url, clone or download the repository
    2. Change directory to authentication and rename example.env.yml in authentication to env.yml and set environmental variables.
    3. Run npm install.
    4. Run serverless deploy on the authentication folder to deploy authentication service to AWS.
    5. (optional) Change directory to ../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.

    Set up Authentication Provider Application Settings

    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 and for 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.


    • 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 and state 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.


    • 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.

    Environmental Variables

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

    # General 
      SERVICE: ${self:service}
      STAGE: ${opt:stage, self:provider.stage}
      REGION: ${opt:region, self:provider.region}
    # Custom Redirect Domain 
    # REDIRECT_DOMAIN_NAME: ${opt:stage, self:provider.stage} 
    # 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} 
      TOKEN_SECRET: token-secret-123
    # 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"

    Example Provider Packages

    Custom Provider

    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 and click 'custom-google' button.

    User database

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

    1. configure FAUNADB_SECRET in authentication/env.yml with a server secret for your database
    2. uncomment return faunaUser.saveUser(profile); from authentication/lib/storage/usersStorage.js
    3. change the last line of authentication/lib/storage/cacheStorage.js to module.exports = faunaCache;
    4. Run STAGE=dev npm run setup:fauna

    To use DynamoBD to save user data:

    1. uncomment UsersTable block from authentication/serverless.yml resources
    2. uncomment return dynamoUser.saveUser(profile); from authentication/lib/storage/usersStorage.js

    To use Cognito User Pool as user database:

    1. create new user pool (
    2. copy user pool id to authentication/env.yml
    3. uncomment return saveCognito(profile); from authentication/lib/storage/usersStorage.js

    API Gateway Custom Domain Name

    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


    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 /hostedzone/Z10QEETUEETUAO copy the Z10QEETUEETUAO part to the REDIRECT_HOSTED_ZONE_ID environment variable.


    Running Tests

    • Run npm install in project root directory
    • Run npm test


    npm i ts-serverless-authentication-boilerplate

    DownloadsWeekly Downloads






    Unpacked Size

    128 kB

    Total Files


    Last publish


    • sansdeus