@bondsports/cognito

AWS Cognito Token Verifier

The AWS Cognito Token Verifier is a TypeScript package designed to facilitate the verification of Amazon Cognito user tokens. It provides a simple and efficient way to validate Cognito tokens in your applications.

Installation

npm install @bondsports/cognito

Usage

import { CognitoTokenVerifier } from '@bondsports/cognito';

// Initialize the CognitoTokenVerifier with your AWS region
const tokenVerifier = new CognitoTokenVerifier('your-aws-region');

// Use the `verifyToken` method to verify Cognito tokens
const result = await tokenVerifier.verifyToken((name) => /* Function to get token value from header by the header name */);

console.log('User Email:', result.email);

Features

• Token Verification: Verify Cognito tokens by providing the necessary headers.
• Logging: Integrated logging for debugging purposes.
• JWKs Caching: Efficiently caches JSON Web Keys (JWKs) to reduce the number of HTTP requests.

Example

try {
const result = await tokenVerifier.verifyToken((name) => /* Function to get token header by name */);
console.log('User Email:', result.email);
} catch (error) {
console.error('Token verification failed:', error.message);
}

Configuration

Required claims

The CognitoTokenVerifier allows you to pass a custom JWT token claims required to be present in the token while verifying:

import { CognitoTokenVerifier } from '@bondsports/cognito';

const requiredClaims = ['myCustomClaim', 'anotherClaimHasToBePresent'];
const tokenVerifier = new CognitoTokenVerifier('your-aws-region', requiredClaims);

there is also a static method returning default required claims, which you may use to extend the list:

import { CognitoTokenVerifier } from '@bondsports/cognito';

const defaultRequiredClaims = CognitoTokenVerifier.getDefaultRequiredClaims();
const requiredClaims = [...defaultRequiredClaims, 'myCustomClaim', 'anotherClaimHasToBePresent'];
const tokenVerifier = new CognitoTokenVerifier('your-aws-region', requiredClaims);

Logger

The CognitoTokenVerifier allows you to pass a custom logger during initialization:

import { CognitoTokenVerifier } from '@bondsports/cognito';
import jsLogger, { Logger } from '@bondsports/js-logger';

const customLogger: Logger = /* Your custom logger instance */;
const requiredClaims = CognitoTokenVerifier.getDefaultRequiredClaims();
const tokenVerifier = new CognitoTokenVerifier('your-aws-region', requiredClaims, customLogger);

Log Level

Default log level is INFO. however, you can change it:

import { CognitoTokenVerifier } from '@bondsports/cognito';
import jsLogger, { Logger, LogLevel } from '@bondsports/js-logger';

const customLogger: Logger = jsLogger();
const requiredClaims = CognitoTokenVerifier.getDefaultRequiredClaims();
const tokenVerifier = new CognitoTokenVerifier('your-aws-region', requiredClaims, customLogger, LogLevel.DEBUG);

Dependencies

This package relies on the following external dependencies:

• jose for JSON Web Token (JWT) processing.
• @bondsports/js-logger for logging functionality.