Understanding Amazon Cognito User Pool Federation

Introduction

Amazon Cognito User Pools provide user authentication and authorization for web and mobile applications. Rather than building login, MFA, password reset, and session management from scratch, Cognito handles these functions and issues JWT tokens your application can validate. Federation extends this to allow users to sign in using existing identities — Google, Apple, Microsoft Entra ID, or corporate SAML providers — without creating a separate Cognito password. This gives users a familiar login experience while centralizing authentication in Cognito.

Step-by-Step: Federating with an External IdP

flowchart TD
    A["1. Configure the External Identity Provider"]
    B["2. Add IdP to Cognito User Pool"]
    C["3. Federation Flow (OIDC)"]
    D["4. Attribute Mapping"]
    E["5. JWT Token Validation in Your API"]
    A --> B
    B --> C
    C --> D
    D --> E

Step 1: Configure the External Identity Provider

Google (OIDC):

1. Create OAuth 2.0 credentials in Google Cloud Console
2. Add Cognito callback URL: https://your-domain.auth.us-east-1.amazoncognito.com/oauth2/idpresponse
3. Note Client ID and Client Secret

Corporate SAML (e.g., Okta):

1. Create SAML app in Okta
2. Set ACS URL: https://cognito-idp.us-east-1.amazonaws.com/us-east-1_XXXXX/saml2/idpresponse
3. Set Entity ID: urn:amazon:cognito:sp:us-east-1_XXXXX
4. Download SAML metadata XML

Step 2: Add IdP to Cognito User Pool

# Add Google as an OIDC provider
aws cognito-idp create-identity-provider   --user-pool-id us-east-1_XXXXX   --provider-name Google   --provider-type Google   --provider-details '{
    "client_id": "12345.apps.googleusercontent.com",
    "client_secret": "GOCSPX-xxx",
    "authorize_scopes": "email profile openid"
  }'   --attribute-mapping '{
    "email": "email",
    "name": "name",
    "username": "sub"
  }'

Step 3: Federation Flow (OIDC)

1. User clicks "Sign in with Google" on your app
2. App redirects to Cognito Hosted UI:
   https://your-domain.auth.us-east-1.amazoncognito.com/oauth2/authorize
   ?identity_provider=Google&response_type=code&client_id=xxx&redirect_uri=xxx

3. Cognito redirects user to Google login
4. User authenticates with Google
5. Google redirects to Cognito callback with authorization code
6. Cognito exchanges code for Google tokens (ID + access token)
7. Cognito maps Google attributes to Cognito user pool attributes
8. Cognito creates/updates federated user in user pool
9. Cognito issues its own JWT tokens (ID, Access, Refresh) to app
10. App validates Cognito JWT and establishes session

Step 4: Attribute Mapping

Cognito maps IdP attributes to user pool attributes:

// Google → Cognito attribute mapping
{
  "email": "email",              // Google email → Cognito email
  "name": "name",                // Google name → Cognito name  
  "sub": "username",             // Google subject ID → Cognito username
  "picture": "custom:avatar_url" // Google picture → custom attribute
}

Step 5: JWT Token Validation in Your API

import boto3, jwt, requests

COGNITO_REGION = "us-east-1"
USER_POOL_ID = "us-east-1_XXXXX"
APP_CLIENT_ID = "your-app-client-id"

# Fetch JWKS from Cognito
jwks_url = f"https://cognito-idp.{COGNITO_REGION}.amazonaws.com/{USER_POOL_ID}/.well-known/jwks.json"
jwks = requests.get(jwks_url).json()

def verify_token(token: str) -> dict:
    # Decode header to get key ID
    header = jwt.get_unverified_header(token)
    
    # Find matching public key
    key = next(k for k in jwks['keys'] if k['kid'] == header['kid'])
    public_key = jwt.algorithms.RSAAlgorithm.from_jwk(key)
    
    # Verify and decode
    return jwt.decode(
        token,
        public_key,
        algorithms=['RS256'],
        audience=APP_CLIENT_ID,
        issuer=f"https://cognito-idp.{COGNITO_REGION}.amazonaws.com/{USER_POOL_ID}"
    )

Key Takeaways

• Cognito federation allows users to sign in via Google, Apple, Facebook, or SAML providers without creating separate passwords.
• The federation flow keeps credentials with the IdP — Cognito receives an authorization code, exchanges it for tokens, maps attributes, and issues its own JWTs.
• Attribute mapping bridges IdP claims to Cognito user pool attributes — map carefully to avoid identity collisions across different IdPs.
• Cognito issues RS256-signed JWTs validated using public keys from the JWKS endpoint — never validate with the secret key (HMAC).
• Use federated identities (Cognito Identity Pools) after User Pool authentication to exchange Cognito JWTs for temporary AWS credentials (IAM roles) for direct AWS service access.