How do I integrate IAM Identity Center with Quick for single sign-on authentication?

Short description

Set the identity method for your Quick users when you create your AWS account. For existing accounts, you can't directly change the identity method. Instead, you must recreate the Quick account.

Note: IAM Identity Center is available only for the Quick Enterprise Edition. If you use IAM Identity Center with a Standard Edition subscription, then you receive the following error message:

"InvalidParameterValueException: The requested edition or authentication method is invalid."

Resolution

Prerequisite: You must meet the IAM Identity Center requirements.

Configure single sign-on for a new Quick subscription

Activate IAM Identity Center

First, activate IAM Identity Center in the same AWS Region as the Quick subscription.

It's a best practice to activate IAM Identity Center for an AWS Organizations account. With this configuration, you can deploy Quick to any account in the organization. However, you can also activate IAM Identity Center at the account level if you require a separate identity store for Quick. For example, you might need to embed Quick dashboards for external customers or have business subsidiaries with separate identity stores that collaborate on Quick. For more information, see Manage access to insights with an account instance of AWS IAM Identity Center and Amazon Quick Sight.

(External IdPs only) Connect the IdP to IAM Identity Center

If you use an external identity provider (IdP), then connect to the IdP through IAM Identity Center.

Important: Don't directly connect the IdP to Quick. You must connect through IAM Identity Center to use single sign-on.

Set up the Quick account with IAM Identity Center

Prerequisites: Make sure that your AWS Identity and Access Management (IAM) principal has the required Quick permissions. Also, create groups in IAM Identity Center for your Quick roles, such as quick-admins, quick-authors, and quick-readers. You can map these groups to Quick roles when you set up the account. If you use an external IdP, then assign the groups to the IAM Identity Center in your IdP.

Subscribe to Quick, and select IAM Identity Center for the authentication method. Then, on the Role mapping page, complete the following steps:

1. Map your IAM Identity Center groups to the Admin, Author, and Reader roles in Quick.
   Important: Users in IAM Identity Center groups get access only after you map the group to a Quick role.
2. Select the IAM role that controls Quick access to AWS resources.
3. Review your configuration, and then choose Finish.
4. Choose Go to Amazon Quick.

Quick automatically registers the account as an IAM Identity Center application.

Update an existing Quick subscription to use IAM Identity Center

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Create an inventory of existing Quick resources

Important: When you recreate a Quick account, you don't need to manually migrate or recreate user identities. When you map a group to a Quick role, IAM Identity Center automatically provisions users. However, the user's Amazon Resource Name (ARN) changes, so you must update references to the previous ARN.

You must manually migrate Quick assets such as data sources, datasets, analyses, and dashboards to the new account. To get lists of all your assets, run the following AWS CLI commands.

Note: In the following commands, replace 123456789012 with your account ID.

Run the following list-data-sources command to list all existing data sources:

aws quicksight list-data-sources \
    --aws-account-id 123456789012

Run the following list-data-sets command to list all existing data sets:

aws quicksight list-data-sets \
    --aws-account-id 123456789012

Run the following list-analyses command to list all existing analyses:

aws quicksight list-analyses \
    --aws-account-id 123456789012

Run the following list-dashboards command to list all existing dashboards:

aws quicksight list-dashboards \
    --aws-account-id 123456789012

Run the following list-themes command to list all existing themes:

aws quicksight list-themes \
    --aws-account-id 123456789012

Run the following list-vpc-connections command to list all existing virtual private cloud (VPC) connections:

aws quicksight list-vpc-connections \
    --aws-account-id 123456789012

Run the following list-folders command to list all existing folders:

aws quicksight list-folders \
    --aws-account-id 123456789012

Run the following list-users command to list all existing users with role and group assignments in your existing subscription:

aws quicksight list-users \
    --aws-account-id 123456789012 \
    --namespace default

Check your IAM permissions

Make sure that the IAM user or role that you use to migrate has the required permissions to export and import the asset bundle. You must have the required permissions for the ARN of each resource that you export.

Export your resources

Prerequisite: Create an Amazon Simple Storage Service (Amazon S3) bucket to store resources during migration.

