Skip to main content

AWS Cognito SAML Integration

This guide explains how to configure AWS Cognito as a SAML Service Provider (SP) to use Signia as an Identity Provider (IdP).

Overview​

After completing this integration:

  • Cognito users will authenticate using Signia credentials
  • Users can log in with WebAuthn/Passkeys (Face ID, Touch ID, security keys)
  • Cognito User Pools trust Signia's SAML assertions
  • Users can access AWS services and Cognito-integrated applications

Prerequisites​

  • AWS account with administrator access
  • IAM permissions to manage Cognito User Pools
  • Admin access to Signia ID dashboard
  • SAML enabled for your Signia tenant

If SAML is not enabled yet, see Enable SAML 2.0 Identity Provider.

Part 1: Configure Signia IdP​

Step 1: Download Signia Metadata​

  1. Log in to Signia ID dashboard (https://signiaid.com)
  2. Select your tenant from the dropdown
  3. Navigate to SAML in the left sidebar
  4. In the Identity Provider Information section:
    • Click Download Metadata button
    • Save as signia-metadata.xml

Alternative: Download directly from metadata URL:

curl https://<your-tenant>.signiaauth.com/saml/metadata -o signia-metadata.xml

Part 2: Create or Configure Cognito User Pool​

Step 1: Create User Pool (if needed)​

  1. Log in to AWS Console (https://console.aws.amazon.com)
  2. Navigate to Amazon Cognito
  3. Click User pools in the left sidebar
  4. Click Create user pool

Configure User Pool (Step-by-step wizard):

Step 1 - Configure sign-in experience:

  • Provider types: Select Cognito user pool
  • Cognito user pool sign-in options: Select Email
  • Click Next

Step 2 - Configure security requirements:

  • Password policy: Configure as needed (or keep defaults)
  • MFA: Select No MFA (or configure if required)
  • Click Next

Step 3 - Configure sign-up experience:

  • Self-service sign-up: Enable or disable
  • Required attributes: Select email (required for SAML)
  • Click Next

Step 4 - Configure message delivery:

  • Select Send email with Cognito (for testing) or configure SES
  • Click Next

Step 5 - Integrate your app:

  • User pool name: Enter name (e.g., "MyApp Users")
  • Hosted authentication pages: Check Use the Cognito Hosted UI
  • Domain: Configure in next steps
  • Initial app client: Configure basic settings
  • Click Next

Step 6 - Review and create:

  • Review all settings
  • Click Create user pool

Step 2: Note User Pool ID and Region​

After creating the pool:

  • User Pool ID: us-east-1_ABC123
  • Region: us-east-1

You'll need these for Signia configuration.

Part 3: Add SAML Identity Provider to Cognito​

Step 1: Navigate to Identity Providers​

  1. In AWS Console → Cognito → User pools
  2. Select your User Pool
  3. Click Sign-in tab in the navigation
  4. Scroll down to Federated identity provider sign-in section
  5. Click Add identity provider

Step 2: Select SAML​

On the Add identity provider page:

  • Select SAML as the identity provider type

Step 3: Configure SAML Provider​

Provider name: Enter a name

  • Example: Signia
  • This will be the provider identifier
  • Use alphanumeric characters only (no spaces)

Metadata document source: Select Upload metadata document

  • Click Choose file
  • Select the signia-metadata.xml file downloaded in Part 1

Map attributes: Configure attribute mapping (can also be done later)

  • Map SAML email → User pool email

Note the Provider name after creation - you'll use this in app client settings.

Click Add identity provider

Step 4: Note Cognito SP Entity ID​

Cognito's Entity ID follows this format:

urn:amazon:cognito:sp:<user-pool-id>

Example:

urn:amazon:cognito:sp:us-east-1_ABC123

Step 5: Note Cognito ACS URL​

Cognito's ACS URL follows this format:

https://<user-pool-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse

Example:

https://my-app.auth.us-east-1.amazoncognito.com/saml2/idpresponse

If you haven't configured a domain yet, see Step 6.

Step 6: Configure User Pool Domain (if needed)​

  1. Click App integration tab in the navigation
  2. In the Domain section, click Actions → Create Cognito domain (or Create custom domain)

Cognito domain:

  • Enter a unique domain prefix: my-app-12345
  • Full domain will be: my-app-12345.auth.us-east-1.amazoncognito.com
  • Click Create Cognito domain

Custom domain (requires ACM certificate):

  • Enter your custom domain: auth.example.com
  • Select your ACM certificate
  • Create CNAME record pointing to Cognito
  • Click Create custom domain
tip

You can find your domain under App integration → Domain after creation. The ACS URL uses this domain.

Part 4: Configure Signia Service Provider​

Step 1: Add Service Provider in Signia​

  1. Log in to Signia ID dashboard
  2. Navigate to SAML → Service Providers
  3. Click Add Service Provider

Step 2: Enter Cognito Details​

Name: AWS Cognito Production (or your preferred name)

Entity ID: Cognito's Entity ID

urn:amazon:cognito:sp:<user-pool-id>

Example: urn:amazon:cognito:sp:us-east-1_ABC123

ACS URL: Cognito's ACS endpoint

https://<user-pool-domain>.auth.<region>.amazoncognito.com/saml2/idpresponse

Example: https://my-app.auth.us-east-1.amazoncognito.com/saml2/idpresponse

NameID Format: Email Address

Enabled: ✓ (checked)

Step 3: Save Service Provider​

Click Create Service Provider

The Service Provider will appear in the list.

Part 5: Configure App Client​

Step 1: Create App Client (if needed)​

  1. In your Cognito User Pool, click App integration tab
  2. Scroll to App clients and analytics section
  3. Click Create app client

App type: Select Public client (for web/mobile apps) or Confidential client (for server-side)

App client name: Enter name (e.g., "MyApp")

Client secret:

  • For Public client: No secret generated
  • For Confidential client: Generate a client secret

Authentication flows: Select:

  • ✓ ALLOW_REFRESH_TOKEN_AUTH
  • ✓ ALLOW_USER_SRP_AUTH

Token expiration:

  • Refresh token: 30 days (default)
  • Access token: 60 minutes
  • ID token: 60 minutes

Click Create app client

Step 2: Note App Client ID​

After creation, note the Client ID:

abc123xyz456

Step 3: Configure Hosted UI Settings​

  1. In App integration tab, scroll to App clients and analytics
  2. Click on your app client name
  3. Scroll to Hosted UI section
  4. Click Edit

Allowed callback URLs: Enter your application's callback URL(s)

https://myapp.example.com/callback
https://localhost:3000/callback

(Enter one URL per line or comma-separated)

Allowed sign-out URLs: Enter logout URL(s)

https://myapp.example.com/logout
https://localhost:3000/logout

Identity providers: Check:

  • ✓ Signia (the SAML provider you created)

OAuth 2.0 grant types: Select:

  • ✓ Authorization code grant
  • ✓ Implicit grant (optional, for legacy apps)

OpenID Connect scopes: Select:

  • ✓ openid
  • ✓ email
  • ✓ profile

Click Save changes

Part 6: Map SAML Attributes​

Step 1: Configure Attribute Mapping​

  1. In Cognito User Pool → Sign-in tab
  2. Scroll to Federated identity provider sign-in section
  3. Click on Signia provider
  4. In the identity provider details, scroll to Attribute mapping
  5. Click Edit

Step 2: Map Required Attributes​

Map SAML attributes from Signia to Cognito user attributes:

SAML attributeUser pool attribute
emailemail
firstNamegiven_name
lastNamefamily_name
name (optional)name
warning

Email is required - Cognito uses the email attribute as the federated user's identifier. If this mapping is missing, user creation will fail after SSO.

Click Save changes

Part 7: Test SSO​

Step 1: Get Hosted UI URL​

Build the Cognito Hosted UI URL:

https://<user-pool-domain>.auth.<region>.amazoncognito.com/login?client_id=<app-client-id>&response_type=code&redirect_uri=<callback-url>

Example:

https://my-app.auth.us-east-1.amazoncognito.com/login?client_id=abc123xyz456&response_type=code&redirect_uri=https://myapp.example.com/callback

Step 2: Initiate SSO​

  1. Open the Hosted UI URL in a browser
  2. Click Sign in with Signia button

Step 3: Verify Redirect​

You should be redirected to:

https://<your-tenant>.signiaauth.com/saml/sso?SAMLRequest=...

Step 4: Authenticate with Signia​

  1. Signia displays authentication UI
  2. Authenticate with:
    • WebAuthn/Passkey (Face ID, Touch ID, security key)
    • Or email/password (if enabled)

Step 5: Verify Success​

After authentication:

  • Redirected back to Cognito
  • Cognito processes SAML assertion
  • User redirected to your app's callback URL
  • Authorization code included in URL parameters

Step 6: Exchange Code for Tokens​

Your application exchanges the authorization code for tokens:

curl -X POST \
  https://<user-pool-domain>.auth.<region>.amazoncognito.com/oauth2/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'client_id=<app-client-id>' \
  -d 'code=<authorization-code>' \
  -d 'redirect_uri=<callback-url>'

Response includes:

  • id_token: JWT with user claims
  • access_token: For Cognito API calls
  • refresh_token: For token renewal

Troubleshooting​

"Invalid SAML Response"​

Cause 1: Metadata not uploaded correctly

Solution:

  1. Re-download Signia metadata
  2. Delete Signia identity provider in Cognito
  3. Re-create with fresh metadata

Cause 2: Certificate mismatch

Solution:

  1. Verify certificate fingerprint in Signia dashboard
  2. Re-upload metadata to Cognito

"User pool client not configured correctly"​

Cause: Signia provider not enabled for app client

Solution:

  1. Navigate to App integration tab
  2. Scroll to App clients and analytics
  3. Click on your app client name
  4. Scroll to Hosted UI section
  5. Click Edit
  6. Under Identity providers, check Signia
  7. Click Save changes

"Invalid redirect_uri"​

Cause: Callback URL not in allowed list

Solution:

  1. Navigate to App integration tab
  2. Scroll to App clients and analytics
  3. Click on your app client name
  4. Scroll to Hosted UI section
  5. Click Edit
  6. Add your callback URL to Allowed callback URLs
  7. Click Save changes

Email Attribute Missing​

Symptom: User creation fails after SSO

Cause: Email attribute not mapped

Solution:

  1. Navigate to Sign-in tab → Federated identity provider sign-in
  2. Click on Signia provider
  3. Scroll to Attribute mapping section
  4. Click Edit
  5. Map email (SAML) → email (User pool)
  6. Click Save changes

Clock Skew Issues​

Symptom: "Assertion expired" errors

Solution:

# Check system time (UTC)
date -u

# Compare with Signia time
curl -I https://<tenant>.signiaauth.com | grep Date

# Sync clocks (difference should be < 5 minutes)

Advanced Configuration​

Custom Domain with ACM Certificate​

Use your own domain instead of Cognito's default domain.

  1. Obtain ACM certificate for your domain (e.g., auth.example.com)
  2. In Cognito → App integration → Domain
  3. Click Actions → Create custom domain
  4. Enter domain name
  5. Select ACM certificate
  6. Create CNAME record in Route 53 or your DNS provider
  7. Click Create custom domain

Lambda Triggers​

Customize user attributes or add custom logic during authentication.

  1. Navigate to User pool properties tab
  2. Scroll to Lambda triggers section
  3. Click Add Lambda trigger
  4. Select trigger type:
    • Pre token generation: Modify claims in ID token
    • Pre authentication: Add custom validation
    • Post authentication: Log authentication events
  5. Select your Lambda function
  6. Click Save changes

Example: Add custom claims:

exports.handler = async (event) => {
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        department: 'Engineering',
        custom_role: 'Admin'
      }
    }
  };
  return event;
};

