cognito-passport-oauth2

1.3.1 verified Sat Apr 25 auth: no javascript

A Passport strategy for authenticating against AWS Cognito User Pools using OAuth 2.0. Version 1.3.1 provides a subclass of passport-oauth2 that supports Cognito-specific auth parameters such as identity_provider and custom scopes. Released as ES5 with CommonJS module format, it integrates seamlessly with Express and Passport. Designed for Node.js server-side authentication flows where Cognito is the identity provider. Includes TypeScript definitions. Not actively maintained, with no recent updates.

Common errors

error CognitoOAuth2Strategy is not a constructor ↓

cause Using CommonJS require without destructuring, e.g., const CognitoOAuth2Strategy = require('cognito-passport-oauth2'); returns the module object, not the class directly.

fix

Use const { CognitoOAuth2Strategy } = require('cognito-passport-oauth2'); to destructure the named export.

error Error: Unsupported grant type: authorization_code ↓

cause Missing or incorrect client_id or client_secret; or using wrong clientDomain.

fix

Verify that clientID, clientSecret, and clientDomain are correct and that the app client has authorization_code grant enabled.

error TypeError: Cannot destructure property 'id_token' of 'undefined' or 'null'. ↓

cause Using the 5-argument verify signature but the strategy expects a 4-argument signature (older version) or the token object is not provided.

fix

Ensure you are using version >=1.2 and the verify function signature matches: verify(req, accessToken, refreshToken, { id_token }, profile, done) if you need id_token.

Warnings

gotcha clientDomain must be the full Cognito domain including https:// ↓

fix Set clientDomain to 'https://yourdomain.auth.region.amazoncognito.com' (with https:// prefix).

gotcha The verify function signature changed: if you need id_token, use 5-argument signature (req, accessToken, refreshToken, { id_token }, profile, done). ↓

fix Use the correct signature: verify(req, accessToken, refreshToken, tokenObj, profile, done) where tokenObj.id_token contains the ID token.

gotcha The strategy does not validate the id_token by default; you must implement verification if required. ↓

fix Optionally use an additional library to verify the JWT id_token from Cognito.

breaking Dropped support for Node.js < 10 in version 1.3.0 ↓

fix Upgrade Node.js to version 10 or later.

deprecated The 'passReqToCallback' option is no longer needed if using the 5-argument verify function. ↓

fix Remove passReqToCallback from options; the request is always passed as first argument when using the 5-argument form.

Install

npm install cognito-passport-oauth2

yarn add cognito-passport-oauth2

pnpm add cognito-passport-oauth2

Imports

CognitoOAuth2Strategy

wrong

const CognitoOAuth2Strategy = require('cognito-passport-oauth2');

correct

import { CognitoOAuth2Strategy } from 'cognito-passport-oauth2'

ESM import available; avoid mixing require() in ESM files. The default export is the strategy class.

CognitoOAuth2Strategy

wrong

const CognitoOAuth2Strategy = require('cognito-passport-oauth2').default

correct

const { CognitoOAuth2Strategy } = require('cognito-passport-oauth2')

CommonJS destructured import is correct. The library exports the class directly, not as a default export.

Strategy

wrong

import Strategy from 'cognito-passport-oauth2'

correct

import { CognitoOAuth2Strategy as Strategy } from 'cognito-passport-oauth2'

No default export; use named import with alias to mimic common pattern.

Quickstart

Shows Express app setup with Passport, Cognito OAuth2 strategy, session handling, and route configuration.

import express from 'express';
import passport from 'passport';
import { CognitoOAuth2Strategy } from 'cognito-passport-oauth2';
import session from 'express-session';

const app = express();
app.use(session({ secret: 'your-secret', resave: false, saveUninitialized: true }));
app.use(passport.initialize());
app.use(passport.session());

passport.serializeUser((user, done) => done(null, user));
passport.deserializeUser((user, done) => done(null, user));

const options = {
  callbackURL: 'http://localhost:4001/auth/callback',
  clientDomain: 'https://yourdomain.auth.eu-west-1.amazoncognito.com',
  clientID: process.env.COGNITO_CLIENT_ID ?? '',
  clientSecret: process.env.COGNITO_CLIENT_SECRET ?? '',
  region: 'eu-west-1',
  passReqToCallback: true
};

async function verify(req, accessToken, refreshToken, profile, done) {
  // Custom user logic here
  return done(null, { username: profile.username });
}

passport.use('cognito', new CognitoOAuth2Strategy(options, verify));

app.get('/auth/login', passport.authenticate('cognito'));
app.get('/auth/callback', passport.authenticate('cognito', { failureRedirect: '/login', successRedirect: '/' }));

app.listen(3000);