Git Product home page Git Product logo

cognito-express2's Introduction

Cognito-Express: API Authentication with AWS Congito

NPM

Build Status Package Quality Code Climate Coverage Status dependencies Status Downloads

Synopsis

cognito-express authenticates API requests on a Node.js application (either running on a server or in an AWS Lambda function) by verifying the JWT signature of AccessToken or IDToken generated by Amazon Cognito.

Motivation

Architecture

This module lets you authenticate Node.js API requests by verifying the JWT signature of AccessToken or IDToken - without needing to call Amazon Cognito for each API invocation.

The module can be easily and unobtrusively integrated into any application or framework that supports Connect-style middleware, including Express.

This module essentially bundles steps 1-7 listed on the official AWS documentation on Using ID Tokens and Access Tokens in your Web APIs

  1. Download and store the JSON Web Token (JWT) set for your user pool.
  2. Decode the token string into JWT format.
  3. Check the iss claim. It should match your user pool.
  4. Check the tokenUse claim. It should match your set preference for access or id token types
  5. Get the kid from the JWT token header and retrieve the corresponding JSON Web Key that was stored in step 1.
  6. Verify the signature of the decoded JWT token.
  7. Check the exp claim and make sure the token is not expired.

You can now trust the claims inside the token and use it as it fits your requirements.

Prerequisites

After successful authentication of a user, Amazon Cognito issues three tokens to the client:

  • ID token
  • Access token
  • Refresh token

(Note: The login mechanism is not covered by this module and you'll have to build that separately)

Save these tokens within the client app (preferably as cookies). When any API is invoked from client, pass in the AccessToken or IDToken to the server.

It's completely up to you how you pass in the AccessToken or IDToken. Here are two options:

  1. By adding them explicitly in Request Headers
  2. Just save the tokens as cookies. This way they get attached to request headers whenever APIs are invoked. (recommended)

Configuration

//Initializing CognitoExpress constructor
const cognitoExpress = new CognitoExpress({
	region: "us-east-1",
	cognitoUserPoolId: "us-east-1_dXlFef73t",
	tokenUse: "access", //Possible Values: access | id
	tokenExpiration: 3600000 //Up to default expiration of 1 hour (3600000 ms)
});

Usage

cognitoExpress.validate(accessTokenFromClient, function(err, response) {
	if (err) {
		/*
			//API is not authenticated, do something with the error.
		    //Perhaps redirect user back to the login page
			
			//ERROR TYPES:
			
			//If accessTokenFromClient is null or undefined
			err = {
			    "name": "TokenNotFound",
			    "message": "access token not found"
			}
			
			//If tokenuse doesn't match accessTokenFromClient
			{
			    "name": "InvalidTokenUse",
			    "message": "Not an id token"
			}

			//If token expired
			err = {
			    "name": "TokenExpiredError",
			    "message": "jwt expired",
			    "expiredAt": "2017-07-05T16:41:59.000Z"
			}

			//If token's user pool doesn't match the one defined in constructor
			{
			    "name": "InvalidUserPool",
			    "message": "access token is not from the defined user pool"
			}

		*/
	} else {
		//Else API has been authenticated. Proceed.
		res.locals.user = response; //Optional - if you want to capture user information
		next();
	}
});

Full Example

app.js - server
//app.js
"use strict";

const express = require("express"),
	CognitoExpress = require("cognito-express"),
	port = process.env.PORT || 8000;

const app = express(),
	authenticatedRoute = express.Router(); //I prefer creating a separate Router for authenticated requests

app.use("/api", authenticatedRoute);

//Initializing CognitoExpress constructor
const cognitoExpress = new CognitoExpress({
	region: "us-east-1",
	cognitoUserPoolId: "us-east-1_dXlFef73t",
	tokenUse: "access", //Possible Values: access | id
	tokenExpiration: 3600000 //Up to default expiration of 1 hour (3600000 ms)
});

//Our middleware that authenticates all APIs under our 'authenticatedRoute' Router
authenticatedRoute.use(function(req, res, next) {
	
	//I'm passing in the access token in header under key accessToken
	let accessTokenFromClient = req.headers.accesstoken;

	//Fail if token not present in header. 
	if (!accessTokenFromClient) return res.status(401).send("Access Token missing from header");

	cognitoExpress.validate(accessTokenFromClient, function(err, response) {
		
		//If API is not authenticated, Return 401 with error message. 
		if (err) return res.status(401).send(err);
		
		//Else API has been authenticated. Proceed.
		res.locals.user = response;
		next();
	});
});


//Define your routes that need authentication check
authenticatedRoute.get("/myfirstapi", function(req, res, next) {
	res.send(`Hi ${res.locals.user.username}, your API call is authenticated!`);
});

app.listen(port, function() {
	console.log(`Live on port: ${port}!`);
});
client.js - angular example
//client.js - angular example

"use strict";

//I stored my access token value returned from Cognito in a cookie called ClientAccessToken

app.controller("MyFirstAPI", function($scope, $http, $cookies) {
	$http({
		method: "GET",
		url: "/api/myfirstapi",
		headers: {
			accesstoken: $cookies.get("ClientAccessToken") 
            }
		}
	}).then(
		function success(response) {
			//Authenticated. Do something with the response. 
		},
		function error(err) {
			console.error(err);
		}
	);
});

Contributors

Gary Arora

License

MIT

cognito-express2's People

Contributors

ghdna avatar j-5-s avatar ncb000gt avatar panuhorsmalahti avatar rivertam avatar

Watchers

 avatar  avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.