Amazon QuickSight Enterprise edition can integrate with your existing Microsoft Active Directory (AD), providing federated access using Security Assertion Markup Language (SAML) to dashboards. Using existing identities from Active Directory eliminates the need to create and manage separate user identities in AWS Identity Access Management (IAM). Federated users assume an IAM role when access is requested through an identity provider (IdP) such as Active Directory Federation Service (AD FS) based on AD group membership. Although, you can connect AD to QuickSight using AWS Directory Service, this blog focuses on federated logon to QuickSight Dashboards.

With identity federation, your users get one-click access to Amazon QuickSight applications using their existing identity credentials. You also have the security benefit of identity authentication by your IdP. You can control which users have access to QuickSight using your existing IdP. Refer to Using identity federation and single sign-on (SSO) with Amazon QuickSight for more information.

In this post, we demonstrate how you can use a corporate email address as an authentication option for signing in to QuickSight. This post assumes you have an existing Microsoft Active Directory Federation Services (ADFS) configured in your environment.

Solution overview

While connecting to QuickSight from an IdP, your users initiate the sign-in process from the IdP portal. After the users are authenticated, they are automatically signed in to QuickSight. After QuickSight checks that they are authorized, your users can access QuickSight.

The following diagram shows an authentication flow between QuickSight and a third-party IdP. In this example, the administrator has set up a sign-in page to access QuickSight. When a user signs in, the sign-in page posts a request to a federation service that complies with SAML 2.0. The end-user initiates authentication from the sign-in page of the IdP. For more information about the authentication flow, see Initiating sign-on from the identity provider (IdP).

The solution consists of the following high-level steps:

1. Create an identity provider.
2. Create IAM policies.
3. Create IAM roles.
4. Configure AD groups and users.
5. Create a relying party trust.
6. Configure claim rules.
7. Configure QuickSight single sign-on (SSO).
8. Configure the relay state URL for QuickStart.

Prerequisites

The following are the prerequisites to build the solution explained in this post:

• An existing or newly deployed AD FS environment.
• An AD user with permissions to manage AD FS and AD group membership.
• An IAM user with permissions to create IAM policies and roles, and administer QuickSight.
• The metadata document from your IdP. To download it, refer to Federation Metadata Explorer.

Create an identity provider

To add your IdP, complete the following steps:

1. On the IAM console, choose Identity providers in the navigation pane.
2. Choose Add provider.
3. For Provider type¸ select SAML.
4. For Provider name, enter a name (for example, QuickSight\_Federation).
5. For Metadata document, upload the metadata document you downloaded as a prerequisite.
6. Choose Add provider.
7. Copy the ARN of this provider to use in a later step.

Create IAM policies

In this step, you create IAM policies that allow users to access QuickSight only after federating their identities. To provide access to QuickSight and also the ability to create QuickSight admins, authors (standard users), and readers, use the following policy examples.

The following code is the author policy:

{ "Statement": [ { "Action": [ "quicksight:CreateUser" ], "Effect": "Allow", "Resource": [ "*" ] } ], "Version": "2012-10-17"}

The following code is the reader policy:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow","Action": "quicksight:CreateReader", "Resource": "*" } ] }

The following code is the admin policy:

{ "Statement": [ { "Action": [ "quicksight:CreateAdmin" ], "Effect": "Allow", "Resource": [ "*" ] } ], "Version": "2012-10-17"}

Create IAM roles

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. Make sure the IAM role names start with ADFS-.

1. On the IAM console, choose Roles in the navigation pane.
2. Choose Create new role.
3. For Trusted entity type, select SAML 2.0 federation.
4. Choose the SAML IdP you created earlier.
5. Select Allow programmatic and AWS Management Console access.
6. Choose Next.
   
7. Choose the admin policy you created, then choose Next.
8. For Name, enter ADFS-ACCOUNTID-QSAdmin.
9. Choose Create.
10. On the Trust relationships tab, edit the trust relationships as follows so you can pass principal tags when users assume the role (provide your account ID and IdP):

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

11. Repeat this process for the role ADFS-ACCOUNTID-QSAuthor and attach the author IAM policy.
12. Repeat this process for the role ADFS-ACCOUNTID-QSReader and attach the reader IAM policy.

Configure AD groups and users

Now you need to create AD groups that determine the permissions to sign in to AWS. Create an AD security group for each of the three roles you created earlier. Note that the group name should follow same format as your IAM role names.

One approach for creating the AD groups that uniquely identify the IAM role mapping is by selecting a common group naming convention. For example, your AD groups would start with an identifier, for example AWS-, which will distinguish your AWS groups from others within the organization. Next, include the 12-digit AWS account number. Finally, add the matching role name within the AWS account. You should do this for each role and corresponding AWS account you wish to support with federated access. The following screenshot shows an example of the naming convention we use in this post.

Later in this post, we create a rule to pick up AD groups starting with AWS-, the rule will remove AWS-ACCOUNTID- from AD groups name to match the respective IAM role, which is why we use this naming convention here.

Users in Active Directory can subsequently be added to the groups, providing the ability to assume access to the corresponding roles in AWS. You can add AD users to the respective groups based on your business permissions model. Note that each user must have an email address configured in Active Directory.

Create a relying party trust

To add a relying party trust, complete the following steps:

1. Open the AD FS Management Console.
2. Choose (right-click) Relying Party Trusts, then choose Add Relying Party Trust.
   
3. Choose Claims aware, then choose Start.
4. Select Import data about the relying party published online or on a local network.
5. For Federation metadata address, enter https://signin.aws.amazon.com/static/saml-metadata.xml.
6. Choose Next.
   
