Embed Amazon Quick Sight visual components into web applications by using Amazon Cognito and IaC automation - AWS Prescriptive Guidance
SummaryPrerequisites and limitationsArchitectureToolsBest practicesEpicsTroubleshootingRelated resources

Embed Amazon Quick Sight visual components into web applications by using Amazon Cognito and IaC automation

Ishita Gupta and Srishti Wadhwa, Amazon Web Services

Summary

This pattern delivers a specialized approach for embedding Amazon Quick Sight visual components into React applications by using registered user embedding with streamlined Amazon Cognito authentication. These resources are then deployed through an infrastructure as code (IaC) template. Unlike traditional dashboard embedding, this solution isolates specific charts and graphs for direct integration into React applications, which dramatically improves both performance and the user experience.

The architecture establishes an efficient authentication flow between Amazon Cognito user management and Quick Sight permissions: Users authenticate through Amazon Cognito and access their authorized visualizations based on the dashboard sharing rules in Quick Sight. This streamlined approach eliminates the need for direct Quick Sight console access while maintaining robust security controls.

The complete environment is deployed through a single AWS CloudFormation template that provisions all the necessary infrastructure components, including:

  • A serverless backend that uses AWS Lambda and Amazon API Gateway

  • Secure frontend hosting through Amazon CloudFront, Amazon Simple Storage Service (Amazon S3), and AWS WAF

  • Identity management by using Amazon Cognito

All components are configured by following security best practices with least-privilege AWS Identity and Access Management (IAM) policies, AWS WAF protection, and end-to-end encryption.

This solution is ideal for development teams and organizations that want to integrate secure, interactive analytics into their applications while maintaining fine-grained control over user access. The solution uses AWS managed services and automation to simplify the embedding process, enhance security, and ensure scalability to meet evolving business needs.

Target audience and use cases:

  • Frontend developers who want to embed analytics into React apps

  • Software as a service (SaaS) product teams that want to offer per-user or role-based data visualizations

  • Solutions architects who are interested in integrating AWS analytics into custom portals

  • Business intelligence (BI) developers who want to expose visuals to authenticated users without requiring full dashboard access

  • Enterprise teams that want to embed interactive Quick Sight charts within internal tools

Prerequisites and limitations

Prerequisites

To successfully implement this pattern, make sure that the following are in place:

  • Active AWS account – An AWS account with permissions to deploy CloudFormation stacks and create Lambda, API Gateway, Amazon Cognito, CloudFront, and Amazon S3 resources.

  • Amazon Quick Sight account – An active Quick Sight account with at least one dashboard that contains visuals. For setup instructions, see Tutorial: Create an Amazon Quick Sight dashboard using sample data in the Amazon Quick Suite documentation.

  • A development environment that consists of:

    • Node.js (version 16 or later)

    • npm or yarn installed

    • Vite as the React build tool

    • React (version 19.1.1)

  • Dashboard sharing – Dashboards must be shared in Quick Sight and the implementer must log in to access the embedded visuals or dashboards.

Limitations

  • This pattern uses the registered user embedding method, which requires implementers to have an active Quick Sight account.

  • Access is restricted to the dashboards and visuals that are explicitly shared with the authenticated Quick Sight user who is implementing this pattern. If the implementer doesn’t have the correct access rights, the embed URL generation will fail and visuals won’t load.

  • The CloudFormation stack must be deployed in an AWS Region where Quick Sight, API Gateway, and Amazon Cognito are supported. For Region availability, see AWS services by Region.

Product versions

Architecture

Target architecture

The following diagram shows the architecture and workflow for this pattern.

Architecture and workflow for embedding Quick Sight visuals into a React application.

In this workflow:

  1. The user accesses the application. The user opens the React web application by using a browser. The request is routed to a CloudFront distribution, which acts as a content delivery network for the application.

  2. AWS WAF filters malicious requests. Before the request reaches CloudFront, it passes through AWS WAF. AWS WAF inspects the traffic and blocks any malicious or suspicious requests based on security rules.

  3. Amazon S3 serves static files. If the request is clean, CloudFront retrieves the static frontend assets (HTML, JS, CSS) from a private S3 bucket by using origin access control (OAC) and delivers them to the browser.

  4. The user signs in. After the application is loaded, the user signs in through Amazon Cognito, which authenticates the user and returns a secure JSON web token (JWT) for authorized API access.

  5. The application makes an API request. After login, the React application makes a secure call to the /get-embed-url endpoint on API Gateway, and passes the JWT token in the request header for authentication.

  6. The token is validated. API Gateway validates the token by using an Amazon Cognito authorizer. If the token is valid, the request proceeds; otherwise, it is denied with a 401 (unauthorized) response.

  7. The request is directed to Lambda for processing. The validated request is then forwarded to a backend Lambda function. This function is responsible for generating the embed URL for the requested Quick Sight visual.

  8. Lambda generates the embed URL from Quick Sight. IAM uses an IAM role with appropriate permissions to call the Quick Sight GenerateEmbedUrlForRegisteredUser API to generate a secure, user-scoped visual URL.

  9. Lambda returns the embed URL to API Gateway. Lambda sends the generated embed URL back to API Gateway as part of a JSON response. This response is then prepared for delivery to the frontend.

  10. The embed URL is sent to the browser. The embed URL is returned to the browser as the API response.

  11. The visual is displayed to the user. The React application receives the response and uses the Quick Sight Embedding SDK to render the specific visual to the user.