Group-Based Access Control​

Map SAML groups to Cognito groups.

  1. Create groups in Cognito:

    • Navigate to Groups tab
    • Click Create group
    • Enter group name (e.g., "Administrators")
    • Optionally set IAM role and precedence
    • Click Create group

  2. Configure attribute mapping:

    • In Sign-in tab, edit your SAML provider's attribute mapping
    • Map SAML groups attribute → Cognito groups

  3. Use groups in Lambda triggers or app logic for authorization

MFA Configuration​

Add additional security layer beyond Signia authentication.

  1. Navigate to Sign-in tab
  2. Scroll to Multi-factor authentication section
  3. Click Edit
  4. Select MFA enforcement:
    • Required: All users must set up MFA
    • Optional: Users can choose to enable MFA
  5. Enable MFA methods:
    • ✓ Authenticator apps (TOTP)
    • ✓ SMS text message
  6. Click Save changes

Integration with Applications​

Web Application (Authorization Code Flow)​

// Redirect to Cognito Hosted UI
const authUrl = `https://${userPoolDomain}.auth.${region}.amazoncognito.com/login?`
  + `client_id=${clientId}`
  + `&response_type=code`
  + `&redirect_uri=${callbackUrl}`;

window.location.href = authUrl;

// Handle callback
const urlParams = new URLSearchParams(window.location.search);
const code = urlParams.get('code');

