AWS quicksight medium security documentation change
Summary
Added comprehensive documentation for embedding Generative Q&A experience for both registered and anonymous users, including IAM permission setup, URL generation, and SDK implementation details
Security assessment
The changes introduce security controls through IAM policy conditions (AllowedEmbeddingDomains) to restrict embedding domains, and emphasize session management to prevent throttling/abuse. These are explicit security measures to prevent unauthorized embedding and protect resource access.
Diff
diff --git a/quicksight/latest/user/embedding-gen-bi.md b/quicksight/latest/user/embedding-gen-bi.md index f5b26f4dd..7b99ec5f0 100644 --- a/quicksight/latest/user/embedding-gen-bi.md +++ b/quicksight/latest/user/embedding-gen-bi.md @@ -4,0 +5,2 @@ +Embedding the Generative Q&A experience for registered usersEmbedding the Generative Q&A experience for anonymous users + @@ -10 +12,627 @@ Intended audience: Amazon QuickSight developers -In the following sections, you can find detailed information about how to set up an embedded Generative Q&A experience that uses enhanced NLQ capabilties powered by LLMs. The Generative Q&A experience is the recommended replacement for the embedded Q Search Bar and provides an updated BI expereince for users. +In the following sections, you can find detailed information about how to set up an embedded Generative Q&A experience that uses enhanced NLQ capabilties powered by LLMs. The Generative Q&A experience is the recommended replacement for the embedded Q Search Bar and provides an updated BI experience for users. + +###### Topics + + * Embedding the Amazon Q in QuickSight Generative Q&A experience for registered users + + * Embedding the Amazon Q in QuickSight Generative Q&A experience for anonymous (unregistered) users + + + + +## Embedding the Amazon Q in QuickSight Generative Q&A experience for registered users + +In the following sections, you can find detailed information about how to set up an embedded Generative Q&A experience for registered users of QuickSight. + +###### Topics + + * Step 1: Set up permissions + + * Step 2: Generate the URL with the authentication code attached + + * Step 3: Embed the Generative Q&A experience URL + + * Optional embedded Generative Q&A experience functionalities + + + + +### Step 1: Set up permissions + +In the following section, you can find how to set up permissions for your backend application or web server to embed the Generative Q&A experience. This task requires administrative access to AWS Identity and Access Management (IAM). + +Each user who accesses a Generative Q&A experience assumes a role that gives them Amazon QuickSight access and permissions. To make this possible, create an IAM role in your AWS account. Associate an IAM policy with the role to provide permissions to any user who assumes it. The IAM role needs to provide permissions to retrieve embedding URLs for a specific user pool. + +With the help of the wildcard character _*_ , you can grant the permissions to generate a URL for all users in a specific namespace. Or you can grant permissions to generate a URL for a subset of users in specific namespaces. For this, you add `quicksight:GenerateEmbedUrlForRegisteredUser`. + +You can create a condition in your IAM policy that limits the domains that developers can list in the `AllowedDomains` parameter of a `GenerateEmbedUrlForRegisteredUser` API operation. The `AllowedDomains` parameter is an optional parameter. It grants developers the option to override the static domains that are configured in the **Manage QuickSight** menu and instead list up to three domains or subdomains that can access a generated URL. This URL is then embedded in a developer's website. Only the domains that are listed in the parameter can access the embedded Generative Q&A experience. Without this condition, developers can list any domain on the internet in the `AllowedDomains` parameter. + +To limit the domains that developers can use with this parameter, add an `AllowedEmbeddingDomains` condition to your IAM policy. For more information about the `AllowedDomains` parameter, see [GenerateEmbedUrlForRegisteredUser](https://docs.aws.amazon.com/quicksight/latest/APIReference/API_GenerateEmbedUrlForRegisteredUser.html) in the _Amazon QuickSight API Reference_. + +The following sample policy provides these permissions. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "quicksight:GenerateEmbedUrlForRegisteredUser" + ], + "Resource": "arn:partition:quicksight:region:accountId:user/namespace/userName", + "Condition": { + "ForAllValues:StringEquals": { + "quicksight:AllowedEmbeddingDomains": [ + "https://my.static.domain1.com", + "https://*.my.static.domain2.com" + ] + } + } + } + ] + } + +Also, if you're creating first-time users who will be Amazon QuickSight readers, make sure to add the `quicksight:RegisterUser` permission in the policy. + +The following sample policy provides permission to retrieve an embedding URL for first-time users who are to be QuickSight readers. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Action": "quicksight:RegisterUser", + "Resource": "*", + "Effect": "Allow" + }, + { + "Effect": "Allow", + "Action": [ + "quicksight:GenerateEmbedUrlForRegisteredUser" + ], + "Resource": [ + "arn:partition:quicksight:region:accountId:user/namespace/userName" + ], + "Condition": { + "ForAllValues:StringEquals": { + "quicksight:AllowedEmbeddingDomains": [ + "https://my.static.domain1.com", + "https://*.my.static.domain2.com" + ] + } + } + } + ] + } + +Finally, your application's IAM identity must have a trust policy associated with it to allow access to the role that you just created. This means that when a user accesses your application, your application can assume the role on the user's behalf and provision the user in QuickSight. + +The following example shows a sample trust policy. + + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "AllowLambdaFunctionsToAssumeThisRole", + "Effect": "Allow", + "Principal": { + "Service": "lambda.amazonaws.com" + }, + "Action": "sts:AssumeRole" + }, + { + "Sid": "AllowEC2InstancesToAssumeThisRole", + "Effect": "Allow", + "Principal": { + "Service": "ec2.amazonaws.com" + }, + "Action": "sts:AssumeRole" + } + ] + } + +For more information regarding trust policies for OpenID Connect or Security Assertion Markup Language (SAML) authentication, see the following sections of the _IAM User Guide:_ + + * [Creating a role for web identity or OpenID Connect federation (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_oidc.html) + + * [Creating a role for SAML 2.0 federation (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp_saml.html) + + + + +### Step 2: Generate the URL with the authentication code attached + +In the following section, you can find how to authenticate your user and get the embeddable Q topic URL on your application server. If you plan to embed the Generative Q&A experience for IAM or Amazon QuickSight identity types, share the Q topic with the users. + +When a user accesses your app, the app assumes the IAM role on the user's behalf. Then the app adds the user to QuickSight, if that user doesn't already exist. Next, it passes an identifier as the unique role session ID. + +Performing the described steps ensures that each viewer of the Q topic is uniquely provisioned in QuickSight. It also enforces per-user settings, such as the row-level security and dynamic defaults for parameters. + +The following examples perform the IAM authentication on the user's behalf. This code runs on your app server. + + + import com.amazonaws.auth.AWSCredentials; + import com.amazonaws.auth.BasicAWSCredentials; + import com.amazonaws.auth.AWSCredentialsProvider; + import com.amazonaws.regions.Regions; + import com.amazonaws.services.quicksight.AmazonQuickSight; + import com.amazonaws.services.quicksight.AmazonQuickSightClientBuilder; + import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserRequest; + import com.amazonaws.services.quicksight.model.GenerateEmbedUrlForRegisteredUserResult; + import com.amazonaws.services.quicksight.model.RegisteredUserEmbeddingExperienceConfiguration; + import com.amazonaws.services.quicksight.model.RegisteredUserGenerativeQnAEmbeddingConfiguration; + + /** + * Class to call QuickSight AWS SDK to get url for embedding Generative Q&A experience. + */ + public class RegisteredUserGenerativeQnAEmbeddingSample { + + private final AmazonQuickSight quickSightClient; + + public RegisteredUserGenerativeQnAEmbeddingSample() { + this.quickSightClient = AmazonQuickSightClientBuilder + .standard() + .withRegion(Regions.US_EAST_1.getName()) + .withCredentials(new AWSCredentialsProvider() { + @Override + public AWSCredentials getCredentials() { + // provide actual IAM access key and secret key here + return new BasicAWSCredentials("access-key", "secret-key"); + } + + @Override + public void refresh() { + } + } + ) + .build(); + } + + public String getQuicksightEmbedUrl( + final String accountId, // AWS Account ID + final String topicId, // Topic ID to embed + final List<String> allowedDomains, // Runtime allowed domain for embedding + final String userArn // Registered user arn to use for embedding. Refer to Get Embed Url section in developer portal to find how to get user arn for a QuickSight user. + ) throws Exception { + + final RegisteredUserEmbeddingExperienceConfiguration experienceConfiguration = new RegisteredUserEmbeddingExperienceConfiguration() + .withGenerativeQnA(new RegisteredUserGenerativeQnAEmbeddingConfiguration().withInitialTopicId(topicId)); + final GenerateEmbedUrlForRegisteredUserRequest generateEmbedUrlForRegisteredUserRequest = new GenerateEmbedUrlForRegisteredUserRequest();