AWS Cognito

Connect AWS Cognito to authenticate end users with your Char widget. Create a Cognito User Pool, configure an app client, and set up Char for token validation.

Prerequisites

An AWS account with access to Amazon Cognito
A Cognito User Pool (or permissions to create one)
Access to the Char dashboard

Quick Links

Cognito Console

Open the Amazon Cognito Console

Cognito User Pools Docs

User Pools documentation

App Client Settings

App client configuration guide

Amplify Auth Docs

AWS Amplify Authentication (Gen 2)

SDK References

aws-amplify

AWS Amplify JavaScript library

@aws-amplify/ui-react

Amplify UI React components

amazon-cognito-identity-js

Low-level Cognito Identity SDK

Configuration Steps

Create or Select a User Pool

Sign in to the AWS Cognito Console
Select User pools from the left navigation
Click Create user pool or select an existing pool

When creating a new User Pool, ensure you enable the Cognito user pool sign-in option and configure email as a required attribute.

Create an App Client

In your User Pool, navigate to App integration tab
Scroll down to App clients and analytics
Click Create app client
Configure the app client:

Setting	Value
App type	Public client
App client name	`Char Widget` (or your preferred name)
Client secret	Don’t generate a client secret
Authentication flows	ALLOW_USER_SRP_AUTH, ALLOW_REFRESH_TOKEN_AUTH

Under Hosted UI settings, configure:
- Allowed callback URLs: Your application’s callback URL(s)
- Allowed sign-out URLs: Your application’s logout URL(s)
- OAuth 2.0 grant types: Authorization code grant, Implicit grant
- OpenID Connect scopes: openid, email, profile
Click Create app client

Note Your Pool ID and Client ID

From your User Pool:

User Pool ID: Found on the User pool overview page (format: region_xxxxxxxxx)
Client ID: Found in App integration → App clients section

Find your Pool ID and Client ID in the Cognito Console

Configure Char

In the Char Dashboard:

Navigate to Settings → Integration
Under SSO Configuration, select Custom OIDC as the provider
Enter your configuration:

Field	Value
Client ID	Your Cognito App Client ID
Issuer URL	`https://cognito-idp.{region}.amazonaws.com/{userPoolId}`

Click Test Connection to verify
Click Save Changes

Configuration Reference

Char Field	AWS Cognito Value	Example
Provider Type	Custom OIDC	`custom_oidc`
Client ID	App Client ID	`1a2b3c4d5e6f7g8h9i0j`
Issuer URL	Cognito Issuer	`https://cognito-idp.us-east-1.amazonaws.com/us-east-1_AbCdEfGhI`

The issuer URL format is https://cognito-idp.{region}.amazonaws.com/{userPoolId}. Replace {region} with your AWS region (e.g., us-east-1, eu-west-1) and {userPoolId} with your User Pool ID.

Token Requirements

Char validates Cognito tokens with these requirements:

Claim	Requirement
`iss`	Must match `https://cognito-idp.{region}.amazonaws.com/{userPoolId}`
`aud`	Must include your configured App Client ID
`sub`	Required - used as the user identifier (Cognito user UUID)
`exp`	Must not be expired
`token_use`	Must be `id` (ID token, not access token)

Standard Cognito ID Token Claims

Claim	Description
`sub`	Unique user identifier (UUID)
`email`	User’s email address
`email_verified`	Whether email is verified
`cognito:username`	Cognito username
`cognito:groups`	User’s group memberships

Example: Obtaining and Passing the Token

AWS Amplify (v6)
React (Amplify)
amazon-cognito-identity-js
Hosted UI (OAuth)

import { Amplify } from 'aws-amplify';
import { fetchAuthSession } from 'aws-amplify/auth';
import "@mcp-b/embedded-agent/web-component";

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

// After user signs in
async function initWidget() {
  const session = await fetchAuthSession();
  const idToken = session.tokens?.idToken?.toString();

  if (idToken) {
    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

    if (!agent.isConnected) {
      document.body.appendChild(agent);
    }

    agent.setAttribute("auth-token", idToken);
  }
}

import { useAuthenticator } from '@aws-amplify/ui-react';
import { fetchAuthSession } from 'aws-amplify/auth';
import { useEffect } from 'react';
import "@mcp-b/embedded-agent/web-component";

function App() {
  const { user } = useAuthenticator();

  useEffect(() => {
    if (user) {
      fetchAuthSession().then((session) => {
        const idToken = session.tokens?.idToken?.toString();
        if (idToken) {
          const agent = document.querySelector("webmcp-agent");
          if (agent) {
            agent.setAttribute("auth-token", idToken);
          }
        }
      });
    }
  }, [user]);

  return <webmcp-agent />;
}

import {
  CognitoUserPool,
  CognitoUser,
  AuthenticationDetails,
} from 'amazon-cognito-identity-js';
import "@mcp-b/embedded-agent/web-component";

const poolData = {
  UserPoolId: 'us-east-1_AbCdEfGhI',
  ClientId: '1a2b3c4d5e6f7g8h9i0j',
};

const userPool = new CognitoUserPool(poolData);

// Get current authenticated user's session
const cognitoUser = userPool.getCurrentUser();

