使用Cognito用户身份验证嵌入Quick Sight视觉效果

Embedding analytics into a React application introduces complexity when you need per-user authentication. Building the identity layer that bridges Amazon Cognito and Amazon Quick Sight so that each person sees only the data their role permits adds layers of complexity that most tutorials skip. With a dedicated identity layer, you can implement fine-grained access governance for every embedded visual.

Amazon Quick is the unified analytics service from AWS. It combines business intelligence, advanced analytics capabilities, and enterprise search into a single service. Amazon Quick Sight is the business intelligence engine within Amazon Quick that powers the embedded analytics experience in your application.

This post shows you how to embed individual Amazon Quick Sight visuals into React applications with registered user authentication through Amazon Cognito. Embedding at the visual level, rather than full dashboards, gives you granular control over layout and user experience. You integrate specific charts, graphs, and metrics directly into your application interface, reusing existing dashboard visuals without building standalone dashboards for each use case.

The solution is lightweight by design. The AWS Lambda function generates scoped embed URLs quickly, including first-time user provisioning. The solution can deploy rapidly using a single AWS CloudFormation stack. Each embed URL remains valid for an extended period, minimizing re-authentication friction during sessions. By the end of this post, you will have built the full pipeline from Cognito user creation through Lambda-based URL generation to a working React front end that renders individually embedded Quick Sight visuals with per-user access control.

Solution architecture

The solution follows a four-layer serverless architecture:

1. Front-end layer consists of a React application served through Amazon CloudFront which serves the React application’s static files from an Amazon Simple Storage Service (Amazon S3) bucket. AWS WAF sits in front of CloudFront and filters malicious requests at the edge.
2. Authentication layer uses Amazon Cognito User Pools to handle user sign-in and issue JSON Web Tokens (JWTs) that are validated at the API tier.
3. Backend layer is an Amazon API Gateway endpoint protected by a Cognito Authorizer that routes authenticated requests to an AWS Lambda function. This function assumes a dedicated AWS Identity and Access Management (IAM) role and calls the Amazon Quick Sight GenerateEmbedUrlForRegisteredUser API to produce a time-scoped embed URL for the requested visual. Amazon CloudWatch captures logs and metrics from the Lambda function throughout this process.
4. Analytics layer is Amazon Quick Sight itself, which renders the individual visual inside the React application through the Embedding SDK running entirely in the browser. The Quick Sight account must have the application’s CloudFront domain registered in the embedding allowlist. Without this entry, the browser blocks the embedded iframe because of cross-origin restrictions and the visual fails to render.

Figure 1: Architecture diagram showing the complete request flow

User synchronization and role-based access control

Each Amazon Cognito user who needs to view an embedded visual must also exist as a registered user inside Amazon Quick Sight. The Lambda function handles this synchronization on every embed URL request. When a user signs in through Cognito, the React application requests an embed URL. The Lambda function receives the user’s email address from the validated JWT and calls describe_user to check whether the user already exists in Amazon Quick Sight. If Amazon Quick Sight does not find the user, a ResourceNotFoundException is raised. The function then calls register_user to create the user as a READER, the least privileged role that supports visual embedding. This approach provisions each new Cognito user in Amazon Quick Sight on first access with no manual intervention.

Role-based access control (RBAC)

Access control in this solution operates at multiple levels to enforce least privilege. API Gateway validates the Cognito JWT token before any request reaches AWS Lambda, so only authenticated users can request embed URLs. The Lambda function then registers every new user in Amazon Quick Sight with UserRole='READER' to grant the minimum permissions required for embedded visual consumption. However, registration alone doesn’t grant access to any dashboard. You can handle this permission step in one of two ways. The first approach is to have an administrator share the target dashboard with the new user through the Quick Sight console and assign Viewer permissions before the user logs in. The second approach extends the Lambda function to also call update_dashboard_permissions after register_user to grant Viewer access at registration time. This way, the user sees the visual on first login without manual intervention. After the user has Viewer permissions, the embed URL further narrows access by scoping it to a specific DashboardId, SheetId, and VisualId. A user can only view visuals explicitly shared with them through Viewer permissions on the parent dashboard. For data-level restrictions, you can layer Quick Sight Row-Level Security to control which rows each user sees based on their username or group membership.

Prerequisites

Before you begin, confirm that you have the following:

1. An AWS account with an active Amazon Quick Sight subscription configured with AWS IAM Identity Center as the authentication method.
2. Node.js 16 or later, npm, and a React development environment.
3. A published Amazon Quick Sight dashboard containing at least one visual.
4. The Dashboard ID, Sheet ID, and Visual ID for the target visual (available from the Embed visual pane in the Quick Sight dashboard).
5. Appropriate AWS Identity and Access Management (IAM) permissions to deploy CloudFormation stacks, create Lambda functions, and configure API Gateway.

Important:

This solution uses the registered user embedding method. You restrict access to dashboards and visuals that you explicitly share with your authenticated users.

Generating the embed URL with AWS Lambda

The Lambda function is the core of the backend. It receives the authenticated user’s email and the visual identifiers (dashboard_id, sheet_id, visual_id). It then confirms the user exists in Amazon Quick Sight and generates a scoped embed URL using the GenerateEmbedUrlForRegisteredUser API.

The following snippet highlights two key operations:

1. The describe_user / register_user pattern automatically provisions any new Cognito user as a READER in Amazon Quick Sight. This sync happens on every request so that first-time users are registered without manual intervention.
2. The ExperienceConfiguration uses DashboardVisual with access to a specific DashboardId, SheetId, and VisualId. This produces a visual embed URL, not a full dashboard embed URL.

