{"id":19648855,"url":"https://github.com/laardee/serverless-authentication-boilerplate","last_synced_at":"2025-04-13T04:59:45.184Z","repository":{"id":56436245,"uuid":"54150474","full_name":"laardee/serverless-authentication-boilerplate","owner":"laardee","description":"Generic authentication boilerplate for Serverless framework","archived":false,"fork":false,"pushed_at":"2020-11-08T00:17:01.000Z","size":333,"stargazers_count":567,"open_issues_count":29,"forks_count":71,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-04-13T04:59:11.370Z","etag":null,"topics":["boilerplate","oauth-provider","oauth2","serverless","serverless-framework"],"latest_commit_sha":null,"homepage":"http://laardee.github.io/serverless-authentication-gh-pages","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laardee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-03-17T20:49:36.000Z","updated_at":"2025-02-17T06:46:10.000Z","dependencies_parsed_at":"2022-08-15T18:40:40.474Z","dependency_job_id":null,"html_url":"https://github.com/laardee/serverless-authentication-boilerplate","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laardee%2Fserverless-authentication-boilerplate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laardee%2Fserverless-authentication-boilerplate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laardee%2Fserverless-authentication-boilerplate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laardee%2Fserverless-authentication-boilerplate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laardee","download_url":"https://codeload.github.com/laardee/serverless-authentication-boilerplate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248665756,"owners_count":21142123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["boilerplate","oauth-provider","oauth2","serverless","serverless-framework"],"created_at":"2024-11-11T14:50:17.700Z","updated_at":"2025-04-13T04:59:45.153Z","avatar_url":"https://github.com/laardee.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Serverless Authentication\n\n[![serverless](http://public.serverless.com/badges/v3.svg)](http://www.serverless.com)\n\n[![Build Status](https://travis-ci.org/laardee/serverless-authentication-boilerplate.svg?branch=master)](https://travis-ci.org/laardee/serverless-authentication-boilerplate)\n\nThis project is aimed to be a generic authentication boilerplate for the [Serverless framework](http://www.serverless.com).\n\nThis boilerplate is compatible with the Serverless v.1.30.3+, to install Serverless framework run `npm install -g serverless`.\n\nWeb app demo that uses this boilerplate: http://laardee.github.io/serverless-authentication-gh-pages\n\nIf you are using Serverless framework v.0.5, see branch https://github.com/laardee/serverless-authentication-boilerplate/tree/serverless-0.5\n\n## Installation\n\nThe installation will create one DynamoDB table for OAuth state and refresh tokens.\n\n1. Run `serverless install --url https://github.com/laardee/serverless-authentication-boilerplate`, clone or download the repository\n2. Change directory to `authentication` and rename _example.env.yml_ in _authentication_ to _env.yml_ and set [environmental variables](#env-vars).\n3. Run `npm install`.\n4. Run `serverless deploy` on the authentication folder to deploy authentication service to AWS.\n5. (optional) Change directory to `../test-token` and run `serverless deploy` to deploy test-token service.\n\nIf you wish to change the cache db name, change `CACHE_DB_NAME ` in _.env_ file and `TableName` in _serverless.yml_ in Dynamo resource.\n\n## Set up Authentication Provider Application Settings\n\nThe 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**.\n\nIf you have a domain that you can use, the configuration is explained in the [custom domain name](#custom-domain) section.\n\n## Services\n\nIn this example project authentication and authorization services are separated from the content API (test-token).\n\n### Authentication\n\nAuthentication service and authorization function for content API. These can also be separated if needed.\n\nFunctions:\n\n* authentication/signin\n  * endpoint: /authentication/signin/{provider}, redirects to oauth provider login page\n  * handler: signin function creates redirect url to oauth provider and saves `state` to DynamoDB\n* authentication/callback\n  * endpoint: /authentication/callback/{provider}, redirects back to client webapp with token url parameter\n  * handler: function is called by oauth provider with `code` and `state` parameters and it creates authorization and refresh tokens\n* authentication/refresh\n  * endpoint: /authentication/refresh/{refresh_token}, returns new authentication token and refresh token\n  * handler: function revokes refresh token\n* authentication/authorize\n  * endpoint: no endpoint\n  * handler: is used by Api Gateway custom authorizer\n\n### Test-token\n\nSimulates content API.\n\nFunctions:\n\n* test-token/test-token\n  * endpoint: /test-token\n  * 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.\n\n## \u003ca id=\"env-vars\"\u003e\u003c/a\u003eEnvironmental Variables\n\nOpen `authentication/env.yml`, fill in what you use and other ones can be deleted.\n\n```yaml\ndev:\n# General\n  SERVICE: ${self:service}\n  STAGE: ${opt:stage, self:provider.stage}\n  REGION: ${opt:region, self:provider.region}\n  REDIRECT_CLIENT_URI: http://127.0.0.1:3000/\n# Custom Redirect Domain\n# REDIRECT_DOMAIN_NAME: ${opt:stage, self:provider.stage}.my-custom-domain-for-callback.com\n# REDIRECT_CERTIFICATE_ARN: arn:aws:acm:us-east-1:111122223333:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3\n# REDIRECT_URI: https://${self:provider.environment.REDIRECT_DOMAIN_NAME}/authentication/callback/{provider}\n# REDIRECT_HOSTED_ZONE_ID: XXXXXXXX\n  TOKEN_SECRET: token-secret-123\n# Database\n  FAUNADB_SECRET: SERVER_SECRET_FOR_YOUR_FAUNADB_DATABASE\n  CACHE_DB_NAME: ${self:service}-cache-${opt:stage, self:provider.stage}\n  USERS_DB_NAME: ${self:service}-users-${opt:stage, self:provider.stage}\n# Cognito\n  USER_POOL_ID: user-pool-id\n# Providers\n  PROVIDER_FACEBOOK_ID: \"fb-mock-id\"\n  PROVIDER_FACEBOOK_SECRET: \"fb-mock-secret\"\n  PROVIDER_GOOGLE_ID: \"g-mock-id\"\n  PROVIDER_GOOGLE_SECRET: \"cg-mock-secret\"\n  PROVIDER_MICROSOFT_ID: \"ms-mock-id\"\n  PROVIDER_MICROSOFT_SECRET: \"ms-mock-secret\"\n  PROVIDER_CUSTOM_GOOGLE_ID: \"cg-mock-id\"\n  PROVIDER_CUSTOM_GOOGLE_SECRET: \"cg-mock-secret\"\n```\n\n## Example Provider Packages\n\n* facebook [serverless-authentication-facebook](https://www.npmjs.com/package/serverless-authentication-facebook)\n* google [serverless-authentication-google](https://www.npmjs.com/package/serverless-authentication-google)\n* windows live [serverless-authentication-microsoft](https://www.npmjs.com/package/serverless-authentication-microsoft)\n* more to come\n\n## \u003ca id=\"custom-provider\"\u003e\u003c/a\u003eCustom Provider\n\nPackage contains example [/authentication/lib/custom-google.js](https://github.com/laardee/serverless-authentication-boilerplate/blob/master/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.\n\n## User database\n\nTo use FaunaDB to save user data. First [create a database here](https://fauna.com/serverless-cloud-sign-up), then:\n\n1. configure `FAUNADB_SECRET` in `authentication/env.yml` with a server secret for your database\n2. uncomment `return faunaUser.saveUser(profile);` from `authentication/lib/storage/usersStorage.js`\n3. change the last line of  `authentication/lib/storage/cacheStorage.js` to `module.exports = faunaCache;`\n4. Run `STAGE=dev npm run setup:fauna`\n\nTo use DynamoBD to save user data:\n\n1. uncomment `UsersTable` block from `authentication/serverless.yml` resources\n2. uncomment `return dynamoUser.saveUser(profile);` from `authentication/lib/storage/usersStorage.js`\n\nTo use Cognito User Pool as user database:\n\n1. create new user pool (http://docs.aws.amazon.com/cognito/latest/developerguide/setting-up-cognito-user-identity-pools.html)\n2. copy user pool id to `authentication/env.yml`\n3. uncomment `return saveCognito(profile);` from `authentication/lib/storage/usersStorage.js`\n\n## \u003ca id=\"custom-domain\"\u003e\u003c/a\u003eAPI Gateway Custom Domain Name\n\nIf 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.\n\nYour 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\n```yaml\nREDIRECT_DOMAIN_NAME: \"authentication.my-domain.com\"\n```\n\nCertificate ARN for your domain,\n```yaml\nREDIRECT_CERTIFICATE_ARN: \"arn:aws:acm:us-east-1:111122223333:certificate/fb1b9770-a305-495d-aefb-27e5e101ff3\"\n```\n\nCallback path, leave this like it is\n```yaml\nREDIRECT_URI: \"https://${self:provider.environment.REDIRECT_DOMAIN_NAME}/authentication/callback/{provider}\"\n```\n\nRoute 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.\n\n```yaml\nREDIRECT_HOSTED_ZONE_ID: \"Z10QEETUEETUAO\"\n````\n\n## Running Tests\n\n* Run `npm install` in project root directory\n* Run `npm test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaardee%2Fserverless-authentication-boilerplate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaardee%2Fserverless-authentication-boilerplate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaardee%2Fserverless-authentication-boilerplate/lists"}