How to embed QuickSight
into Embedportal.

1. Why this is needed

To embed QuickSight dashboards securely, Embedportal needs permission to generate temporary embed URLs on your behalf. You grant that permission by creating an IAM role in your AWS account that allows a narrow set of read-only QuickSight actions. Your data never leaves your AWS environment — Embedportal only signs the embed URL.

works with — Amazon QuickSight in any AWS region.

2. Prerequisites

• An AWS account with Amazon QuickSight activated.
• IAM permissions to create a role and deploy a CloudFormation stack.
• Your Embedportal Organization ID (shown on the QuickSight setup guide and pre-filled in the template).
• An Embedportal workspace (Professional or Enterprise).
• About 15 minutes.

3. Download the CloudFormation Template

In Embedportal, open the QuickSight integration setup guide and click Download Template (JSON). The template:

• Creates an IAM role trusted only by Embedportal’s AWS account.
• Pins the trust with an External ID equal to your Embedportal Organization ID.
• Attaches a least-privilege policy covering only the QuickSight embed actions.
• Exports the resulting Role ARN as a stack output.

4. Deploy the Stack in AWS Console

1. 01

   Open CloudFormation

   In the AWS Console, switch to the region where your QuickSight lives and open CloudFormation.

2. 02

   Create stack

   Click Create stack → With new resources (standard).

3. 03

   Upload the template

   Choose Upload a template file and select the JSON you downloaded from Embedportal.

4. 04

   Name the stack

   Use a recognisable name like atspark-quicksight-role. Parameters are pre-filled.

5. Review & Create

• Click Next through configuration options (defaults are fine).
• Check “I acknowledge that AWS CloudFormation might create IAM resources”.
• Click Submit.
• Wait for the stack status to reach CREATE_COMPLETE (typically under a minute).

6. Copy the Role ARN

1. 01

   Open the Outputs tab

   Click on your stack in the CloudFormation console and switch to the Outputs tab.

2. 02

   Copy the RoleArn value

   The value starts with arn:aws:iam::. Copy the full ARN.

3. 03

   Paste it into Embedportal

   Back in Embedportal, paste the ARN into the IAM Role ARN field and click Save & Test Connection. Embedportal will assume the role, list your QuickSight dashboards, and confirm the connection.

7. Manual (AWS CLI) setup

Prefer CLI over CloudFormation? The Embedportal setup guide also provides a manual flow:

1. Save the trust policy as trust-policy.json (Embedportal shows the exact JSON).
2. Create the role:

   aws iam create-role \
     --role-name quicksight-embed-role \
     --assume-role-policy-document file://trust-policy.json

3. Save the permissions policy as permissions.json, replacing CUSTOMER_ACCOUNT_ID with your 12-digit AWS Account ID.
4. Attach the policy:

   aws iam put-role-policy \
     --role-name quicksight-embed-role \
     --policy-name quicksight-embed \
     --policy-document file://permissions.json

5. Get the ARN:

   aws iam get-role --role-name quicksight-embed-role \
     --query 'Role.Arn' --output text

6. Paste the ARN into Embedportal.

8. Fields you’ll fill in Embedportal

That’s it. Embedportal already knows the External ID (it’s your organization ID) and derives the region from the ARN.

9. Tag-based row-level security

QuickSight supports two RLS modes: dataset-based and tag-based. Embedportal uses tag-based RLS because it scales to multi-tenant SaaS without provisioning a QuickSight user per viewer.

1. In QuickSight, open the dataset and toggle Row-level security → Tag-based.
2. Declare tag keys such as organization_id and region.
3. Filter the dataset on those tags in the dataset definition.
4. In Embedportal, enable RLS on the dashboard and tick the same attributes.

On every embed request Embedportal passes the viewer’s attributes as session tags when calling GenerateEmbedUrlForRegisteredUser (or ForAnonymousUser on anonymous dashboards). QuickSight applies the filter before the query runs.

For the full vendor-agnostic setup, see Row-level security for embedded dashboards.

10. Security & the External ID

The IAM role uses your Embedportal Organization ID as an External ID in the trust policy. This prevents the cross-account confused-deputy problem: even if another party learns the role ARN, they can’t assume the role without also knowing the External ID — which only Embedportal and your IAM trust policy share.

• Keep the permissions policy narrow — the CloudFormation template only grants QuickSight embed actions.
• Audit role usage via AWS CloudTrail; every sts:AssumeRole is logged.
• Rotate: if you rebuild the Embedportal workspace, delete the stack and redeploy so a fresh External ID is used.

11. Troubleshooting

• AccessDenied on AssumeRole — External ID mismatch. Re-download the template (it includes the correct External ID) and redeploy.
• Dashboards list is empty — QuickSight doesn’t have any dashboards in the role’s region, or the role lacks quicksight:ListDashboards.
• “QuickSight not registered” — QuickSight isn’t active in the region you chose. Activate it in the QuickSight console.
• Tag-based RLS returns zero rows — the tag key in the dataset doesn’t match the attribute name in Embedportal. Names are case-sensitive.
• UnrecognizedClientException — role ARN was copied from a different AWS account than Embedportal is assuming. Redeploy the template in the correct account.

12. FAQ