Federate Amazon QuickSight access with Okta

February 2021 – Updated to include newly released features, additional screenshots, and enhanced SSO integration instruction.

Amazon QuickSight is cloud-powered, serverless, and embeddable business intelligence service that makes it easy to deliver insights to everyone in your organization. As a fully managed service, QuickSight lets you easily create and publish interactive dashboards that can then be accessed from any device and embedded into your applications, portals, and websites.

QuickSight supports identity federation through Security Assertion Markup Language 2.0 (SAML 2.0) in both Standard and Enterprise editions. With federation, you can manage users using your enterprise identity provider (IdP) and pass them to QuickSight at login. Such IdPs include Microsoft Active Directory Federation Services, Ping One Federation Server, and Okta.

This post provides step-by-step guidance to configure federated single sign-on (SSO) between QuickSight and Okta. We also demonstrate ways to assign QuickSight roles based on Okta membership. Administrators can publish QuickSight applications in the Okta Portal, enabling users to SSO to QuickSight using their Okta credentials.

Creating an Okta application

The following steps guide you through the process of creating an Okta application.

1. Sign in to your Okta admin dashboard.

If you don’t have an account, you can create a free Okta Developer Edition account.

2. After login, if you’re viewing the Developer Console, you can switch to Classic UI.

3. Choose Applications.
4. Choose Add Application.
5. Search for and choose AWS Account Federation.

6. Choose Add.

7. For Application label, enter Amazon QuickSight.
8. Choose Next.

9. For Sign-On Options, select SAML 2.0.
10. For Default Relay State, enter https://quicksight.aws.amazon.com

11. Choose Identity Provider metadata (right-click) and choose Save Link As.

12. Save the XML file to disk.
13. Choose Done.

Creating a SAML provider in AWS

To create your SAML provider, complete the following steps:

1. In a new window, sign in to the AWS Management Console.
2. On the AWS Identity and Access Management (IAM) console, choose Identity providers.
3. Choose Add provider.
4. For Provider type, select SAML.
5. For Provider name, enter Okta.
6. For Metadata document, upload the XML file you downloaded earlier.
7. Choose Add provider.

8. Locate the IdP that you just created and make note of the ARN.

Creating a role for federated users

This section describes the steps for creating an IAM SAML 2.0 federation role. Although Okta is used for SSO, you can provision users in QuickSight in two different ways:

• Grant the federation role permission to create new QuickSight users when a user visits for the first time.
• Pre-provision QuickSight users using the API and add users to the appropriate groups. This is preferred for adding users to groups within QuickSight, because you can provision the users and add them to the groups at the same time. 

The following steps demonstrate how to create a federation role with permission to create new QuickSight users. If you want to pre-provision QuickSight users, see the section Pre-provisioning QuickSight users later in this post.

1. On the IAM console, choose Roles.
2. Choose Create role.
3. For Select type of trusted entity, choose SAML 2.0 federation.
4. For SAML provider, choose the IdP you created earlier (Okta).
5. Select Allow programmatic and AWS Management Console access.
6. Choose Next: Permissions.

7. Choose Create policy.

8. On the JSON tab, replace the default content with the following code, providing the IdP ARN you recorded earlier and your AWS account ID:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": "sts:AssumeRoleWithSAML",
               "Resource": "<YOUR SAML IDENTITY PROVIDER ARN>",
               "Condition": {
                   "StringEquals": {
                       "saml:aud": "https://signin.aws.amazon.com/saml"
                   }
               }
           },
           {
               "Action": [
                   "quicksight:CreateReader"
               ],
               "Effect": "Allow",
               "Resource": [
                   "arn:aws:quicksight::<YOUR ACCOUNT ID>:user/${aws:userid}"
               ]
           }
       ]
   }
   

The preceding IAM policy grants the federation role permission to self-provision a QuickSight reader with the quicksight:CreateReader action. The best practice is to grant users in your organization reader access, and then upgrade users from within the application. Instructions for upgrading users are at the end of this post.