Automation and scale

Backend and frontend deployments are fully automated by using CloudFormation, which provisions all required AWS resources, including Amazon Cognito, Lambda, API Gateway, Amazon S3, CloudFront, AWS WAF, IAM roles, and Amazon CloudWatch in a single deployment.

This automation ensures consistent and repeatable infrastructure across all environments. All components scale automatically: Lambda adjusts to function invocations, CloudFront serves cached content globally, and API Gateway scales with incoming requests.

Tools

AWS services

  • Amazon Quick Sight is a cloud-native business intelligence service that helps you create, manage, and embed interactive dashboards and visuals.

  • Amazon API Gateway manages APIs that act as the bridge between the React application and backend services.

  • AWS Lambdais a serverless compute service that this pattern uses to generate secure Quick Sight embed URLs dynamically, and scales automatically based on requests.

  • Amazon Cognitoprovides authentication and authorization for users, and issues secure tokens for API access.

  • Amazon S3 hosts static frontend assets for this pattern, and serves them securely through CloudFront.

  • Amazon CloudFront delivers frontend content globally with low latency and integrates with AWS WAF for traffic filtering.

  • AWS WAF protects the web application from malicious traffic by applying security rules and rate limiting.

  • AWS CloudFormationautomates the provisioning and configuration of all application resources in a single deployment.

  • Amazon CloudWatch collects logs and metrics from Lambda, API Gateway, and AWS WAF for monitoring and troubleshooting.

Development tools

  • React JS is a frontend framework that this pattern uses to build the web application and integrate embedded Quick Sight visuals.

  • Vite is a build tool used for fast development and optimized production builds of the React application.

  • Quick Sight Embedding SDK facilitates embedding Quick Sight visuals into the React application and enables seamless interaction between the application and visuals.

Code repository

The code for this pattern is available in the GitHub Amazon Quick Sight Visual Embedding in React repository.

Best practices

This pattern automatically implements the following security best practices:

  • Uses Amazon Cognito user pools for JWT-based authentication, with optional multi-factor authentication (MFA).

  • Secures APIs with Amazon Cognito authorizers and enforces least-privilege IAM policies across all services.

  • Implements Quick Sight registered user embedding and auto-provisions users with the reader role.

  • Enforces encryption in transit that supports TLS 1.2 and later versions through CloudFront and HTTPS.

  • Encrypts data at rest by using AES-256 for Amazon S3 with versioning and OAC.

  • Configures API Gateway usage plans with throttling and quotas.

  • Secures Lambda with reserved concurrency and environment variable protection.

  • Enables logging for Amazon S3, CloudFront, Lambda, and API Gateway; monitors services by using CloudWatch.

  • Encrypts logs, applies access controls, and enforces deny policies for non-HTTPS or unencrypted uploads.

In addition, we recommend the following:

  • Use CloudFormation to automate deployments and maintain consistent configurations across environments.

  • Make sure that each user has the correct Quick Sight permissions to access embedded visuals.

  • Protect API Gateway endpoints with Amazon Cognito authorizers and enforce the principle of least privilege for all IAM roles.

  • Store sensitive information such as Amazon Resource Names (ARNs) and IDs in environment variables instead of hardcoding them.

  • Optimize Lambda functions by reducing dependencies and improving cold-start performance. For more information, see the AWS blog post Optimizing cold start performance of AWS Lambda using advanced priming strategies with SnapStart.

  • Add your CloudFront domain to the Quick Sight allowlist to enable secure visual embedding.

  • Monitor performance and security by using CloudWatch and AWS WAF for logging, alerts, and traffic protection.