Run the following start-asset-bundle-export-job command to export your resources as a Quick asset file:

aws quicksight start-asset-bundle-export-job \
   --aws-account-id 123456789012 \
   --asset-bundle-export-job-id migration-export-1 \
   --resource-arns arn:aws:quicksight:us-east-1:123456789012:dashboard/example-dashboard-id \
   --include-all-dependencies \
   --include-permissions \
   --export-format QUICKSIGHT_JSON

Note: Replace 123456789012 with your account ID, us-east-1 with your Region, and example-dashboard-id with your dashboard ID. Each export job accepts up to 100 resource ARNs. One account can concurrently run up to five export jobs.

The preceding command exports analyses, dashboards, datasets, data sources, refresh schedules, themes, and VPC connections. For more information, see Asset bundle export operations.

To check the status of your export, run the following describe-asset-bundle-export-job command:

aws quicksight describe-asset-bundle-export-job \
    --aws-account-id 123456789012 \
    --asset-bundle-export-job-id migration-export-1

Note: Replace 123456789012 with your account ID.

In the output, check for the SUCCESSFUL job status to confirm that the export completed. The output also contains a download URL that you can use to access your export. The URL is valid only for 5 minutes. To refresh the URL, rerun describe-asset-bundle-export-job. Save each .qs bundle to your Amazon S3 bucket.

To batch export a large quantity of resources, see Automate and accelerate your Amazon Quick Sight asset deployments using the new APIs.

Check each .qs file to confirm that the contents are complete. Quick doesn't automatically reimport sensitive properties, so you must manually reapply them. Note the data source secrets, VPC connection settings, and refresh schedules.

Unsubscribe and resubscribe to Quick

Important: When you unsubscribe, Quick deletes all users, datasets, dashboards, and other account resources. You can't undo the action.

Complete the following steps:

1. Make sure that you have the required permissions to unsubscribe.
2. Delete your Quick account.
3. Subscribe to Quick, and select IAM Identity Center for the authentication method.
   Note: Make sure that you already activated IAM Identity Center. For instructions, see Configure single sign-on for a new Quick subscription.

Recreate your account

First, recreate your namespaces and shared folders. You don't need to recreate the default namespace. Run the following create-namespace command for each non-default namespace:

aws quicksight create-namespace \
    --aws-account-id 123456789012 \
    --namespace example-namespace \
    --identity-store QUICKSIGHT

Note: Replace 123456789012 with your account ID and example-namespace with your namespace name.

Import the asset bundles to your namespaces and folders.

To confirm that your migration is complete, open each migrated dashboard and analysis and refresh the SPICE datasets. Make sure that the data sources can connect. Then, reapply row-level security and column-level security rules that reference Quick managed users. Make sure that the rules use the new IAM Identity Center user ARNs.

To avoid downtime, complete the following steps to use a second account to set up migration:

1. Export your resources from the original account.
2. Import the resources into a second account that uses IAM Identity Center.
3. Confirm that the migration included all resources.
4. Unsubscribe and resubscribe to the original account.
5. Export the resources from the second account.
6. Import the resources into the original account.

For an example of a cross-account resource transfer, see How do I use templates to set up cross-account access in Quick Sight?

Assign the Quick admin role to an IAM Identity Center user or group

Complete the following steps:

1. Create a group in IAM Identity Center that you can grant admin access to. You can use an existing group. To grant admin access to a user, make sure that the user is in the correct group.
   Note: If you use an external IdP, then make sure that you assigned the user and group to Quick in IAM Identity Center.
2. Open the IAM Identity Center console.
3. Choose Applications, and then select the Quick application.
4. Under Assigned users and groups, confirm that the user or group is listed. To add the user or group, choose Assign users or groups, and then choose the user or group.
5. Sign in to Quick with the Admin role.
6. Provide admin access to the IAM Identity Center group. You can also provide Author and Reader access.
   Important: You must map the group in Quick even if the group already has admin access in IAM Identity Center.

Related information

IAM policy examples for Quick

Simplify business intelligence identity management with Amazon Quick Suite and AWS IAM Identity Center