15 — Cognito & Auth

What is Cognito?

Managed authentication and authorization for web/mobile apps.

User → Sign in → Cognito User Pool → JWT (id_token, access_token, refresh_token)
                                         ↓
                                   API Gateway (validates JWT)
                                         ↓
                                      Lambda / Backend

---

User Pools

# Create user pool
aws cognito-idp create-user-pool \
  --pool-name my-app-users \
  --auto-verified-attributes email \
  --mfa-configuration OPTIONAL \
  --policies "PasswordPolicy={MinimumLength=8,RequireUppercase=true,RequireLowercase=true,RequireNumbers=true,RequireSymbols=false}"

# Create app client
aws cognito-idp create-user-pool-client \
  --user-pool-id us-east-1_xxxxx \
  --client-name web-app \
  --explicit-auth-flows ALLOW_USER_SRP_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --generate-secret false

---

Frontend Integration (React)

import { Amplify } from 'aws-amplify';
import { signUp, signIn, signOut, getCurrentUser, fetchAuthSession } from 'aws-amplify/auth';

Amplify.configure({
  Auth: {
    Cognito: {
      userPoolId: 'us-east-1_xxxxx',
      userPoolClientId: 'abc123',
    },
  },
});

// Sign up
await signUp({
  username: 'user@example.com',
  password: 'P@ssw0rd!',
  options: { userAttributes: { email: 'user@example.com', name: 'John' } },
});

// Sign in
const { isSignedIn } = await signIn({
  username: 'user@example.com',
  password: 'P@ssw0rd!',
});

// Get JWT token for API calls
const session = await fetchAuthSession();
const token = session.tokens?.idToken?.toString();

// API call with token
fetch('/api/orders', {
  headers: { Authorization: `Bearer ${token}` },
});

// Sign out
await signOut();

---

Hosted UI (Quick Setup)

Cognito provides a pre-built sign-in/sign-up UI.

Configure:
  - Callback URL: https://myapp.com/callback
  - Sign-out URL: https://myapp.com
  - OAuth flows: Authorization code grant
  - Scopes: openid, email, profile

URL: https://my-app.auth.us-east-1.amazoncognito.com/login

Supports: Email/password, Google, Facebook, Apple, SAML, OIDC.

---

Social Login (Google, Facebook)

User → "Sign in with Google" → Google OAuth → Cognito User Pool
                                                → Creates/links user
                                                → Returns JWT tokens

Configure in Cognito: Identity Provider → Add Google → provide Client ID/Secret.

---

JWT Tokens

id_token:      User identity (name, email, groups) — use for APIs
access_token:  Authorization scopes — use for OAuth
refresh_token: Get new tokens without re-login (30 days default)

Token validation (backend):
  1. Verify signature (Cognito public keys: JWKS)
  2. Check expiration (exp claim)
  3. Check audience (aud = your client ID)
  4. Check issuer (iss = your user pool URL)

---

Groups & RBAC

# Create group
aws cognito-idp create-group \
  --user-pool-id us-east-1_xxxxx \
  --group-name admins

# Add user to group
aws cognito-idp admin-add-user-to-group \
  --user-pool-id us-east-1_xxxxx \
  --username user@example.com \
  --group-name admins

// Check group in Lambda
const groups = event.requestContext.authorizer.claims['cognito:groups'];
if (!groups?.includes('admins')) {
  return { statusCode: 403, body: 'Forbidden' };
}

---

Lambda Triggers

// Pre Token Generation: add custom claims
export const handler = async (event: any) => {
  event.response.claimsOverrideDetails = {
    claimsToAddOrOverride: {
      'custom:role': 'admin',
      'custom:orgId': 'org-123',
    },
  };
  return event;
};

---

Key Takeaways

• User Pool = managed user directory with sign-up, sign-in, MFA, JWT tokens
• Hosted UI for quick auth without building login pages
• Use Amplify libraries for easy frontend integration
• JWT tokens: id_token for identity, access_token for authorization
• Use groups for RBAC (admin, user, editor)
• Lambda triggers to customize auth flows (add claims, validate, sync DB)
• Supports social login (Google, Facebook, Apple) and SAML/OIDC federation