Other recommended best practices

  • Use custom domains with SSL certificates from AWS Certificate Manager to provide a secure and branded user experience.

  • Encrypt Amazon S3 data and CloudWatch logs by using customer managed AWS Key Management Service (AWS KMS) keys for greater control over encryption.

  • Extend AWS WAF rules with geo-blocking, SQL injection (SQLi), cross-site scripting (XSS) protection, and custom filters for enhanced threat prevention.

  • Enable CloudWatch alarms, AWS Config, and AWS CloudTrail for real-time monitoring, auditing, and configuration compliance.

  • Apply granular IAM policies, enforce API key rotation, and allow cross-account access only when absolutely necessary.

  • Perform regular security assessments to ensure alignment with compliance frameworks such as System and Organization Controls 2 (SOC 2), General Data Protection Regulation (GDPR), and Health Insurance Portability and Accountability Act (HIPAA).

Epics

TaskDescriptionSkills required

Clone the repository.

Clone the GitHub repository for this solution to your local system and navigate to the project directory:

git clone https://github.com/aws-samples/sample-quicksight-visual-embedding.git

cd sample-quicksight-visual-embedding

This repository contains the CloudFormation template and React source code required to deploy the solution.

App developer
TaskDescriptionSkills required

Deploy the template.

  1. Sign in to the AWS Management Console and open the AWS CloudFormation console.

  2. On the Stacks page, choose Create stack in the upper right, and then choose With new resources (standard).

  3. On the Create stack page, for Prerequisite – Prepare template, choose Choose an existing template.

  4. For Specify template, choose Upload a template file.

  5. Upload the template.yaml file from your local GitHub repository, and then choose Next.

  6. On the Specify stack details page, enter the stack name (for example, quicksight-embedding-stack).

  7. On the Configure stack options page, keep the default settings, and check the box to acknowledge the creation of IAM resources. Choose Next.

  8. On the Review and create page, choose Submit.

 For more information, see Creating and managing stacks in the CloudFormation documentation.

AWS administrator

Monitor stack creation.

Monitor the stack in the Events tab until its status is CREATE_COMPLETE.

AWS administrator

Retrieve stack outputs.

  1. When deployment is complete, choose the Outputs tab.

  2. Note key outputs: ApiGatewayUrl, UserPoolId, UserPoolClientId, CloudFrontDomainName, and S3BucketName. You will use this information in subsequent steps.

AWS administrator
TaskDescriptionSkills required

Retrieve Quick Sight visual identifiers.

  1. Open the Quick Sight dashboard.

  2. Note the dashboard ID, sheet ID, and visual ID of each visual you plan to embed in your web application.

Quick Sight administrator

Configure your local React environment.

To set up your local React environment and link it to AWS resources, create an .env file in the my-app/ folder of your local GitHub repository. Populate the file with:

  • Your AWS Region

  • Amazon Cognito pool information (from CloudFormation stack outputs)

  • API Gateway endpoint (from CloudFormation stack outputs)

  • Quick Sight visual IDs (DashboardId, SheetId, VisualId)

Here’s an example .env file:

VITE_AWS_REGION=us-east-1

# Cognito Configuration (from CloudFormation outputs)
VITE_USER_POOL_ID=us-east-1_xxxxxxxxx VITE_USER_POOL_WEB_CLIENT_ID=xxxxxxxxxxxxxxxxxxxxxxxxxx

# API Configuration (from CloudFormation outputs)
VITE_API_URL=https:/your-api-id.execute-api.us-east-1.amazonaws.com/prod

# QuickSight Visual Configuration
VITE_DASHBOARD_ID=your-dashboard-id 
VITE_SHEET_ID=your-sheet-id 
VITE_VISUAL_ID=your-visual-id
App developer
TaskDescriptionSkills required

Create or Manage Users in Cognito

To enable authenticated user access to embedded Quick Sight visuals, you first create users in Amazon Cognito:

  1. On the Amazon Cognito console, choose User pools, and then choose the pool that matches UserPoolId (from CloudFormation outputs).

  2. Add users to the pool. You can choose from two options:

    • In Amazon Cognito, create users manually with email addresses and temporary passwords (for more information, see the Amazon Cognito documentation)

      —or—

    • Enable self-signup in the UI by setting hideSignUp={false} in the my-app/src/auth/AuthWrapper.jsx file.

AWS administrator

Provide Quick Sight dashboard access

To provide access to Quick Sight visuals, provide Viewer permission access to authenticated users:

  1. On the Quick Sight console, choose Dashboards.

  2. Select the dashboard you want to share by choosing its name.

  3. In the upper-right corner of the dashboard page, choose Share.

  4. In the sharing panel, choose Share with specific users.

  5. To add new users, choose Invite users or the plus (+) icon.

  6. In the email field, enter the recipient's complete email address. (This email must match the user’s Amazon Cognito login exactly)

  7. From the Permission menu next to the email field, choose Viewer.

  8. To send the invitation and grant access, choose Share.

Each user will receive an email with a link to the dashboard. You can modify permissions at any time through the Share menu.

