Sign Users In to Cognito With AWS SDK v3 (InitiateAuth)

// cognito-auth.ts: sign users in to a Cognito user pool with InitiateAuth and RespondToAuthChallenge.
// Works for app clients with or without a client secret. InitiateAuth and RespondToAuthChallenge are
// unauthenticated API operations: the SDK sends them unsigned, so no AWS credentials are needed.
import { createHmac } from "node:crypto";
import {
  CognitoIdentityProviderClient,
  InitiateAuthCommand,
  RespondToAuthChallengeCommand,
  type AuthenticationResultType,
  type ChallengeNameType,
} from "@aws-sdk/client-cognito-identity-provider";

export interface CognitoConfig {
  region: string;
  clientId: string;
  clientSecret?: string; // only for confidential app clients; never ship it to a browser or mobile app
}

export type Challenge = { kind: "challenge"; name: ChallengeNameType; session: string; parameters: Record<string, string> };
export type AuthStep = { kind: "tokens"; tokens: AuthenticationResultType } | Challenge;

/** Base64(HMAC_SHA256(clientSecret, username + clientId)), as the Cognito developer guide specifies. */
export function secretHash(username: string, clientId: string, clientSecret: string): string {
  return createHmac("sha256", clientSecret).update(username + clientId).digest("base64");
}

export class CognitoAuth {
  private readonly client: CognitoIdentityProviderClient;
  private readonly config: CognitoConfig;

  constructor(config: CognitoConfig) {
    this.config = config;
    this.client = new CognitoIdentityProviderClient({ region: config.region });
  }

  private withHash(username: string, params: Record<string, string>): Record<string, string> {
    const { clientId, clientSecret } = this.config;
    return clientSecret ? { ...params, SECRET_HASH: secretHash(username, clientId, clientSecret) } : params;
  }

  private toStep(out: {
    AuthenticationResult?: AuthenticationResultType;
    ChallengeName?: ChallengeNameType;
    Session?: string;
    ChallengeParameters?: Record<string, string>;
  }): AuthStep {
    if (out.AuthenticationResult) return { kind: "tokens", tokens: out.AuthenticationResult };
    if (!out.ChallengeName || !out.Session) throw new Error("Cognito returned neither tokens nor a challenge");
    return { kind: "challenge", name: out.ChallengeName, session: out.Session, parameters: out.ChallengeParameters ?? {} };
  }

  /** USER_PASSWORD_AUTH sends the password to Cognito over TLS. The app client must allow ALLOW_USER_PASSWORD_AUTH. */
  async signIn(username: string, password: string): Promise<AuthStep> {
    const out = await this.client.send(new InitiateAuthCommand({
      AuthFlow: "USER_PASSWORD_AUTH",
      ClientId: this.config.clientId,
      AuthParameters: this.withHash(username, { USERNAME: username, PASSWORD: password }),
    }));
    return this.toStep(out);
  }

  /** Answers NEW_PASSWORD_REQUIRED, SOFTWARE_TOKEN_MFA, SMS_MFA, EMAIL_OTP and similar challenges. */
  async respond(step: Challenge, username: string, answers: Record<string, string>): Promise<AuthStep> {
    const out = await this.client.send(new RespondToAuthChallengeCommand({
      ClientId: this.config.clientId,
      ChallengeName: step.name,
      Session: step.session,
      ChallengeResponses: this.withHash(username, { USERNAME: username, ...answers }),
    }));
    return this.toStep(out);
  }

  /**
   * REFRESH_TOKEN_AUTH returns new ID and access tokens; the original refresh token stays valid.
   * With a client secret, hash with the username claim when username is a sign-in attribute,
   * otherwise with the user's sub claim (both are in the ID and access tokens).
   */
  async refresh(refreshToken: string, hashUsername?: string): Promise<AuthenticationResultType> {
    const params: Record<string, string> = { REFRESH_TOKEN: refreshToken };
    const out = await this.client.send(new InitiateAuthCommand({
      AuthFlow: "REFRESH_TOKEN_AUTH",
      ClientId: this.config.clientId,
      AuthParameters: hashUsername ? this.withHash(hashUsername, params) : params,
    }));
    if (!out.AuthenticationResult) throw new Error(`unexpected challenge ${out.ChallengeName ?? "(none)"}`);
    return out.AuthenticationResult;
  }
}

// sign-in-cli.ts: interactive sign-in that handles a temporary password and TOTP or SMS MFA.
// Usage: COGNITO_CLIENT_ID=... [COGNITO_CLIENT_SECRET=...] AWS_REGION=... npx tsx sign-in-cli.ts alice
import { createInterface } from "node:readline/promises";
import {
  NotAuthorizedException,
  PasswordResetRequiredException,
  UserNotConfirmedException,
  CodeMismatchException,
  InvalidPasswordException,
  TooManyRequestsException,
} from "@aws-sdk/client-cognito-identity-provider";
import { CognitoAuth, type AuthStep } from "./cognito-auth.js";

