Tutorial: Amazon QuickSight and IAM identity federation

Sign in to your Okta dashboard. If you don't have one, create a free Okta Developer Edition account by using this QuickSight-branded URL. When you have activated your email, sign in to Okta.

On the Okta website, choose <> Developer Console at upper left, and then choose Classic UI.

Choose Add Applications, and choose Add app.

Enter aws for Search, and choose Amazon Account Federation from the search results.

Choose Add to create an instance of this application.

For Application label, enter Amazon Account Federation - QuickSight.

Choose Next.

For SAML 2.0, Default Relay State, enter https://quicksight.aws.amazon.com.

Open the context (right-click) menu for Identity Provider metadata, and choose to save the file. Name the file metadata.xml. You need this file in the next procedure.

The contents of the file look similar to the following.

<md:EntityDescriptor xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" entityID="http://www.okta.com/exkffz2hATwiVft645d5">
    <md:IDPSSODescriptor WantAuthnRequestsSigned="false" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
    <md:KeyDescriptor use="signing">
        <ds:KeyInfo xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
        <ds:X509Data>
            <ds:X509Certificate>
            MIIDpjCCAo6gAwIBAgIGAXVjA82hMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYDVQQGEwJVUzETMBEG 
            . 
            .        (certificate content omitted)
            . 
            QE/6cRdPQ6v/eaFpUL6Asd6q3sBeq+giRG4=
            </ds:X509Certificate>
        </ds:X509Data>
        </ds:KeyInfo>
    </md:KeyDescriptor>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</md:NameIDFormat>
    <md:NameIDFormat>urn:oasis:names:tc:SAML:2.0:nameid-format:unspecified</md:NameIDFormat>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://dev-1054988.okta.com/app/amazon_aws/exkffz2hATwiVft645d5/sso/saml"/>
    <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://dev-1054988.okta.com/app/amazon_aws/exkffz2hATwiVft645d5/sso/saml"/>
    </md:IDPSSODescriptor>
    </md:EntityDescriptor>

After you have the XML file saved, scroll to the bottom of the Okta page, and choose Done.

Keep this browser window open, if possible. You need it later in the tutorial.

Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

In the navigation pane, choose Identity providers, Create Provider.

Enter the following settings:

Choose Next Step, Create.

Locate the IdP that you created and choose it to view the settings. Note the Provider ARN. You need this to finish the tutorial.

Verify that the identity provider is created with your settings. In IAM, choose Identity providers, Okta (the IdP you added), Download metadata. The file should be the one that you recently uploaded.

Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

In the navigation pane, choose Roles, Create Role.

For Select type of trusted entity, choose the card labeled SAML 2.0 federation.

For SAML provider, select the IdP that you created in the previous procedure, for example Okta.

Enable the option Allow programmatic and Amazon Management Console access.

Choose Next: Permissions.

Paste the following policy into the editor.

In the policy editor, update the JSON with your provider's Amazon Resource Name (ARN).

{
    "Version": "2012-10-17",
    "Statement": [
    {
        "Effect": "Allow",
        "Action": "sts:AssumeRoleWithSAML",
        "Resource": "arn:aws-cn:iam::111111111111:saml-provider/Okta",
        "Condition": {
        "StringEquals": {
            "saml:aud": "https://signin.aws.amazon.com/saml"
        }
        }
    }
    ]
    }

Choose Review policy.

For Name, enter QuicksightOktaFederatedPolicy, and then choose Create policy.

Choose Create policy, JSON a second time.

Paste the following policy into the editor.

In the policy editor, update the JSON with your Amazon Web Services account ID. It should be the same account ID that you used in the previous policy in the provider ARN.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "quicksight:CreateReader"
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws-cn:quicksight::111111111111:user/${aws:userid}"
            ]
        }
    ]
    }

You can omit the Amazon Web Services Region name in the ARN, as shown following.

arn:aws-cn:quicksight::111111111111:user/$${aws:userid}

Choose Review policy.

For Name, enter QuicksightCreateReader, and then choose Create policy.

Refresh the list of policies by choosing the refresh icon at right.

For Search, enter QuicksightOktaFederatedPolicy. Choose the policy to enable it ( ).

If you don't want to use automatic provisioning, you can skip the following step.

To add a QuickSight user, use register-user. To add a QuickSight group, use create-group. To add users to the QuickSight group, use create-group-membership.

(Optional) For Search, enter QuicksightCreateReader. Choose the policy to enable it ( ).

Do this step if you want to provision QuickSight users automatically, rather than using the QuickSight API.

The QuicksightCreateReader policy activates automatic provisioning by allowing use of the quicksight:CreateReader action. Doing this grants dashboard subscriber (reader-level) access to first-time users. A QuickSight administrator can later upgrade them from the QuickSight profile menu, Manage QuickSight, Manage users.

To continue attaching the IAM policy or policies, choose Next: Tags.

Choose Next: Review.

For Role name, enter QuicksightOktaFederatedRole, and choose Create role.

Verify that you completed this successfully by taking these steps:

1. Return to the main page of the IAM console at https://console.amazonaws.cn/iam/. You can use your browser's Back button.

2. Choose Roles.

3. For Search, enter Okta. Choose QuicksightOktaFederatedRole from the search results.

