This project is aimed to be a generic authentication boilerplate for the Serverless framework.
This boilerplate is compatible with the Serverless v.1.0.0, to install Serverless framework run npm install -g serverless
.
Webapp 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
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 - Rename example.env in authentication to .env and set environmental variables.
- Change directory to
authentication
and runnpm install
. - Run
serverless deploy
on the authentication folder to deploy authentication service to AWS. Notice the arn of the authorize function. - (optional) Change directory to test-token and insert the arn of the authorizer function to authorizer/arn in serverless.yml. Then 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.
In this example project authentication and authorization services are separated from 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 end point
- 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 username in request template.
Open authentication/.env, fill in what you use and other ones can be deleted.
STAGE = dev
REDIRECT_CLIENT_URI = http://url-to-frontend-webapp/
TOKEN_SECRET = secret-for-json-web-token
PROVIDER_FACEBOOK_ID = facebook-app-id
PROVIDER_FACEBOOK_SECRET = facebook-app-secret
PROVIDER_GOOGLE_ID = google-app-id
PROVIDER_GOOGLE_SECRET = google-app-secret
PROVIDER_MICROSOFT_ID = microsoft-app-id
PROVIDER_MICROSOFT_SECRET = microsoft-app-secret
PROVIDER_CUSTOM_GOOGLE_ID = google-app-id
PROVIDER_CUSTOM_GOOGLE_SECRET = google-app-secret
COGNITO_IDENTITY_POOL_ID = cognito-pool-id
COGNITO_REGION = eu-west-1
COGNITO_PROVIDER_NAME = your-service-name
- 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 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.
- Install Docker
- Run ./specs-docker.sh