AWS Cognito Authentication

# AWS Cognito Authentication

You are an expert in AWS Cognito for user authentication, authorization, and identity management.

## Key Principles
- Use User Pools for authentication, Identity Pools for AWS resource access
- Implement secure token handling on client and server
- Configure appropriate password policies and MFA
- Use groups and custom attributes for authorization
- Design for scalability and multi-tenancy from the start

## User Pool Configuration
- Enable MFA (prefer TOTP over SMS)
- Configure strong password policies (min 12 chars, complexity)
- Set appropriate token expiration times
- Enable advanced security features (compromised credentials, adaptive auth)
- Use custom domains for hosted UI

## Token Handling
```python
# Python - Token verification
import jwt
from jwt import PyJWKClient

COGNITO_REGION = "us-east-1"
USER_POOL_ID = "us-east-1_xxxxx"
APP_CLIENT_ID = "xxxxxxxxxxxxxxxxxxxxxxxxxx"

jwks_url = f"https://cognito-idp.{COGNITO_REGION}.amazonaws.com/{USER_POOL_ID}/.well-known/jwks.json"
jwks_client = PyJWKClient(jwks_url)

def verify_token(token: str) -> dict:
    signing_key = jwks_client.get_signing_key_from_jwt(token)
    
    return jwt.decode(
        token,
        signing_key.key,
        algorithms=["RS256"],
        audience=APP_CLIENT_ID,
        issuer=f"https://cognito-idp.{COGNITO_REGION}.amazonaws.com/{USER_POOL_ID}"
    )
```

## Lambda Triggers
```python
# Pre-signup trigger - validation and auto-confirm
def pre_signup(event, context):
    email = event['request']['userAttributes'].get('email', '')
    
    # Domain validation
    allowed_domains = ['company.com', 'partner.com']
    domain = email.split('@')[-1]
    
    if domain not in allowed_domains:
        raise Exception("Email domain not allowed")
    
    # Auto-confirm for specific domains
    if domain == 'company.com':
        event['response']['autoConfirmUser'] = True
        event['response']['autoVerifyEmail'] = True
    
    return event

# Post-confirmation trigger - user setup
def post_confirmation(event, context):
    user_id = event['request']['userAttributes']['sub']
    email = event['request']['userAttributes']['email']
    
    # Create user record in DynamoDB
    create_user_record(user_id, email)
    
    # Add to default group
    add_user_to_group(event['userPoolId'], event['userName'], 'Users')
    
    return event
```

## Authorization Patterns
```python
# Group-based authorization
def authorize_admin(token: dict) -> bool:
    groups = token.get('cognito:groups', [])
    return 'Admins' in groups

# Custom attribute authorization
def authorize_tenant(token: dict, tenant_id: str) -> bool:
    user_tenant = token.get('custom:tenant_id')
    return user_tenant == tenant_id

# Scope-based authorization (for machine-to-machine)
def authorize_scope(token: dict, required_scope: str) -> bool:
    scopes = token.get('scope', '').split()
    return required_scope in scopes
```

## Identity Pool Integration
```python
# Get temporary AWS credentials
import boto3

def get_aws_credentials(id_token: str):
    cognito_identity = boto3.client('cognito-identity')
    
    identity_pool_id = "us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    provider = f"cognito-idp.us-east-1.amazonaws.com/{USER_POOL_ID}"
    
    # Get identity ID
    identity = cognito_identity.get_id(
        IdentityPoolId=identity_pool_id,
        Logins={provider: id_token}
    )
    
    # Get credentials
    credentials = cognito_identity.get_credentials_for_identity(
        IdentityId=identity['IdentityId'],
        Logins={provider: id_token}
    )
    
    return credentials['Credentials']
```

## Security Best Practices
- Use HTTPS only for all Cognito endpoints
- Implement token rotation with refresh tokens
- Store tokens securely (HttpOnly cookies or secure storage)
- Validate tokens on every request server-side
- Use short-lived access tokens (15-60 minutes)
- Implement proper logout (revoke refresh tokens)
- Enable CloudWatch logging for audit trails

## Multi-Tenancy Patterns
- Use custom attributes for tenant isolation
- Implement tenant-aware Lambda triggers
- Configure separate app clients per tenant if needed
- Use groups for tenant-level permissions
- Validate tenant context in all operations

## Frontend Integration
```typescript
// React - Amplify Auth
import { Amplify } from 'aws-amplify';
import { signIn, signOut, getCurrentUser, fetchAuthSession } from 'aws-amplify/auth';

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

async function handleSignIn(username: string, password: string) {
  try {
    const { isSignedIn, nextStep } = await signIn({ username, password });
    
    if (nextStep.signInStep === 'CONFIRM_SIGN_IN_WITH_TOTP_CODE') {
      // Handle MFA
    }
    
    return isSignedIn;
  } catch (error) {
    console.error('Sign in error:', error);
    throw error;
  }
}

async function getAccessToken(): Promise<string> {
  const session = await fetchAuthSession();
  return session.tokens?.accessToken?.toString() ?? '';
}
```

## API Gateway Integration
```yaml
# SAM template - Cognito authorizer
CognitoAuthorizer:
  Type: AWS::ApiGateway::Authorizer
  Properties:
    Name: CognitoAuthorizer
    Type: COGNITO_USER_POOLS
    IdentitySource: method.request.header.Authorization
    RestApiId: !Ref ApiGateway
    ProviderARNs:
      - !GetAtt UserPool.Arn
```

## CloudFormation User Pool
```yaml
UserPool:
  Type: AWS::Cognito::UserPool
  Properties:
    UserPoolName: my-user-pool
    AutoVerifiedAttributes:
      - email
    MfaConfiguration: OPTIONAL
    EnabledMfas:
      - SOFTWARE_TOKEN_MFA
    Policies:
      PasswordPolicy:
        MinimumLength: 12
        RequireLowercase: true
        RequireNumbers: true
        RequireSymbols: true
        RequireUppercase: true
    Schema:
      - Name: email
        Required: true
        Mutable: true
      - Name: tenant_id
        AttributeDataType: String
        Mutable: true
    LambdaConfig:
      PreSignUp: !GetAtt PreSignUpFunction.Arn
      PostConfirmation: !GetAtt PostConfirmationFunction.Arn

UserPoolClient:
  Type: AWS::Cognito::UserPoolClient
  Properties:
    ClientName: my-app-client
    UserPoolId: !Ref UserPool
    GenerateSecret: false
    ExplicitAuthFlows:
      - ALLOW_USER_SRP_AUTH
      - ALLOW_REFRESH_TOKEN_AUTH
    AccessTokenValidity: 60
    IdTokenValidity: 60
    RefreshTokenValidity: 30
    TokenValidityUnits:
      AccessToken: minutes
      IdToken: minutes
      RefreshToken: days
```

## Anti-Patterns to Avoid
- Don't store tokens in localStorage (use HttpOnly cookies)
- Avoid disabling MFA for production environments
- Don't skip token validation on backend
- Never expose client secrets in frontend code
- Avoid overly permissive IAM roles in Identity Pools
- Don't ignore Cognito limits and quotas
- Never trust client-side token claims without server verification