If you prefer to pre-provision QuickSight users using the API, don’t include any actions in the permission policy.

9. Choose Review policy.
10. For Name, enter a name (for example, QuickSightOktaFederatedPolicy).
11. Choose Create policy.

12. Back on the Create role page, choose the Refresh icon and select the policy you just created.
13. Choose Next: Tags.

14. Choose Next: Review.
15. For Role name, enter a name (for example, QuickSightOktaFederatedRole).
16. For Role description, enter a description.
17. Choose Create role.

Creating an AWS access key for Okta

To create an access key for Okta, follow these steps:

1. On the IAM console, choose Users.
2. Choose Add user.
3. For User name, enter a name (for example, OktaSSOUser).
4. For Access type, select Programmatic access.
5. Choose Next: Permissions.

6. Choose Attach existing policies directly.
7. Choose Create policy.

8. On the JSON tab, enter the following code:

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "iam:ListRoles",
                   "iam:ListAccountAliases"
               ],
               "Resource": "*"
           }
       ]
   }
   

9. Choose Review policy.

9. For Name, enter a name (for example, OktaListRolesPolicy).
10. Choose Create policy.

10. On the Add user page, choose the Refresh icon and select your new policy.
11. Choose Next: Tags.

12. Choose Next: Review.
13. Choose Create user.

14. To save your access key ID and secret access key, choose Download .csv and download your credentials.

Configuring the Okta application

To configure your Okta application, complete the following steps:

1. Return to Okta and your Application Dashboard
2. Choose the Okta application Amazon QuickSight you created earlier.
3. On the Sign On tab, choose Edit.

4. For Identity Provider ARN, enter the ARN of the IdP you created earlier.
5. Choose Done.
6. On the Provisioning tab, choose Integration.
7. Choose Edit.
8. Select Enable API Integration.
9. For Access key and Secret key, enter the keys from the CSV file you downloaded earlier.
10. Choose Test API Credentials.
11. Choose Save.

12. On the navigation pane, choose To App.
13. Choose Edit.
14. For Create Users, select Enable.
15. Choose Save.

16. On the Assignments tab, on the Assign menu, choose Assign to People to grant federated access to specific users.

You can also use filters to sort on the user or group.

17. Search for users to assign.
18. Choose Assign.
19. Choose Done.

20. On the Roles menu, choose SAML User Roles to grant to users.
21. Choose Save and Go Back.

22. Choose Done.

Identity Provider Initiated (IdP-initiated) SSO

1. To use IdP-initiated SSO, log in to your Okta Applications Dashboard
2. If you’re using the admin account to log in, choose My Apps to access the application.

3. You should see the new application you created earlier, with the Okta application label Amazon QuickSight.

4. Choose the application icon to launch QuickSight.

You can now manage your users and groups using Okta as your IdP and federate access to QuickSight.

Service Provider Initiated (SP-initiated) SSO

QuickSight can also be configured for SP-initiated sign-on in the Enterprise edition. This setup enables QuickSight to redirect the user to authenticate with the IdP first before granting access to the QuickSight resources. For QuickSight-initiated SSO to work with Okta, perform the following steps:

1. Open the QuickSight portal as an administrator.
2. Choose Manage QuickSight.

3. Choose Single sign-on (SSO).
4. In the Configuration section, for IdP URL, enter the Okta application’s SSO URL.

This can be found by opening the metadata XML file that you downloaded when creating your Okta application. The URL is the value of the Location attribute in the md:SingleSignOnService element and ends with /sso/saml.

5. For IdP redirect URL parameter, enter RelayState.
6. Copy the custom URL provided under Test the end-to-end experience.
7. Choose Save.

Now you can test the end-to-end experience for signing into QuickSight.

8. Enter the custom URL you just copied into a new browser window.
9. Enter your QuickSight account name.
10. Choose Continue.

You’re redirected to authenticate with Okta.

