cognito-express

    3.0.1 • Public • Published

    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.

    Architecture

    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.

    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();
    	}
    });

    Also supports async/await pattern

    (async function main() {
      try {
        const response = await cognitoExpress.validate(accessTokenFromClient);
        console.log(response);
         //User is authenticated, proceed with rest of your business logic.
    
      } catch (e) {
        console.error(e);
         //User is not authenticated, do something with the error.
         //Perhaps redirect user back to the login page
      }
    })();

    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

    Install

    npm i cognito-express

    DownloadsWeekly Downloads

    22,726

    Version

    3.0.1

    License

    MIT

    Unpacked Size

    13.4 kB

    Total Files

    5

    Last publish

    Collaborators

    • ghdna