# Step 1: Verify user exists in Amazon Quick (Cognito -> QS sync)
try:
    user_resp = quicksight_client.describe_user(
        AwsAccountId=aws_account_id, Namespace='default', UserName=email
    )
    user_arn = user_resp['User']['Arn']
except quicksight_client.exceptions.ResourceNotFoundException:
    user_resp = quicksight_client.register_user(
        IdentityType='IAM', Email=email, UserRole='READER',
        AwsAccountId=aws_account_id, Namespace='default', UserName=email
    )
    user_arn = user_resp['User']['Arn']

# Step 2: Generate embed URL scoped to a specific visual
response = quicksight_client.generate_embed_url_for_registered_user(
    AwsAccountId=aws_account_id,
    SessionLifetimeInMinutes=600,
    UserArn=user_arn,
    ExperienceConfiguration={
        'DashboardVisual': { 'InitialDashboardVisualId': {
            'DashboardId': dashboard_id,
            'SheetId': sheet_id,
            'VisualId': visual_id
        }}
    }
)

Rendering visuals in React with the embedding SDK

The React component fetches the embed URL from the Lambda backend and uses the amazon-quicksight-embedding-sdk to render the visual inside a container element. The two key SDK calls are createEmbeddingContext(), which initializes the embedding context, and embedVisual(), which renders a single visual (not a full dashboard) into the specified container.

// Fetch embed URL from Lambda backend
const res = await apiPOSTQS({ dashboard_id, sheet_id, visual_id });
const url = res.data.embedUrl;

// Initialize SDK and embed the visual
const embeddingContext = await QuickSightEmbedding.createEmbeddingContext();
const visual = await embeddingContext.embedVisual({
    url,
    container: `#${containerId}`,
    height: '600px',
    width: '100%',
    onChange: (event) => {
        if (event.eventName === 'FRAME_LOADED') setLoading(false);
    }
});
embeddedVisualRef.current = visual;

Custom filters from your UI

After visuals are embedded, you can connect your application’s existing filter controls directly to the Amazon Quick Sight visuals. The Quick Sight Embedding SDK exposes runtime methods to apply, update, remove, and query filter groups programmatically. A React menu or date picker in your UI can trigger a filter on the embedded visual without any page reload. Users interact with your branded components while Quick Sight handles the data processing and rendering behind the scenes. You can also chain multiple filter groups to create complex multi-dimension filter combinations from a single UI event. The result is an analytics experience that feels native to your application rather than a third-party widget dropped into the page.

The Amazon Quick Sight Embedding SDK (v2.5.0+) exposes the following runtime filtering methods on the embedded visual object:

1. addFilterGroups(filterGroups) – Apply one or more filter groups to the visual.
2. updateFilterGroups(filterGroups) – Update existing filters by FilterGroupId.
3. removeFilterGroups(filterGroupsOrIds) – Remove filters by group ID.
4. getFilterGroups() – Query the current filter state on the visual.

The following snippet shows how a React menu’s change handler applies a category filter to the embedded visual:

// Apply a custom filter from your UI to the embedded visual
const applyRegionFilter = async (selectedRegion) => {
    const filterGroup = {
        FilterGroupId: 'custom-region-filter',
        Filters: [{
            CategoryFilter: {
                FilterId: 'region-filter-1',
                Column: {
                    DataSetIdentifier: 'your-dataset',
                    ColumnName: 'Region'
                },
                Configuration: {
                    FilterListConfiguration: {
                        MatchOperator: 'CONTAINS',
                        CategoryValues: [selectedRegion]
                    }
                }
            }
        }],
        ScopeConfiguration: { AllSheets: {} },
        CrossDataset: 'ALL_DATASETS'
    };
    await embeddedVisualRef.current.addFilterGroups([filterGroup]);
};

This pattern gives your application control over the filtering UX. Users interact with your branded components while Amazon Quick Sight handles all the data processing and rendering behind the scenes. You can chain multiple filter groups to create complex, multi-dimension filter combinations, all triggered from your own UI events.

Implementation steps

Follow these steps to deploy and configure the solution in your AWS environment. You will start by deploying the backend infrastructure through AWS CloudFormation. Then you will configure the React front end and create your first Cognito user. Each step builds on the previous one, so that by the final step your application renders a live Quick Sight visual scoped to an authenticated user.

Step 1: Deploy the backend infrastructure

Deploy the AWS CloudFormation stack to provision all backend resources. This approach verifies all resources are provisioned with correct IAM permissions and cross-service references from the start, helping to reduce manual wiring errors.

1. Run the following command to clone the GitHub repository and navigate to the project directory:

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

1. Create a new AWS CloudFormation stack and upload the template.yaml file from your local GitHub repository.

Figure 2: Create a new CloudFormation stack and upload the template file

1. When deployment is complete, choose the Outputs tab. Copy the values for ApiGatewayUrl, UserPoolId, UserPoolClientId, CloudFrontDomainName, and S3BucketName. You use this information in subsequent steps.

Step 2: Configure the front-end environment

Retrieve Amazon Quick Sight visual identifiers

1. Open your published Amazon Quick Sight dashboard.
2. Choose the visual that you want to display in your front-end application. Open the three-dot menu (⋮) in the top-right corner of the visual and choose Embed visual from the context menu.

Figure 3: Context menu showing embed options for the selected visual

1. In the Embed visual panel that opens on the right, note the following IDs listed under IDs for developers: Dashboard ID, Sheet ID, Visual ID.

Figure 4: Embed visual panel displaying IDs for developers

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:

1. Your AWS Region.
2. Amazon Cognito pool information (User Pool ID and App Client ID from the CloudFormation stack Outputs tab in Step 1).
3. Amazon API Gateway endpoint (from the CloudFormation stack Outputs tab in Step 1).
4. Amazon Quick visual IDs (the DashboardId, SheetId, and VisualId you r