Amazon Cognito: Authentication and User Management

You just shipped a new feature. Two hours later, your CTO is in your DMs: 'Why are our users getting 401s?' You check the logs — your custom JWT library expired tokens an hour early. This is the reality of rolling your own auth. Amazon Cognito exists because authentication is harder than it looks. It's not just about passwords; it's about token rotation, MFA, social logins, and scaling to millions without burning down your database. Cognito handles all of that, but it's not a magic bullet. Misconfigure it, and you'll leak data or lock users out. In this article, I'll show you how to set it up for production: user pools, identity pools, and the gotchas that will bite you. No fluff, just patterns that work.

Why Cognito? The Case for Managed Auth

Building authentication from scratch is a trap. You'll spend weeks on password hashing, session management, MFA, and social login integrations — and still get it wrong. Amazon Cognito gives you a managed user directory that scales to millions, handles OAuth 2.0, SAML, and OIDC out of the box, and integrates with API Gateway, ALB, and AppSync. It's not perfect (we'll cover the sharp edges), but for most teams, it's the right starting point. Cognito splits into two services: User Pools for identity and sign-in, and Identity Pools for AWS credentials. You almost always need both.

aws cognito-idp create-user-pool \
  --pool-name my-app-users \
  --policies 'PasswordPolicy:{MinimumLength:8,RequireUppercase:true,RequireLowercase:true,RequireNumbers:true,RequireSymbols:true}' \
  --auto-verified-attributes email \
  --schema '[{"Name":"email","Required":true,"Mutable":true},{"Name":"custom:role","AttributeDataType":"String","Mutable":true}]' \
  --region us-east-1

User Pool Configuration: Schema, Policies, and App Clients

Your User Pool schema defines which attributes you store. Standard attributes (email, phone) are fine, but custom attributes (prefixed with custom:) let you store app-specific data like custom:role or custom:tenant_id. Password policies should enforce at least 8 characters with complexity — but don't go overboard; users will hate you. App Clients are the bridge between your app and the pool. Each client gets a client ID and optional secret. For public clients (mobile/web), never embed the secret — use PKCE flow instead. Enable ALLOW_USER_PASSWORD_AUTH only for server-side flows. Always set a callback URL and sign-out URL; otherwise, the hosted UI will reject redirects.

aws cognito-idp create-user-pool-client \
  --user-pool-id us-east-1_xxxxxxxxx \
  --client-name my-web-app \
  --generate-secret \
  --explicit-auth-flows ALLOW_USER_PASSWORD_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --callback-urls '["https://app.example.com/callback"]' \
  --logout-urls '["https://app.example.com/logout"]' \
  --supported-identity-providers COGNITO \
  --region us-east-1

Sign-Up and Sign-In Flows: Hosted UI vs Custom UI

Cognito offers a hosted UI that handles sign-up, sign-in, MFA, and password reset out of the box. It's ugly but functional — great for MVPs. For production, you'll likely build a custom UI using the Amplify SDK or raw Cognito API calls. The hosted UI supports social logins (Google, Facebook, Apple) via OIDC federation. Custom UI gives you full control over UX but requires handling token storage, refresh, and logout manually. The sign-up flow can auto-verify email/phone via a confirmation code. For custom UI, use SignUp API, then ConfirmSignUp. For sign-in, use InitiateAuth with USER_PASSWORD_AUTH flow, which returns access, ID, and refresh tokens.

const AWS = require('aws-sdk');
const cognito = new AWS.CognitoIdentityServiceProvider({ region: 'us-east-1' });

const params = {
  ClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
  Username: 'user@example.com',
  Password: 'Str0ng!Pass',
  UserAttributes: [
    { Name: 'email', Value: 'user@example.com' },
    { Name: 'custom:role', Value: 'admin' }
  ]
};

cognito.signUp(params, (err, data) => {
  if (err) console.error(err);
  else console.log('User signed up:', data.UserSub);
});

Token Management: Access, ID, and Refresh Tokens

Cognito issues three tokens on successful authentication: Access token (authorization), ID token (user info), and Refresh token (long-lived). Access tokens are JWTs with claims like cognito:groups and custom:attributes. ID tokens contain user profile data. Both expire in 1 hour by default. Refresh tokens last 30 days (configurable). Never store tokens in localStorage — use httpOnly cookies or secure storage. On each API call, validate the access token's signature and expiry. Use the refresh token to get new tokens silently. Cognito's InitiateAuth with REFRESH_TOKEN_AUTH flow handles this. Implement token refresh in an interceptor to avoid 401s.

const AWS = require('aws-sdk');
const cognito = new AWS.CognitoIdentityServiceProvider({ region: 'us-east-1' });

const params = {
  AuthFlow: 'REFRESH_TOKEN_AUTH',
  ClientId: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
  AuthParameters: {
    REFRESH_TOKEN: 'your-refresh-token-here'
  }
};

cognito.initiateAuth(params, (err, data) => {
  if (err) console.error('Refresh failed:', err);
  else {
    console.log('New access token:', data.AuthenticationResult.AccessToken);
    console.log('New ID token:', data.AuthenticationResult.IdToken);
  }
});

MFA and Advanced Security: Protecting Accounts

Cognito supports SMS and TOTP (time-based one-time password) MFA. Enable MFA per user or enforce it via a pool policy. SMS is convenient but expensive and unreliable in some regions. TOTP is free and more secure. For advanced protection, enable Cognito's Advanced Security Features (ASF) — it uses machine learning to detect suspicious sign-ins (new device, location anomaly) and can block or require MFA. ASF requires a client-side SDK to send risk context (IP, user agent). It's an extra cost but worth it for high-value apps. Configure MFA settings in the User Pool: optional, required, or adaptive (with ASF).

aws cognito-idp set-user-pool-mfa-config \
  --user-pool-id us-east-1_xxxxxxxxx \
  --mfa-configuration ON \
  --software-token-mfa-configuration Enabled=true \
  --sms-mfa-configuration SmsAuthenticationMessage='Your verification code is {####}' SmsConfiguration={SnsCallerArn=arn:aws:iam::123456789012:role/CognitoSNSRole,ExternalId=my-external-id} \
  --region us-east-1

Federated Identities: Social Login and SAML

Cognito supports federation with social identity providers (Google, Facebook, Apple, Amazon) and enterprise SAML/OIDC providers (Azure AD, Okta). For social login, configure the provider in the User Pool console with your app's client ID and secret. Users can sign in with their social account, and Cognito maps their attributes (email, name) to your user pool. For SAML, you need a metadata XML from the IdP. Federation reduces password fatigue and improves conversion. However, you lose control over account recovery — if the social provider goes down, users can't log in. Always provide a fallback (email+password) or multiple federation options.

aws cognito-idp create-identity-provider \
  --user-pool-id us-east-1_xxxxxxxxx \
  --provider-name Google \
  --provider-type Google \
  --attribute-mapping '{"email":"email","name":"name"}' \
  --provider-details '{"client_id":"1234567890-xxxxx.apps.googleusercontent.com","client_secret":"GOCSPX-xxxxx","authorize_scopes":"openid email profile"}' \
  --region us-east-1

Identity Pools: Exchanging Tokens for AWS Credentials

Identity Pools (formerly Federated Identities) let you exchange a Cognito token (or any OIDC token) for temporary AWS credentials. This is how your app gets access to S3, DynamoDB, or API Gateway. You define IAM roles for authenticated and unauthenticated users. The Identity Pool uses the token's claims (like cognito:groups) to select the right role. For example, an admin group gets a role with write access to S3, while regular users get read-only. The credentials are temporary (default 1 hour) and automatically refreshed by the SDK. Always scope down permissions — never use a wildcard * in the role policy.

const AWS = require('aws-sdk');
const cognitoIdentity = new AWS.CognitoIdentity({ region: 'us-east-1' });

const params = {
  IdentityPoolId: 'us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
  Logins: {
    'cognito-idp.us-east-1.amazonaws.com/us-east-1_xxxxxxxxx': 'your-id-token'
  }
};

cognitoIdentity.getId(params, (err, data) => {
  if (err) console.error(err);
  else {
    const identityId = data.IdentityId;
    cognitoIdentity.getCredentialsForIdentity({
      IdentityId: identityId,
      Logins: params.Logins
    }, (err, creds) => {
      if (err) console.error(err);
      else {
        console.log('Access Key:', creds.Credentials.AccessKeyId);
        console.log('Secret Key:', creds.Credentials.SecretKey);
        console.log('Session Token:', creds.Credentials.SessionToken);
      }
    });
  }
});

Lambda Triggers: Customizing the Auth Flow

Cognito Lambda triggers let you inject custom logic at various points: pre sign-up (validate or reject), post confirmation (send welcome email), pre authentication (block suspicious users), post authentication (audit log), and more. For example, a pre sign-up trigger can check if the email domain is allowed. A post authentication trigger can record the login event to DynamoDB. Triggers receive an event object and must return it (possibly modified). They can throw errors to abort the flow. Be careful with trigger latency — Cognito has a 5-second timeout. Use async processing (SQS, SNS) for heavy work.

exports.handler = async (event) => {
  const allowedDomains = ['example.com', 'mycompany.org'];
  const email = event.request.userAttributes.email;
  const domain = email.split('@')[1];

  if (!allowedDomains.includes(domain)) {
    throw new Error('Email domain not allowed');
  }

  // Optionally auto-confirm user
  event.response.autoConfirmUser = true;
  event.response.autoVerifyEmail = true;

  return event;
};

Monitoring and Auditing: CloudWatch, CloudTrail, and Alarms

Cognito emits metrics to CloudWatch: SignInSuccesses, SignUpSuccesses, TokenRefreshSuccesses, and their failure counterparts. Set up dashboards and alarms for spikes in failures — they could indicate attacks or misconfiguration. CloudTrail records all Cognito API calls (CreateUserPool, AdminCreateUser, etc.) for auditing. For user-level events (login, sign-up), enable detailed logging via CloudWatch Logs with a Lambda trigger. Also monitor Lambda trigger errors. Set up a composite alarm: if SignInFailures > 100 in 5 minutes, alert the team. Use AWS Config to track changes to User Pool policies.

aws cloudwatch put-metric-alarm \
  --alarm-name cognito-signin-failures \
  --alarm-description 'Alarm when sign-in failures exceed 100 in 5 minutes' \
  --metric-name SignInFailures \
  --namespace AWS/Cognito \
  --statistic Sum \
  --period 300 \
  --evaluation-periods 1 \
  --threshold 100 \
  --comparison-operator GreaterThanThreshold \
  --dimensions Name=UserPool,Value=us-east-1_xxxxxxxxx \
  --alarm-actions arn:aws:sns:us-east-1:123456789012:my-alert-topic \
  --region us-east-1

Common Pitfalls and Production Hardening

Cognito has sharp edges. First, the hosted UI domain is shared across all pools in a region — if another team's pool is compromised, your redirect URIs could be abused. Use a custom domain (via CloudFront) to isolate. Second, User Pool export/import is not supported — you must build your own migration script. Third, the default token expiry (1 hour) is fine, but refresh tokens expire after 30 days — users will be forced to re-login. Extend it to 365 days if acceptable. Fourth, Cognito does not support account recovery by email if the user forgets their password — you must implement a custom forgot-password flow. Fifth, Lambda triggers can be cold-started, adding latency to auth. Pre-warm them with a scheduled invocation.

aws cognito-idp create-user-pool-domain \
  --domain auth.myapp.com \
  --user-pool-id us-east-1_xxxxxxxxx \
  --custom-domain-config CertificateArn=arn:aws:acm:us-east-1:123456789012:certificate/xxxx-xxxx-xxxx-xxxx-xxxx \
  --region us-east-1