How to Embed Amazon Quick-Sight Dashboard for Registered Users into Your React Application

One of the most fascinating things about using different products or services these days is the ability of businesses to gather data, analyze it and make decisions that deliver personalized services and improve your experiences. Making decisions is an integral part of running a business. And to make the best one for you, having access to the right information at the right time and in the right format is crucial for any organization. This is why Amazon Quick Sight exists.

What is Amazon Quicksight?

Amazon quick sight is a cloud-based, faster, and easy-to-use business intelligence service that allows organizations to collect data, analyze and turn them into useful insights by creating data visualizations and dashboards for their users and employees. It can connect to different data sources in the cloud, such as spreadsheets, big data sources, third-party databases, and so on. It then transforms this data into beautiful, sophisticated interactive dashboards, hereby giving you and your users the ability to analyze information fast.

One of Quick Sight’s most beautiful features is the ability to access data from anywhere, i.e., it can be embedded into your applications and accessed from your websites, mobile devices and even email. Amazon quick-sight dashboards can be embedded into internal applications in two ways;

• For Anonymous users

Anonymous users are individuals who do not have an account or login credentials to access the Quicksight dashboard. They can view the dashboard, but their access might be limited depending on how the dashboard is configured. Anonymous access can be useful for sharing information with a broad audience, such as customers, partners, or the general public.

• For registered users

Registered users, on the other hand, are individuals who have an account and login credentials to access the Quicksight dashboard. They can view the full dashboard and interact with its features, including filtering data, drilling down into specific metrics, and creating custom visualizations. Registered access is typically reserved for employees, authorized partners, or other individuals who require more advanced data access.

This article will focus on embedding a quick-sight dashboard for registered users into your React application.

Steps in Embedding a Quick Sight Dashboard into a React Application

To successfully embed a quick sight dashboard into your web application, you must meet the following requirements;

Requirements

• Have a good understanding of JavaScript/ReactJs.

• Subscribed to Amazon Quick Sight Enterprise Edition.

• You have analyses/visualizations published into one or more dashboards.

• You have admin rights on quick sight.

Step 1: Verify Your User’s Access to the Dashboard

As a developer, you will most likely work in a team and might not be the original owner of the quick-sight account you will be using. So, even if you have been granted admin rights, you will still not have permission to view the dashboard you want to embed and might get an error that looks like the one below.

The only solution to this is that the admin shares the dashboard that needs to be embedded with your user. To grant a user permission to view a dashboard, the admin will need to click on the share icon at the top right corner of the dashboard.

Click on “share dashboard,” Input the user’s email and click the share button. The user will get an email like the one below and now have permission to view, share, and export the dashboard.

Step 2: Copy your Dashboard Id and Whitelist your Website Domain

After the dashboard has been shared with the required user, the next step is to copy the dashboard Id from the dashboard URL and save it in a notepad, as shown below.

To whitelist the domain, click on the profile icon > manage quicksight> Domains and Embedding. Enter the domain names (including localhost domains) and add them to the list of embedded URLs. Embedded dashboards only work on domains that have been allowed.

Step 3: Set Up Permissions for the Webserver

If you’re embedding a dashboard into your app, your users will have to assume a role that gives them access to Amazon quick sight and the dashboard. If permissions are set correctly, a new dashboard URL with a unique auth code is generated for every login, and users will no longer have to log into quick sight to view dashboards. To achieve this, you must create an AWS Identity and Access Management (IAM) role that allows users to become a reader on Amazon Quicksight and retrieve embedding URLs for a unique user pool.

Click the “Create role” button on the roles page and choose the “Web identity” option. You will be prompted to include your identity pool Id.

If you do not have an Identity Pool ID, go to Amazon Cognito, create a user pool first, and then create the identity pool.

Include the identity pool ID and click “Next” to create a new policy.

This is what a sample policy looks like;

{ {
  "Version": "2012-10-17",
  "Statement": [
      {
      "Action": "quicksight:RegisterUser",
      "Resource": "*",
      "Effect": "Allow"
      },
      {
      "Effect": "Allow",
      "Action": [
          "quicksight:GenerateEmbedUrlForRegisteredUser"
      ],
      "Resource": “*”
      },
      "Action": "sts:AssumeRole",
      "Resource": "*",
      "Effect": "Allow"
  }
  ]
}

