Step 3: Authenticate Your User and Get the URL - Amazon QuickSight

Step 3: Authenticate Your User and Get the URL

In the following section, you can find out how to authenticate your user and get the embeddable dashboard URL on your application server. Although we explain this process using AWS CLI commands as examples, you or your developer needs to wrap these API operations in code that runs on the application server. You can find some examples following.

When a user accesses your app, the app should assume the IAM role (created in step 2) on the user's behalf. Then it should add the user to Amazon QuickSight, if that user doesn't already exist. Next, it should pass an identifier as the unique role session ID.

Doing this ensures that each viewer of the dashboard is uniquely provisioned in Amazon QuickSight. It also enforces per-user settings, such as the row-level security and dynamic defaults for parameters.

To assume the role, choose one of the following AWS Security Token Service (AWS STS) API operations:

  • AssumeRole – Use this when you are using an IAM identity to assume the role.

  • AssumeRoleWithWebIdentity – Use this when you are using a web identity provider to authenticate your user.

  • AssumeRoleWithSaml – Use this when you are using SAML to authenticate your users.

The following example shows the CLI command to set the IAM role.

/* Assume the role with permissions enabled for actions: quickSight:RegisterUser and quicksight:GetDashboardEmbedURL */ /* You can use assume-role, assume-role-with-web-identity, or assume-role-with-saml */ aws sts assume-role \ --role-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \ --role-session-name john.doe@example.com

The assume-role operation returns three output parameters: the access key, the secret key, and the session token.

Note

If you get an ExpiredToken error when calling the AssumeRole operation, this is because the previous SESSION TOKEN is still in the environment variables. Clear this by setting the following variables:

  • AWS_ACCESS_KEY_ID

  • AWS_SECRET_ACCESS_KEY

  • AWS_SESSION_TOKEN

The following example shows how to set these three parameters in the CLI. If you are using a Microsoft Windows machine, use set instead of export.

export AWS_ACCESS_KEY_ID = "access_key_from_assume_role" export AWS_SECRET_ACCESS_KEY = "secret_key_from_assume_role" export AWS_SESSION_TOKEN = "session_token_from_assume_role"

Running these commands sets the role session ID of the user visiting your website to embedding_quicksight_dashboard_role/john.doe@example.com. The role session ID is made up of the role name from role-arn and the role-session-name value. Using the unique role session ID for each user ensures that appropriate permissions are set for each user. It also prevents any throttling of user access. Throttling is a security feature that prevents the same user from accessing Amazon QuickSight from multiple locations.

The role session ID also becomes the user name in Amazon QuickSight. You can use this pattern to provision your users in Amazon QuickSight ahead of time, or to provision them the first time they access the dashboard. With pay-per-session mode in Amazon QuickSight, you can provision thousands of users. You get charged only when they access Amazon QuickSight.

The following example shows the CLI command that you can use to provision a user. For more information about RegisterUser, DescribeUser, and other Amazon QuickSight API operations, see the Amazon QuickSight API Reference.

/* If the user does not exist in QuickSight, register the user */ aws quicksight register-user \ --aws-account-id 111122223333 \ --namespace default \ --identity-type IAM \ --iam-arn "arn:aws:iam::111122223333:role/embedding_quicksight_dashboard_role" \ --user-role READER \ --session-name "john.doe@example.com" \ --email john.doe@example.com \ --region us-east-1

If the user is authenticated through Microsoft AD, you don't need to use RegisterUser to set them up. Instead, they should be automatically subscribed the first time they access Amazon QuickSight. For Microsoft AD users, you can use DescribeUser to get the user ARN.

The first time a user accesses Amazon QuickSight, you can also add this user to the group that the dashboard is shared with. The following example shows the CLI command to add a user to a group.

aws quicksight create-group-membership \ --aws-account-id=111122223333 \ --namespace=default \ --group-name=financeusers \ --member-name="embedding_quicksight_dashboard_role/john.doe@example.com"

You now have a user of your app who is also a user of Amazon QuickSight, and who has access to the dashboard.

Finally, to get a signed URL for the dashboard, call get-dashboard-embed-url from the app server. This returns the embeddable dashboard URL. The following example shows how to get the URL for an embedded dashboard using a server-side call for users authenticated through AWS Managed Microsoft AD.

aws quicksight get-dashboard-embed-url \ --aws-account-id 111122223333 \ --dashboard-id 1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89 \ --identity-type QUICKSIGHT \ --user-arn arn:aws:quicksight:us-east-1:111122223333:user/default/embedding_quicksight_dashboard_role/embeddingsession

The following example shows how to get the URL for an embedded dashboard using a server-side call for users authenticated through SSO.

aws quicksight get-dashboard-embed-url \ --aws-account-id 111122223333 \ --dashboard-id 1a1ac2b2-3fc3-4b44-5e5d-c6db6778df89 \ --identity-type IAM

For more information on using this operation, see GetDashboardEmbedUrl. You can use this and other API operations in your own code.