7. Enter a descriptive display name, for example Amazon QuickSight Federation, then choose Next.
8. Choose your access control policy (for this post, Permit everyone), then choose Next.
   
9. In the Ready to Add Trust section, choose Next.
   
10. Leave the defaults, then choose Close.

Configure claim rules

In this section, you create claim rules that identify accounts, set LDAP attributes, get the AD groups, and match them to the roles created earlier. Complete the following steps to create the claim rules for NameId, RoleSessionName, Get AD Groups, Roles, and (optionally) Session Duration:

1. Select the relying party trust you just created, then choose Edit Claim Issuance Policy.
2. Add a rule called NameId with the following parameters:
   1. For Claim rule template, choose Transform an Incoming Claim.
   2. For Claim rule name, enter NameId
   3. For Incoming claim type, choose Windows account name.
   4. For Outgoing claim type, choose Name ID.
   5. For Outgoing name ID format, choose Persistent Identifier.
   6. Select Pass through all claim values.
   7. Choose Finish.
      
3. Add a rule called RoleSessionName with the following parameters:
   1. For Claim rule template, choose Send LDAP Attributes as Claims.
   2. For Claim rule name, enter RoleSessionName.
   3. For Attribute store, choose Active Directory.
   4. For LDAP Attribute, choose E-Mail-Addresses.
   5. For Outgoing claim type, enter https://aws.amazon.com/SAML/Attributes/RoleSessionName.
   6. Add another E-Mail-Addresses LDAP attribute and for Outgoing claim type, enter https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email.
   7. Choose OK.
      
4. Add a rule called Get AD Groups with the following parameters:
   1. For Claim rule template, choose Send Claims Using a Custom Rule.
   2. For Claim rule name, enter Get AD Groups
   3. For Custom Rule, enter the following code:

      c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"] => add(store = "Active Directory", types = ("http://temp/variable"), query = ";tokenGroups;{0}", param = c.Value);

   4. Choose OK.
      

5. Add a rule called Roles with the following parameters:
   1. For Claim rule template, choose Send Claims Using a Custom Rule.
   2. For Claim rule name, enter Roles
   3. For Custom Rule, enter the following code (provide your account ID and IdP):

      c:[Type == "http://temp/variable", Value =~ "(?i)^AWS-ACCOUNTID"]=> issue(Type = "https://aws.amazon.com/SAML/Attributes/Role", Value = RegExReplace(c.Value, "AWS-ACCOUNTID-", "arn:aws:iam:: ACCOUNTID:saml-provider/your-identity-provider-name,arn:aws:iam:: ACCOUNTID:role/ADFS-ACCOUNTID-"));

   4. Choose Finish.

Optionally, you can create a rule called Session Duration. This configuration determines how long a session is open and active before users are required to reauthenticate. The value is in seconds. For this post, we configure the rule for 8 hours.

5. Add a rule called Session Duration with the following parameters:
   1. For Claim rule template, choose Send Claims Using a Custom Rule.
   2. For Claim rule name, enter Session Duration.
   3. For Custom Rule, enter the following code:

      => issue(Type = "https://aws.amazon.com/SAML/Attributes/SessionDuration", Value = "28800");

   4. Choose Finish.

You should be able to see these five claim rules, as shown in the following screenshot.

6. Choose OK.
7. Run the following commands in PowerShell on your AD FS server:

Set-AdfsProperties -EnableIdPInitiatedSignonPage $trueSet-AdfsProperties -EnableRelayStateForIdpInitiatedSignOn $true

8. Stop and start the AD FS service from PowerShell:

net stop adfssrvnet start adfssrv

Configure E-mail Syncing

With QuickSight Enterprise edition integrated with an IdP, you can restrict new users from using personal email addresses. This means users can only log in to QuickSight with their on-premises configured email addresses. 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 configured in Active Directory.

QuickSight 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. 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.

To configure E-mail syncing for federated users in QuickSight, complete the following steps:

1. Log in to your QuickSight dashboard with a QuickSight administrator account.
2. Choose the profile icon.
   
3. On the drop-down menu, choose on Manage QuickSight.
4. In the navigation pane, choose Single sign-on (SSO).
5. For Email Syncing for Federated Users, select ON, then choose Enable in the pop-up window.
6. Choose Save.

Configure the relay state URL for QuickStart

To configure the relay state URL, complete the following steps (revise the input information as needed to match your environment’s configuration):

1. Use the ADFS RelayState Generator to generate your URL.
2. For IDP URL String, enter https://ADFSServerEndpoint/adfs/ls/idpinitiatedsignon.aspx.
3. For Relying Party Identifier, enter urn:amazon:webservices or https://signin.aws.amazon.com/saml.
4. For Relay State/Target App, enter your authenticated users to access. In this case, it’s https://quicksight.aws.amazon.com.
5. Choose Generate URL.
6. Copy the URL and load it in your browser.

You should be presented with a login to your IdP landing page.

Make sure the user logging in has an email address attribute configured in Active Directory. A successful login should redirect you to the QuickSight dashboard after authentication. If you’re not redirected to the QuickSight dashboard page, make sure you ran the commands listed earlier after you configured your claim rules.

Summary

In this post, we demonstrated how to configure federated identities to a QuickSight dashboard and ensure that users can only sign in with preconfigured email address in your existing Active Directory.

We’d love to hear from you. Let us know what you think in the comments section.

About the Author

Adeleke Coker is a Global Solutions Architect with AWS. He helps customers globally accelerate workload deployments and migrations at scale to AWS. In his spare time, he enjoys learning, reading, gaming and watching sport events.