if (cognitoUser) {
  cognitoUser.getSession((err, session) => {
    if (err) {
      console.error(err);
      return;
    }

    const idToken = session.getIdToken().getJwtToken();

    const agent =
      document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

    if (!agent.isConnected) {
      document.body.appendChild(agent);
    }

    agent.setAttribute("auth-token", idToken);
  });
}

import "@mcp-b/embedded-agent/web-component";

// Parse tokens from URL hash after Hosted UI redirect
function getIdTokenFromUrl() {
  const hash = window.location.hash.substring(1);
  const params = new URLSearchParams(hash);
  return params.get('id_token');
}

const idToken = getIdTokenFromUrl();

if (idToken) {
  const agent =
    document.querySelector("webmcp-agent") ?? document.createElement("webmcp-agent");

  if (!agent.isConnected) {
    document.body.appendChild(agent);
  }

  agent.setAttribute("auth-token", idToken);

  // Clean up URL
  history.replaceState(null, '', window.location.pathname);
}

Cognito User Groups

If you’re using Cognito User Groups for authorization:

// Groups are included in the cognito:groups claim
const session = await fetchAuthSession();
const idToken = session.tokens?.idToken;

// Access groups from the token payload
const groups = idToken?.payload['cognito:groups'] || [];
console.log('User groups:', groups);

Char uses the sub claim for user identification. Group memberships (cognito:groups) are available in the token but not used for authorization by Char.

Custom Domains

If you’ve configured a custom domain for your Cognito User Pool:

In Cognito Console, navigate to App integration → Domain
Set up your custom domain (e.g., auth.yourcompany.com)
The issuer URL remains the same (cognito-idp.{region}.amazonaws.com/{poolId})

Unlike some other providers, Cognito’s issuer URL does not change when using a custom domain. Always use the standard Cognito issuer format in Char.

Troubleshooting

INVALID_ISSUER error

The issuer URL format is incorrect:

Verify the format: https://cognito-idp.{region}.amazonaws.com/{userPoolId}
Check the region: Ensure you’re using the correct AWS region
Verify Pool ID: The User Pool ID should match exactly (case-sensitive)
No trailing slash: The issuer URL should not end with /

INVALID_AUDIENCE error

The token’s audience doesn’t match:

Verify the App Client ID matches exactly
Ensure you’re using the ID token, not the access token
Check that the App Client is in the correct User Pool

JWKS_FETCH_FAILED error

Char couldn’t reach Cognito’s JWKS endpoint:

The JWKS URL is https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json
Verify your region and User Pool ID are correct
Use Test Connection in the dashboard

Token expired immediately

If tokens expire quickly:

Check your App Client’s token validity settings in App integration → App clients
ID token validity can be set from 5 minutes to 1 day
Consider implementing token refresh before expiration

cognito:groups claim missing

If user groups aren’t in the token:

Verify the user is assigned to groups in the Cognito Console
Check that your app client’s Read attributes includes groups
Groups are only included if explicitly configured

Lambda Triggers for Custom Claims

You can use Lambda triggers to add custom claims:

// Pre Token Generation Lambda Trigger
exports.handler = async (event) => {
  // Add custom claims to the ID token
  event.response = {
    claimsOverrideDetails: {
      claimsToAddOrOverride: {
        'custom:role': event.request.userAttributes['custom:role'],
        'custom:team': event.request.userAttributes['custom:team'],
      },
    },
  };

  return event;
};

Configure this in User pool properties → Lambda triggers → Pre token generation.

Security Best Practices

Enable MFA in User Pool settings for enhanced security
Configure password policies with appropriate complexity requirements
Use AWS WAF with Cognito for additional protection
Enable advanced security features for adaptive authentication
Monitor with CloudWatch for authentication anomalies
Rotate app client secrets if using confidential clients (server-side)
Use Cognito User Groups for role-based access control

Introduction

How-to Guides

Explanation

AWS Cognito

Prerequisites

Quick Links

Cognito Console

Cognito User Pools Docs

App Client Settings

Amplify Auth Docs

SDK References

aws-amplify

@aws-amplify/ui-react

amazon-cognito-identity-js

Configuration Steps

Configuration Reference

Token Requirements

Standard Cognito ID Token Claims

Example: Obtaining and Passing the Token

Cognito User Groups

Custom Domains

Troubleshooting

Lambda Triggers for Custom Claims

Security Best Practices

Introduction

How-to Guides

Explanation

​Prerequisites

​Quick Links

Cognito Console

Cognito User Pools Docs

App Client Settings

Amplify Auth Docs

​SDK References

aws-amplify

@aws-amplify/ui-react

amazon-cognito-identity-js

​Configuration Steps

​Configuration Reference

​Token Requirements

​Standard Cognito ID Token Claims

​Example: Obtaining and Passing the Token

​Cognito User Groups

​Custom Domains

​Troubleshooting

​Lambda Triggers for Custom Claims

​Security Best Practices

Prerequisites

Quick Links

SDK References

Configuration Steps

Configuration Reference

Token Requirements

Standard Cognito ID Token Claims

Example: Obtaining and Passing the Token

Cognito User Groups

Custom Domains

Troubleshooting

Lambda Triggers for Custom Claims

Security Best Practices