11. Enter the credentials for your Okta user.

You’re now logged in to the QuickSight portal.

Pre-provisioning QuickSight users

The steps outlined in the preceding sections demonstrated how to grant users permission to self-provision QuickSight users when they visit QuickSight for the first time. If you prefer to pre-provision QuickSight users, you can use the API to create users and groups and then add users to those groups.

Pre-provisioning users enables admins to pre-assign permissions to QuickSight resources such as dashboards and folders.

To create a QuickSight user, use the AWS Command Line Interface (AWS CLI).

The following code links your QuickSight user to your federated username:

aws quicksight register-user \
    --aws-account-id=<YOUR ACCOUNT ID> \
    --namespace=default \
    --email=<USER@EXAMPLE.COM> \
    --iam-arn=arn:aws:iam::<YOUR ACCOUNT ID>:role/<ROLE NAME> \
    --identity-type=IAM \
    --session-name=<OKTA USERNAME> \
    --user-role=READER

Optionally, create a QuickSight group with the following code:

aws quicksight create-group \
    --aws-account-id=<YOUR ACCOUNT ID> \
    --namespace=default \
    --group-name="<YOUR GROUP NAME>" \
    --description="<YOUR GROUP DESCRIPTION>"

Add users to groups with the following code:

aws quicksight create-group-membership \
    --aws-account-id=<YOUR ACCOUNT ID> \
    --namespace=default \
    --group-name="<YOUR GROUP NAME>" \
    --member-name="<YOUR MEMBER USER NAME>"

By using the QuickSight API, you can manage users, groups, and group membership. After they’re created, groups automatically become available for use when modifying permissions to datasets, analyses, or dashboards by entering the group name instead of a specific user. For other supported group and user management functions, see List of Actions.

Managing users

You can upgrade users between reader, author, or admin on the Manage users tab of the Manage QuickSight page.

1. On the QuickSight console, choose your user name in the upper-right corner.
2. Choose Manage QuickSight.
3. In the navigation pane, choose Manage users.
4. Locate the user to upgrade, and under Role, choose the role to grant.

Deep linking dashboards

You can share QuickSight dashboards using the Okta application’s SSO URL so that users can be federated directly to specific dashboards.

To deep link to a specific QuickSight dashboard with SSO, first locate the Okta application’s SSO URL. This can be found by opening the metadata XML file that you downloaded when you created your Okta application. The URL is the value of the Location attribute in the md:SingleSignOnService element and ends with /sso/saml.

After you have the Okta application’s SSO URL, append ?RelayState= to the end of the URL followed by the URL to your QuickSight dashboard. For example, your deep link URL might look as follows:

https://my-test-org.okta.com/app/amazon_aws/abcdefg12345XYZ678/sso/saml?RelayState=https://us-east-1.quicksight.aws.amazon.com/sn/dashboards/11111111-abcd-1234-efghi-111111111111

By deep linking dashboards, you can provide users a way to use SSO and directly access specific dashboards.

Summary

This post provided a step-by-step guide for configuring Okta as your IdP, and using IAM roles to enable SSO to QuickSight. It also showed how users and groups can be managed using the QuickSight API.

Although this post demonstrated the integration of IAM and Okta, you can replicate this solution using your choice of SAML 2.0 IdPs. For other supported federation options, see Using Identity Federation and Single Sign-on (SSO) with QuickSight.

If you have any questions or feedback, please leave a comment.

About the Authors

Updated February 2021 by:

Manish Chugh is a Sr. Solutions Architect at AWS based in San Francisco, CA. He has worked with organizations ranging from large enterprises to early stage startups. He is responsible for helping customers architect scalable, secure, and cost-effective workloads on AWS. In his free time, he enjoys hiking East Bay trails, road biking, and watching (and playing) cricket.

First Posted Sept 19 by:

Loc Trinh is a solutions architect at Amazon Web Services.

Naresh Gautam is a senior solutions architect at Amazon Web Services.