const username = process.argv[2];
if (!username) throw new Error("usage: sign-in-cli.ts <username>");
const auth = new CognitoAuth({
  region: process.env.AWS_REGION ?? "us-east-1",
  clientId: process.env.COGNITO_CLIENT_ID ?? "",
  clientSecret: process.env.COGNITO_CLIENT_SECRET,
});
const rl = createInterface({ input: process.stdin, output: process.stdout });

try {
  let step: AuthStep = await auth.signIn(username, await rl.question("Password: "));
  while (step.kind === "challenge") {
    console.log(`Challenge: ${step.name}`);
    if (step.name === "NEW_PASSWORD_REQUIRED") {
      step = await auth.respond(step, username, { NEW_PASSWORD: await rl.question("New password: ") });
    } else if (step.name === "SOFTWARE_TOKEN_MFA") {
      step = await auth.respond(step, username, { SOFTWARE_TOKEN_MFA_CODE: await rl.question("Authenticator code: ") });
    } else if (step.name === "SMS_MFA") {
      step = await auth.respond(step, username, { SMS_MFA_CODE: await rl.question("SMS code: ") });
    } else {
      throw new Error(`challenge ${step.name} isn't handled by this example`);
    }
  }
  const { IdToken, AccessToken, RefreshToken, ExpiresIn } = step.tokens;
  console.log(`Signed in. ID and access tokens expire in ${ExpiresIn} seconds.`);
  console.log(`ID token ${IdToken?.length ?? 0} chars, access token ${AccessToken?.length ?? 0} chars, refresh token ${RefreshToken ? "received" : "missing"}.`);
} catch (err) {
  if (err instanceof NotAuthorizedException) console.error("NotAuthorizedException: check the username, password and secret hash.");
  else if (err instanceof UserNotConfirmedException) console.error("UserNotConfirmedException: confirm the account first.");
  else if (err instanceof PasswordResetRequiredException) console.error("PasswordResetRequiredException: start ForgotPassword.");
  else if (err instanceof CodeMismatchException) console.error("CodeMismatchException: wrong code, sign in again.");
  else if (err instanceof InvalidPasswordException) console.error("InvalidPasswordException: the new password fails the pool's policy.");
  else if (err instanceof TooManyRequestsException) console.error("TooManyRequestsException: retry later with backoff.");
  else throw err;
  process.exitCode = 1;
} finally {
  rl.close();
}

npm install @aws-sdk/client-cognito-identity-provider
npm install --save-dev tsx typescript @types/node
COGNITO_CLIENT_ID=1example23456789 COGNITO_CLIENT_SECRET=... AWS_REGION=us-east-1 npx tsx sign-in-cli.ts alice

Password: Temp-Passw0rd!
Challenge: NEW_PASSWORD_REQUIRED
New password: N3w-Long-Passphrase!
Challenge: SOFTWARE_TOKEN_MFA
Authenticator code: 123456
Signed in. ID and access tokens expire in 3600 seconds.
ID token 1142 chars, access token 1071 chars, refresh token received.

// verify-token.ts: verify a Cognito access token in your API before trusting any claim in it.
import { CognitoJwtVerifier } from "aws-jwt-verify";
import { JwtExpiredError, JwtBaseError } from "aws-jwt-verify/error";

export const verifier = CognitoJwtVerifier.create({
  userPoolId: process.env.COGNITO_USER_POOL_ID ?? "us-east-1_EXAMPLE",
  tokenUse: "access", // use "id" to verify ID tokens
  clientId: process.env.COGNITO_CLIENT_ID ?? "1example23456789",
});

export async function authenticate(authorization: string | undefined): Promise<{ sub: string; username: string }> {
  const token = authorization?.replace(/^Bearer /, "");
  if (!token) throw new Error("missing bearer token");
  try {
    // Checks the signature against the pool's JWKS, then issuer, expiry, token_use and client_id.
    const payload = await verifier.verify(token);
    return { sub: payload.sub, username: String(payload.username) };
  } catch (err) {
    if (err instanceof JwtExpiredError) throw new Error("token expired: refresh it and retry");
    if (err instanceof JwtBaseError) throw new Error(`invalid token: ${err.message}`);
    throw err; // for example a network error while fetching the JWKS
  }
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ServerSideSignInOnly",
      "Effect": "Allow",
      "Action": [
        "cognito-idp:AdminInitiateAuth",
        "cognito-idp:AdminRespondToAuthChallenge"
      ],
      "Resource": "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_EXAMPLE"
    }
  ]
}