4. On the Summary page for the policy, examine the Permissions tab. Verify that the role has the policy or policies that you attached to it. It should have QuicksightOktaFederatedPolicy. If you chose to add the ability to create users, it should also have QuicksightCreateReader.

5. Use the icon to open each policy. Verify that the text matches what is shown in this procedure. Double-check that you added your own Amazon Web Services account number in place of the example account number 111111111111.

6. On the Trust relationships tab, verify that the Trusted entities field contains the ARN for the identity provider. You can double-check the ARN in the IAM console by opening Identity providers, Okta.

Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

Add a policy that allows Okta to display a list of IAM roles to the user. To do this, choose Policy, Create policy.

Choose JSON, then enter the following policy.

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

Choose Review Policy.

For Name, enter OktaListRolesPolicy. Then choose Create policy.

Add a user so you can provide Okta with an access key.

In the navigation pane, choose Users, Add User.

Use the following settings:

Choose Next: Permissions.

Choose Attach existing policies directly.

For Search, enter OktaListRolesPolicy, and choose OktaListRolesPolicy from the search results.

Choose Next: Tags, and then choose Next: Review.

Choose Create user. Now you can get the access key.

Download the key file by choosing Download .csv. The file contains the same access key ID and secret access key that displays on this screen. However, because Amazon doesn't display this information a second time, make sure to download the file.

Verify that you completed this step correctly by doing the following:

1. Open the IAM console, and choose Users. Search for OktaSSOUser, and open it by choosing the username from the search results.

2. On the Permissions tab, verify that the OktaListRolesPolicy is attached.

3. Use the icon to open the policy. Verify that the text matches what is shown in this procedure.

4. On the Security credentials tab, you can check the access key, although you already downloaded it. You can return to this tab to create an access key when you need a new one.

Return to your Okta dashboard. If requested to do so, sign in. If the developer console is no longer open, choose Admin to reopen it.

If you have to reopen Okta, you can return to this section by following these steps:

1. Sign in to Okta. Choose Applications.

2. Choose Amazon Account Federation - QuickSight—the application that you created at the beginning of this tutorial.

3. Choose the Sign On tab, between General and Mobile.

Scroll to Advanced Sign-On Settings.

For Identity Provider ARN (Required only for SAML IAM federation), enter the provider ARN from the previous procedure, for example:

arn:aws-cn:iam::111122223333:saml-provider/Okta

Choose Done or Save. The name of the button varies depending if you are creating or editing the application.

Choose the Provisioning tab, and at the lower part of the tab, choose Configure API Integration.

Turn on Enable API integration to display the settings.

For Access Key and Secret Key, provide the access key and secret key that you downloaded previously to a file named OktaSSOUser_credentials.csv.

Choose Test API Credentials. Look above the Enable API integration setting for a message confirming that Amazon Account Federation was verified successfully.

Choose Save.

Make sure that To App is highlighted at left, and choose Edit at right.

For Create Users, turn on the option Enable.

Choose Save.

On the Assignments tab, near Provisioning and Import, choose Assign.

Do one or more of the following to enable federated access:

For each IAM user or group, do the following:

1. Choose Assign, Role.

2. Select QuicksightOktaFederatedRole from the list of IAM roles.

3. For SAML User Roles, enable QuicksightOktaFederatedRole.

Choose Save and Go Back, and then choose Done.

Verify that you completed this step correctly by choosing the People or Groups filter at left, and checking the users or groups that you entered. If you can't complete this process because the role that you created doesn't appear in the list, return to the previous procedures to verify the settings.

If you are using an Okta administrator account, switch to user mode.

Sign in to your Okta Applications dashboard with a user that has been granted federated access. You should see a new application with your label, for example Amazon Account Federation - QuickSight.

Choose the application icon to launch Amazon Account Federation - QuickSight.

Open QuickSight, and choose Manage QuickSight from your profile menu.

Choose Single sign-on (IAM federation) from the navigation pane.

For Configuration, IdP URL, enter the URL that your IdP provides to authenticate users, for example https://dev-1-----0.okta.com/home/amazon_aws/0oabababababaGQei5d5/282. You can find this in your Okta app page, on the General tab, in Embed Link.

For IdP URL, enter RelayState.

Do one of the following:

For Status, choose ON.

Choose Save to keep your settings.

Locate the Okta application’s single sign-on (IAM federation) URL in the metadata.xml file that you downloaded beginning of the tutorial. You can find the URL near the bottom of the file, in the element named md:SingleSignOnService. The attribute is named Location and the value ends with /sso/saml, as shown in the following example.

<md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://dev-0000001.okta.com/app/amazon_aws/abcdef2hATwiVft645d5/sso/saml"/>

Take the value of the IAM federation URL and append ?RelayState= followed by the URL of your QuickSight dashboard. The RelayState parameter relays the state (the URL) that the user was in when they were redirected to the authentication URL.

To the new IAM federation with the relay state added, append the URL of your QuickSight dashboard. The resulting URL should resemble the following.

https://dev-1-----0.okta.com/app/amazon_aws/abcdef2hATwiVft645d5/sso/saml?RelayState=https://us-west-2.quicksight.aws.amazon.com/sn/analyses/12a12a2a-121a-212a-121a-abcd12abc1ab

If the link you create doesn't open, check that you are using the most recent IAM federation URL from the metadata.xml. Also check that the username you use to sign in isn't assigned in more than one IAM federation Okta app.