Assign this policy to the AuthRole created earlier. Leave tags empty, review the role, and click “create policy.”

This policy allows you to create a role that permits you to register a user and assume the role that allows you to generate a dashboard URL using the GenerateEmbedUrlForRegisteredUser() method

Step 4: Generate the dashboard URL

To generate a unique dashboard URL every time a user authenticates, performing the below steps in your web server is essential.

• The first step is to

For a user to be permitted to view a quick-sight dashboard, such a user has to be authenticated using Cognito.

How does it work?

Cognito generates three token IDs every time a user logs into your application. These IDs are IDToken, RefreshToken and AccessToken. These tokens are sent to your application server each time a user tries to authenticate or use any AWS service that requires authentication. This same token is what we will be using for every unique user that needs to view your Quicksight dashboard.

• The next step is to create a temporary IAM user and call the “sts.assume role method” to generate the IAM credentials.

Your application assumes this IAM role on the user's behalf and adds the user to Quicksight.

• Next, register the user in Quicksight with the temporary credentials using the “quicksight.registerUser” method.

This allows a user to become a registered user in the Amazon Quicksight account and also retrieve the requested dashboard URL.

• Generate the embedded URL

This step can only be done on the web server, and this is what a sample JavaScript code from Quicksight documentation looks like;

   const AWS = require('aws-sdk');

      function generateEmbedUrlForRegisteredUser(
        accountId,
        dashboardId,
        openIdToken, // Cognito-based token
        userArn, // registered user arn
        roleArn, // IAM user role to use for embedding
        sessionName, // Session name for the roleArn assume role
        allowedDomains, // Runtime allowed domain for embedding
        getEmbedUrlCallback, // GetEmbedUrl success callback method
        errorCallback // GetEmbedUrl error callback method
        ) {
        const stsClient = new AWS.STS();
        let stsParams = {
            RoleSessionName: sessionName,
            WebIdentityToken: openIdToken,
            RoleArn: roleArn
        }
        stsClient.assumeRoleWithWebIdentity(stsParams, function(err, data) {
            if (err) {
                console.log('Error assuming role');
                console.log(err, err.stack);
                errorCallback(err);
            } else {
                const getDashboardParams = {
                    "AwsAccountId": accountId,
                    "ExperienceConfiguration": {
                        "Dashboard": {
                            "InitialDashboardId": dashboardId
                        }
                    },
                    "UserArn": userArn,
                    "AllowedDomains": allowedDomains,
                    "SessionLifetimeInMinutes": 600
                };

                const quicksightClient = new AWS.QuickSight({
                    region: process.env.AWS_REGION,
                    credentials: {
                        accessKeyId: data.Credentials.AccessKeyId,
                        secretAccessKey: data.Credentials.SecretAccessKey,
                        sessionToken: data.Credentials.SessionToken,
                        expiration: data.Credentials.Expiration
                    }
                });
                var params = {
   AwsAccountId: “account id”,
   Email: 'email',
   IdentityType: 'IAM' ,
   Namespace: 'default',
   UserRole: ADMIN | AUTHOR | READER | RESTRICTED_AUTHOR | RESTRICTED_READER,
   IamArn: 'Cognito Identity role arn',
   SessionName: 'session name given in the assume role creation',
};
quicksight.registerUser(params, function (err, data1) {
   if (err) console.log("err register user”); 
   // an error occurred
   else {
      // console.log("Register User1”);
   }
})

                quicksightClient.generateEmbedUrlForRegisteredUser(getDashboardParams, function(err, data) {
                    if (err) {
                        console.log(err, err.stack);
                        errorCallback(err);
                    } else {
                        const result = {
                            "statusCode": 200,
                            "headers": {
                                "Access-Control-Allow-Origin": "*", // Use your website domain to secure access to GetEmbedUrl API
                                "Access-Control-Allow-Headers": "Content-Type"
                            },
                            "body": JSON.stringify(data),
                            "isBase64Encoded": false
                        }
                        getEmbedUrlCallback(result);
                    }
                });
            }
        });
    }

Step 5: Embed URL into React App

Once the URL has been generated, you will get a response like the one below;

//The URL returned is over 900 characters. For this example, we've shortened the string for
//readability and added ellipsis to indicate that it's incomplete.
    {
        "Status": "200",
        "EmbedUrl": "https://quicksightdomain/embed/12345/dashboards/67890...",
        "RequestId": "7bee030e-f191-45c4-97fe-d9faf0e03713"
    }

Usually, all you would need to embed this in your app is by adding the "EmbedUrl" in an iframe. But since we are embedding this in a react application, we will need a more consistent URL that will not timeout.

To embed the URL into your React App, you will need to create an endpoint that returns this "EmbedUrl" from the backend or application server.

Once the URL has been created on the backend, we should now have an endpoint that includes the dashboard Id and takes in a unique email as an argument. This endpoint might look something like this;

https://samplequicksighturl.com/embedurlquicksight/get?dashboard_id=2b8560-b43216-00985j-67h90-eb369&email=${email};

To get the quick-sight embed URL that we need on the front end;

first, we will need to install Axios using npm;

npm install axios

Next, create a src/EmbedUrl.js file and include the following lines.

Import React, { useEffect, useState } from “react”;
Import axios from “axios”;
import { Auth } from 'aws-amplify';

let QuickSightEmbedding = require('amazon-quicksight-embedding-sdk');
const EmbedDashboard = () => {
Const baseUrl = https://sampleurl.com;
Const [qsUrl, setUrl] = useState(“”);

const getQsdb = async () => {
  try {
    let user = await Auth.currentSession();
    const payloadsub = user.getIdToken().payload.sub;
    const email = user.getIdToken().payload.email;
    const options = {
      response: true,
      queryStringParameters: {
        jwtToken: user.getIdToken().getJwtToken(),
        payloadSub: payloadsub,
        email: email
      }
    };
    let api = await axios.get(
      `${baseUrl}?embedurlquicksight/get?dashboard_id=2b8560-b43216-00985j-67h90-    eb369&email=${email}`,
      user.getIdToken().getJwtToken(),
      options
    );
   setUrl(api);

  } catch (error) {
    console.log(error);
  }
};
  useEffect(() => {
     getQsdb();
  }, [])

  const getUrl = () => {
    let dashboardWrapper;
    const containerDiv = document.getElementById('dashboardContainer');
    const params = {
      url: qsUrl?.url, 
      container: containerDiv,
      parameters: {
        country: 'United States'
      },
      height: '800px',
      undoRedoDisabled: true,
      resetDisabled: true,
      footerPaddingEnabled: true
    };
    // eslint-disable-next-line no-unused-vars
    dashboardWrapper = QuickSightEmbedding.embedDashboard(params);
  };

  useEffect(() => {
      getUrl();
  }, [qsUrl.url]);

  return (
    <>
        <div id="dashboardContainer"></div>
    </>
  );
};

export default EmbedDashboard;

• First, we imported Axios and the JavaScript-embedding-SDK into the app. It is also important to import “Auth” from aws-amplify if Amplify manages your authentication. If not, feel free to include your app user’s Jwtoken, email, and others.

• Next is to call our API using Axios. The request takes in the API URL, token, and the options parameter defined earlier.

• Then the getQsdb function gets called inside the useEffect and returns the embedded URL once the app loads.

• After that, we defined another function (getUrl( )) that embeds the URL into our app. Defining the dashboard URL and the container in which the dashboard will be embedded is the most important. Then, we used the quick sight-embedding-SDK that we defined earlier to call the embedDashboard() method and passed the params option.

• Finally, we called this getUrl function inside our useEffect and told it to run only when the URL is defined. And that’s it. Your dashboard should be up and ready.

Bonus

If you need to embed multiple dashboards into your app. Then you will need an API URL that returns a list of the dashboards you need to embed with their respective IDs. The params option can also take in a dashboard Id like the one below so that you can be able to switch between multiple dashboards;

const params = {
      url: api.url,
      dashboardId: {
        Id: dashboard.id
      },
      …
}

Conclusion

So far, we’ve been able to set up permissions on our web server, generate the embed URL from the backend and embed the URL into our React application. The embedDashboard() also supports other features such as On-screen filters, Download to CSV, Reset dashboard to defaults option, and many others. Feel free to explore them.