// Exchange code for tokens
const tokenResponse = await fetch(
  `https://${userPoolDomain}.auth.${region}.amazoncognito.com/oauth2/token`,
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
    body: new URLSearchParams({
      grant_type: 'authorization_code',
      client_id: clientId,
      code: code,
      redirect_uri: callbackUrl
    })
  }
);

const tokens = await tokenResponse.json();
// tokens.id_token, tokens.access_token, tokens.refresh_token

Mobile Application (with AWS Amplify)​

import { Amplify, Auth } from 'aws-amplify';

Amplify.configure({
  Auth: {
    region: 'us-east-1',
    userPoolId: 'us-east-1_ABC123',
    userPoolWebClientId: 'abc123xyz456',
    oauth: {
      domain: 'my-app.auth.us-east-1.amazoncognito.com',
      redirectSignIn: 'myapp://callback',
      redirectSignOut: 'myapp://logout',
      responseType: 'code'
    }
  }
});

// Sign in with Signia (SAML)
Auth.federatedSignIn({ customProvider: 'Signia' });

API Gateway Authorization​

Use Cognito authorizer to protect API endpoints.

  1. Create Cognito User Pool Authorizer in API Gateway
  2. Configure authorizer:
    • Token source: Authorization header
    • Token validation: ID token or Access token
  3. Attach authorizer to API methods
  4. Clients include token in requests: 
    Authorization: Bearer <id_token>

