AWS Big Data Blog
Federate Amazon QuickSight access with open-source identity provider Keycloak
Amazon QuickSight is a scalable, serverless, embeddable, machine learning (ML) powered business intelligence (BI) service built for the cloud that supports identity federation in both Standard and Enterprise editions. Organizations are working toward centralizing their identity and access strategy across all their applications, including on-premises and third-party. Many organizations use Keycloak as their identity provider (IdP) to control and manage user authentication and authorization centrally. You can enable role-based access control to make sure users get appropriate role permissions in QuickSight based on their entitlement stored in Keycloak attributes.
In this post, we walk through the steps you need to configure federated single sign-on (SSO) between QuickSight and open-source IdP Keycloak. We also demonstrate ways to to assign QuickSight roles based on Keycloak membership. Administrators can publish QuickSight applications on the Keycloak Admin console. This enables you to SSO to QuickSight using your Keycloak credentials.
Prerequisites
To complete the walkthrough, you need the following prerequisites:
- Keycloak setup with administrator access
- QuickSight account subscription
- AWS Identity and Access Management (IAM) administrator access
- Java 11
Solution overview
The walkthrough includes the following steps:
- Register a client application in Keycloak.
- Configure the application in Keycloak.
- Add Keycloak as your SAML IdP in AWS.
- Configure IAM policies.
- Configure IAM roles.
- Assign the newly created roles in IAM to users and groups in Keycloak.
Register a client application in KeyCloak
To configure the integration of an SSO application in Keycloak, you need to create a Keycloak client application.
- Sign in to your Keycloak admin dashboard.
For instructions on installing Keycloak, refer to Keycloak Downloads. For the Keycloak admin dashboard, use http://localhost:8080/. - Create a new realm by choosing Create realm on the default realm master page.
- Assign a name for this new realm. For this example, we assign the name
aws-realm
.
- When the new realm has been created, choose Clients.
- Choose Create client to create a new Keycloak application for SSO Federation to QuickSight.
Configure the application in Keycloak
Follow the steps to configure the application in Keycloak.
- Download the SAML metadata file.
- Save full code from saml-metadata.xml to your local machine.
- In the navigation pane under Clients, import the SAML metadata file.
- Choose Import client.
- Choose Browse.
- Leave the rest of the fields blank. The metadata.xml file that you import later automatically populates them.
- When imported, press Save.
- On the Clients Application Setting page, choose the recently added client.
- Update the properties of the client ID:
- Change Home URL to
/realms/aws-realm/protocol/saml/clients/amazon-qs
. - Change the IdP Initiated SSO URL to
amazon-qs
. - Change the IdP initiated SSO Relay State to
https://quicksight.thinkwithwp.com
.
- Change Home URL to
- On the Client scopes tab, choose the client ID.
- On the Scope tab, make sure the Full scope allowed toggle is set to off.
- Insert your specific host domain name where the Keycloak application resides in the following URL:
https://<your_host_domain>/realms/aws-realm/protocol/saml/descriptor
.- Download the Keycloak IdP SAML metadata file from that URL location.
You now have Keycloak installed in your local machine, a new client added, AWS federation properties updated, and the Keycloak SAML metadata downloaded for AWS use in the following section.
Add Keycloak as your SAML IdP in AWS
To configure Keycloak as your SAML IdP, complete the following steps:
- Open a new tab in your browser.
- Sign in to the IAM console in your AWS account with admin permissions.
- On the IAM console, under Access Management in the navigation pane, choose Identity providers.
- Choose Add provider.
- For Provider type, select SAML.
- For Provider name, enter
keycloak
. - For Metadata document, upload the Keycloak IdP SAML metadata XML file you downloaded and saved to your local machine earlier.
- Choose Add provider.
- Verify Keycloak has been added as an IAM IdP and copy the ARN assigned.
The ARN is used in a later step for federated users and IdP Keycloak advanced configuration.
Configure IAM policies
Create three IAM policies for mapping to three different roles with permissions in QuickSight (admin, author, and reader):
- Admin – Uses QuickSight for authoring and for performing administrative tasks such as managing users or purchasing SPICE capacity
- Author – Authors analyses and dashboards in QuickSight but doesn’t perform any administrative tasks
- Reader – Interacts with shared dashboards, but doesn’t author analyses or dashboards or perform any administrative tasks
Use the following steps to setup the QuickSight-Admin
policy. This policy grants the admin privileges in QuickSight to the federated user.
- On the IAM console, choose Policies.
- Choose Create policy.
- Choose JSON and replace the existing text with the code from the following table for
QuickSight-Admin
.
Policy Name JSON Text QuickSight-Admin
QuickSight-Author
QuickSight-Reader
- Choose Review policy.
- For Name, enter
QuickSight-Admin
. - Choose Create policy.
- Repeat the steps for
QuickSight-Reader
andQuickSight-Author
.
Configure IAM roles
Create the roles that your Keycloak users assume when federating into QuickSight. Use the following steps to set up the admin role:
- On the IAM console, choose Roles in the navigation pane.
- Choose Create role.
- For Select type of trusted entity, choose SAML 2.0 federation.
- For SAML provider, choose the IdP you created earlier (
keycloak
). - Select Allow programmatic and AWS Management Console access.
- Choose Next: Permissions.
- Choose the
QuickSight-Admin
IAM policy you created in the previous step. - Choose Next: Name, review, and create.
- For Role name, enter
QuickSight-Admin-Role
. - For Role description, enter a description.
- Choose Create role.
- Repeat these steps to create your author and reader roles and attach the appropriate policies:
- For
QuickSight-Author-Role
, use the policyQuickSight-Author
- For
QuickSight-Reader-Role
, use the policyQuickSight-Reader
- For
With the completion of these steps, you have created an IdP in AWS, created policies, and created roles for the Keycloak IdP.
Assign the newly created roles in IAM to users and groups in Keycloak
To create a role for the client, complete the following steps:
- Log back in to the Keycloak admin console.
- Select
aws-realm
and clientamazon:webservices
. - Choose Create Role.
- Provide a comma-separated string using the ARN for the IAM role and the ARN for the Keycloak IdP, as in the following example:
arn:aws:iam:: <AWS account>:role/QuickSight-Admin-Role,arn:aws:iam::<AWS account>:saml-provider/keycloak
- Provide a comma-separated string using the ARN for the IAM role and the ARN for the Keycloak IdP, as in the following example:
- When the role has been added successfully, choose Save.
- Repeat the steps to add
QuickSight-Author-Role
andQuickSight-Reader-Role
.
Create mappers
To create a mapper for the client, complete the following steps:
- On the Client scopes tab, select the client
amazon:webservices
foraws-realm
.
- On the Mappers tab, choose Add mapper.
- Choose By configuration to generate mappers for Session Role, Session Duration, and Session Name.
- Add the values needed for the Session Role mapper:
- Name: Session Role
- Mapper type: Role list
- Friendly Name: Session Role
- Role attribute name:
https://thinkwithwp.com/SAML/Attributes/Role
- SAML Attribute NameFormat: Basic
- Add the values needed for the Session Duration mapper:
- Name: Session Duration
- Mapper Type: Hardcoded attribute
- Friendly Name: Session Duration
- SAML Attribute Name:
https://thinkwithwp.com/SAML/Attributes/SessionDuration
- SAML Attribute NameFormat: Basic
- Attribute Value: 28800
You can automatically sync user email mapping. To perform these steps, refer to Configure an automated email sync for federated SSO users to access Amazon QuickSight.
To manually add the values needed for the Session Name mapper, provide the following information:
- Name: Session Name
- Mapper Type: User Property
- Property: username
- Friendly Name: Session Name
- SAML Attribute Name:
https://thinkwithwp.com/SAML/Attributes/RoleSessionName
- SAML Attribute NameFormat: Basic
Create a sample group for Keycloak users
To create groups and users for the Keycloak IdP, complete the following steps:
- Choose Group in the navigation pane.
- Create a new group named
READ_ONLY_AWS_USERS
.
- Choose the Role mapping tab and Assign role.
- Add the role created for the client.
- Choose Assign.
Create a sample user
Complete these steps to create a sample user with credentials:
- Choose Users in the navigation pane.
- Choose Create new user.
- Create a sample user, such as John.
- Set the credentials for the created user.
- Add the sample user created in earlier to the group
READ_ONLY_AWS_USERS
.
You now have a Keycloak role for the realm and client, and Keycloak mappers, groups, and users in your groups.
Test the application
Let’s invoke the application you have created to seamlessly sign in to QuickSight using the following URL. Make sure you enter your domain for Keycloak.
http://<your domain>/realms/aws-realm/protocol/saml/clients/amazon-qs
When prompted for your user ID and password, enter the credentials that you created earlier.
Keycloak successfully validates the credentials and federates access to the QuickSight console by assuming the role.
Conclusion
In this post, we provided step-by-step instructions to configure federated SSO between Keycloak IdP and QuickSight. We also discussed how to create new roles and map users and groups in Keycloak to IAM for secure access to QuickSight.
If you have any questions or feedback, please leave a comment.
About the Authors
Ayah Chamseddin is a Sr. Engagement Manager at AWS. She has a deep understanding of cloud technologies and has successfully overseen and lead strategic projects, partnering with clients to define business objectives, develop implementation strategies, and drive the successful delivery of solutions.
Vamsi Bhadriraju is a Data Architect at AWS. He works closely with enterprise customers to build data lakes and analytical applications on the AWS Cloud.
Srikanth Baheti is a Specialized World Wide Principal Solutions Architect for Amazon QuickSight. He started his career as a consultant and worked for multiple private and government organizations. Later he worked for PerkinElmer Health and Sciences & eResearch Technology Inc, where he was responsible for designing and developing high traffic web applications, highly scalable and maintainable data pipelines for reporting platforms using AWS services and Serverless computing.
Raji Sivasubramaniam is a Sr. Solutions Architect at AWS, focusing on Analytics. Raji is specialized in architecting end-to-end Enterprise Data Management, Business Intelligence and Analytics solutions for Fortune 500 and Fortune 100 companies across the globe. She has in-depth experience in integrated healthcare data and analytics with wide variety of healthcare datasets including managed market, physician targeting and patient analytics.