For more information, see Granting individual Amazon Quick Sight users and groups access to a dashboard in Amazon Quick Sight in the Amazon Quick Suite documentation.

Quick Sight administrator
TaskDescriptionSkills required

Install dependencies and build the project.

In the React application directory, run the following commands to generate optimized production files:

cd my-app
npm install
npm run build
App developer

Upload the build files to Amazon S3.

Upload all the files from the my-app/dist/ directory to the S3 bucket provisioned by CloudFormation (do not upload the folder itself).

App developer

Create a CloudFront invalidation.

On the CloudFront console, create an invalidation for path /* to refresh cached content after deployment. For instructions, see Invalidate files in the CloudFront documentation.

AWS administrator
TaskDescriptionSkills required

Add the CloudFront domain to the Quick Sight allowlist.

To enable your CloudFront domain to securely embed Quick Sight visuals:

  1. On the Quick Sight console, choose Manage Quick Sight, Domains and Embedding.

  2. Add the CloudFront domain to the Domain box (for example, https://d1234567890abc.cloudfront.net).

  3. Choose Add domain.

Quick Sight administrator
TaskDescriptionSkills required

Open the React application.

Use the CloudFront domain (from CloudFormation outputs) to open the deployed React web application in a browser.

App owner

Verify authentication.

Sign in to the application by using Amazon Cognito credentials to verify the authentication flow and JWT validation through API Gateway.

App owner

Verify embedded visuals.

Confirm that Quick Sight visuals load properly within the application based on user-specific access permissions.

App owner

Validate API and Lambda connectivity.

Confirm that the application can successfully call the /get-embed-url API and retrieve valid Quick Sight embed URLs without errors.

App owner
TaskDescriptionSkills required

Monitor by using CloudWatch.

You can use AWS observability tools to monitor the application and to maintain secure, scalable performance in production.

Review Lambda logs, API Gateway metrics and Amazon Cognito authentication events in CloudWatch to ensure application health and to detect anomalies.

AWS administrator

Track AWS WAF and CloudFront logs.

Inspect AWS WAF logs for blocked or suspicious requests and CloudFront access logs for performance and caching metrics.

AWS administrator

Troubleshooting

IssueSolution

"Domain not allowed" error

  1. On the Quick Sight console, choose Manage Quick Sight, Domains and Embedding.

  2. Add your CloudFront domain (for example, https://d1234567890abc.cloudfront.net).

  3. Save the configuration and reload the application.

Authentication errors

Possible causes:

  • Incorrect Amazon Cognito user pool ID or application client ID in the .env file.

  • User wasn’t confirmed in the Amazon Cognito user pool.

  • Invalid or missing JWT token in API requests.

Solutions:

  • Verify Amazon Cognito configuration values in the .env file.

  • On the Amazon Cognito console, check the Users tab to verify that the user is active.

  • Confirm that the Authorization header contains a valid JWT token.

  • On the API Gateway console, check Authorizers to verify that API Gateway is using the Amazon Cognito authorizer for authentication.

API Gateway errors

Possible causes:

  • Missing or misconfigured Amazon Cognito authorizer in API Gateway.

  • Insufficient Lambda permissions for calling the Quick Sight API.

  • API URL mismatch between .env and CloudFormation outputs.

Solutions:

  • Reconfirm that the API Gateway invoke URL is in your .env file.

  • On the API Gateway console, check Authorizers to verify the Amazon Cognito setup.

  • Attach the required IAM policy with quicksight:GenerateEmbedUrlForRegisteredUser to the Lambda execution role.

  • Review CloudWatch logs for detailed API or permission errors. For more information, see the API Gateway documentation.

Quick Sight visuals don’t load

Possible causes:

  • Incorrect Quick Sight dashboard ID, sheet ID, or visual ID in the environment configuration.

  • No Quick Sight user access to the visual or dashboard.

  • Missing cross-origin resource sharing (CORS) configuration in API Gateway.

Solutions:

  • Confirm the Quick Sight IDs from the three-dot menu in upper-right corner of the dashboard visual.

  • Confirm that the Quick Sight user has the Viewer role for the shared dashboard.

  • Enable CORS in API Gateway and redeploy the API. For more information, see the API Gateway documentation.

  • Inspect the browser console for CORS for network-related errors.

"User does not have access" error

Possible causes:

  • The user’s email wasn’t shared with the Quick Sight dashboard.

  • Incorrect user role or permission in Quick Sight.

Solution:

  1. On the Quick Sight console, open your dashboard, and then choose Share, Share Dashboard.

  2. Add the user’s email address (matching the Amazon Cognito login email).

  3. Assign the Viewer permission role.

  4. Ask the user to log out and sign in again to refresh permissions.

Related resources

AWS documentation

Tutorials and videos