Security Recommendations​

Enable CloudTrail Logging​

Monitor Cognito API calls for security and compliance.

  1. Navigate to CloudTrail
  2. Create trail
  3. Log Cognito events:
    • cognito-idp:AdminInitiateAuth
    • cognito-idp:GetUser
    • cognito-idp:ListUsers

Token Expiration Settings​

Configure token lifetimes for security.

  1. Navigate to App integration tab
  2. Scroll to App clients and analytics
  3. Click on your app client name
  4. In the Auth session section, you can configure:
    • Refresh token expiration: 30 days (default)
    • Access token expiration: 60 minutes
    • ID token expiration: 60 minutes
  5. Click Edit and Save changes

Certificate Rotation​

When Signia certificate expires:

  1. Download new metadata from Signia
  2. Delete old SAML provider in Cognito
  3. Re-create with new metadata
  4. Test SSO flow

Cost Considerations​

AWS Cognito pricing (check AWS Cognito Pricing for current rates):

  • First 50,000 MAUs: Free tier
  • 50,001 - 100,000 MAUs: $0.0055 per MAU
  • 100,001+ MAUs: Volume discounts available
  • Advanced security features: Additional cost per MAU

MAU = Monthly Active User (user who authenticates at least once per month)

note

Federated users (SAML/Social) count toward your MAU total. Each unique user authenticated via Signia SAML is counted as one MAU.

Next Steps​

Additional Resources​