LambdAuth is a sample authentication service implemented with a server-less architecture, using AWS Lambda to host and execute the code and Amazon DynamoDB as persistent storage. This provides a cost-efficient solution that is scalable and highly available.

The authentication can be used with Amazon Cognito to assume an Authenticated Role via Developer Authenticated Identities.

Passwords are not saved in clear in the database, but “salted” (via HMAC-SHA1) using a dedicated, random salt for each password.

The basic functions implemented are:

  • new user creation, an email is sent to validate the email address provided
  • login, getting back an authentication “token” that can be used with Amazon Cognito to assume an Authenticated Role via Developer Authenticated Identities
  • password change
  • password reset, an email is sent with a link to reset the password

The login function is calling in the backend GetOpenIdTokenForDeveloperIdentity, a Cognito API to register (or retrieve) the IdentityId and an OpenID Connect token for a user authenticated by your backend authentication process.

Amazon SES is used to send all emails.

A sample implementation can be found at http://lambdauth.danilop.net.

Installation

You can find LambdAuth in its GitHub repository.

Fork me on GitHub

A sample installation script using Bash (init.sh) is provided to install and configure all necessary resources in your AWS account:

The init.sh script requires a configured AWS Command Line Interface (CLI) and the jq tool. The script is designed to be non destructive, so you can run it again (e.g. if you delete a role) without affecting the other resources.

Before running the init.sh script, set up your configuration in the config.json file:

  • your AWS account (12-digit number)
  • the AWS region (e.g. “eu-west-1”)
  • the Amazon S3 bucket to use for the sample HTML pages
  • the Cache-Control: max-age value, in seconds, to use on Amazon S3 (e.g. if distributed by Amazon CloudFront or another CDN)
  • the Amazon DynamoDB table to create/use
  • the Amazon Cognito identity pool name to create/use (the identity pool id is automatically overwritten if present in the config.json file)
  • the Developer Provider Name to use with Amazon Cognito
  • the external name to be included in emails
  • the email source for emails (must be verified via Amazon SES)
  • the link to the verification page (usually http://bucket.s3.amazonaws.com/verify.html, but can be customized using a bucket name that is a DNS domain, Amazon CloudFront or another CDN)
  • the link to the password reset page (usually http://bucket.s3.amazonaws.com/reset.html, but can be customized using a bucket name that is a DNS domain, Amazon CloudFront or another CDN)
{
  "AWS_ACCOUNT_ID": "123412341234",
  "REGION": "eu-west-1",
  "BUCKET": "bucket",
  "MAX_AGE": "10",
  "DDB_TABLE": "LambdAuthUsers",
  "IDENTITY_POOL_NAME": "LambdAuth",
  "DEVELOPER_PROVIDER_NAME": "login.mycompany.myapp",
  "EXTERNAL_NAME": "My Authentication",
  "EMAIL_SOURCE": "email@example.com",
  "VERIFICATION_PAGE": "http://bucket.s3.amazonaws.com/verify.html",
  "RESET_PAGE": "http://bucket.s3.amazonaws.com/reset.html"
}

A sample deployment script using Bash (deploy.sh) is provided to update the AWS Lambda functions and the sample HTML pages on the Amazon S3 bucket.

Usage

Sample HTML pages are provided to showcase how to use this framework with a JavaScript application:

  • signup.html - to create a new user, the email address will be validated sending a custom link to the verify.html page
  • login.html - to login in, assuming an authenitcated role with Cognito
  • verify.html - to validate the email address of a new user
  • changePassword.html - to change password, knowing the old one
  • lostPAssword.html - to ask for a passwrod reser, via email
  • reset.html - to reset the password, linked by the email sent for a lost password

The same use cases can be implemented on a Mobile device using the AWS Mobile SDK.

API

The API are exposed as AWS Lambda Functions:

Function Input Output
LambdAuthCreateUser email, password created: true / false
LambdAuthVerifyUser email, verify verified: true / false
LambdAuthLogin email, password login: true / false, identityId, token
LambdAuthChangePassword email, oldPassword, newPassword changed: true / false
LambdAuthLostPassword email sent: true / false
LambdAuthResetPassword email, lost, password changed: true / false


Contribute

Please give me your feedback and fork the repository on GitHub.