Configuring email syncing for federated users in Amazon QuickSight - Amazon QuickSight

Configuring email syncing for federated users in Amazon QuickSight

 Applies to: Enterprise Edition 
   Intended audience: System administrators and Amazon QuickSight administrators 

In Amazon QuickSight Enterprise edition, as an administrator you can restrict new users from using personal email addresses when provisioning through their identity provider (IdP) directly to QuickSight. QuickSight then uses the preconfigured email addresses passed through the IdP when provisioning new users to your account. For example, you can make it so that only corporate-assigned email addresses are used when users are provisioned to your QuickSight account through your IdP.

Note

Make sure that your users are federating directly to QuickSight through their IdP. Federating to the AWS Console through their IdP and then clicking into QuickSight results in an error and they won't be able to access QuickSight.

When you configure email syncing for federated users in QuickSight, users who log in to your QuickSight account for the first time have preassigned email addresses. These are used to register their accounts. This approach allows users to bypass manually entering an email address. It also ensures that users can't use an email address that might differ from the email address prescribed by you, the administrator.

QuickSight supports provisioning through an IdP that supports SAML or OpenID Connect (OIDC) authentication. To configure email addresses for new users when provisioning through an IdP, you update the trust relationship for the IAM role that they use with AssumeRoleWithSAML or AssumeRoleWithWebIdentity. Then you add a SAML attribute or OIDC token in their IdP. Last, you turn on email syncing for federated users in QuickSight.

The following procedures describe these steps in detail.

Step 1: Update the trust relationship for the IAM role with AssumeRoleWithSAML or AssumeRoleWithWebIdentity

You can configure email addresses for your users to use when provisioning through your IdP to QuickSight. To do this, add the sts:TagSession action to the trust relationship for the IAM role that you use with AssumeRoleWithSAML or AssumeRoleWithWebIdentity. By doing this, you can pass in principal tags when users assume the role.

The following example illustrates an updated IAM role where the IdP is Okta. To use this example, update the Federated Amazon Resource Name (ARN) with the ARN for your service provider. You can replace items in red with your AWS and IdP service-specific information.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::account-id:saml-provider/Okta" }, "Action": "sts:AssumeRoleWithSAML", "Condition": { "StringEquals": { "SAML:aud": "https://signin.aws.amazon.com/saml" } } }, { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::account-id:saml-provider/Okta" }, "Action": "sts:TagSession", "Condition": { "StringLike": { "aws:RequestTag/Email": "*" } } } ] }

Step 2: Add a SAML attribute or OIDC token for the IAM principal tag in your IdP

After you update the trust relationship for the IAM role as describe preceding, add a SAML attribute or OIDC token for the IAM Principal tag in your IdP.

The following examples illustrate a SAML attribute and an OIDC token. To use these examples, replace the email address with a variable in your IdP that points to a user's email address. You can replace items highlighted in red with your information.

  • SAML attribute: The following example illustrates a SAML attribute.

    <Attribute Name="https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email"><AttributeValue>john.doe@example.com</AttributeValue></Attribute>
    Note

    If you're using Okta as your IdP, make sure to turn on a feature flag in your Okta account to use SAML. For more information, see Okta and AWS Partner to Simplify Access Via Session Tags on the Okta blog.

  • OIDC token: The following example illustrates an OIDC token example.

    "https://aws.amazon.com/tags": {"principal_tags": {"Email": ["john.doe@example.com"]

Step 3: Turn on email syncing for federated users in QuickSight

As described preceding, update the trust relationship for the IAM role and add a SAML attribute or OIDC token for the IAM Principal tag in your IdP. Then turn on email syncing for federated users in QuickSight as described in the following procedure.

To turn on email syncing for federated users

  1. From any page in QuickSight, choose your user name at top right, and then choose Manage QuickSight.

  2. Choose Single sign-on (SSO) in the menu at left.

  3. On the Service Provider Initiated SSO page, for Email Syncing for Federated Users, choose ON.

    When email syncing for federated users is on, QuickSight uses the email addresses that you configured in steps 1 and 2 when provisioning new users to your account. Users can't enter their own email addresses.

    When email syncing for federated users is off, QuickSight asks users to input their email address manually when provisioning new users to your account. They can use any email addresses that they want.