Setting up Amazon Q Business with Microsoft Entra ID as identity provider

Important

Starting April 30, 2024, all new applications will need to use IAM Identity Center directly to manage user access. No new applications can be created using the legacy identity management flow. All existing Amazon Q Business applications using legacy identity management will need to migrate to using IAM Identity Center for user management by July 29, 2024. We recommend you integrate any new application you're creating directly with IAM Identity Center.

The following steps show how to set up Amazon Q Business with Microsoft Entra ID (formerly Azure Active Directory) as your SAML 2.0-compliant identity provider. Integrating Amazon Q Business with Entra ID requires that you switch between tasks on the Amazon Q Business console and in the Entra ID portal.

Prerequisites

Before you start to integrate Amazon Q Business with Entra ID, make sure that you have completed the following tasks:

• Created an Amazon Q Business application, selected a retriever, added your desired data sources, and previewed Amazon Q Business web experience.

• Created an Entra ID instance, provisioned at least one user, and provided each user with a valid email address.

To integrate Amazon Q Business with Entra ID

1. In the Amazon Q Business console, choose the Amazon Q Business application you want to integrate with Entra ID.

2. On the Applications page, from Applications, choose the application you want to deploy. Then, choose Deploy web experience.

   

3. On the Deploy web experience page, for Service access, choose to Create a use a new service role or Use an existing service role. If you choose to create a new service role, Amazon Q Business, will automatically create a name for it.

   

4. In the Configure your Identity provider section, do the following:

   • Copy the Assertion consumer service(ACS) URL displayed on the console to a text editor of your choice

   • Copy the Audience URI (SP EntityID) displayed on the console to a text editor of your choice.

   

   You will use this information later in this procedure.

5. Then, switch to the Entra ID portal. In the left navigation pane, choose Enterprise applications, and then choose Add.

   

6. On the All applications page, choose New application.

   

7. In the Browse Microsoft Entra Gallery page, choose Create your own application.

   

8. Enter a name for your application, choose Integrate any other application you don't find in the gallery (Non gallery), and choose Create. It might take a few minutes for your application to be provisioned.

   

9. On the Application overview page, in the Getting started section, choose Set up single sign on.

   

10. In the Select a single sign-on method pane, choose SAML.

    

11. In the Basic SAML Configuration section, choose More (three dots) and then choose Edit.

    

12. Choose Add identifier. Then enter the following information:

    • For the Identifier (Entity ID) field, enter the Audience URI (SP Entity ID) that you copied from the Amazon Q Business console.

    • Next, choose Add reply URL.

    • For the Reply URL (Assertion Consumer Service URL) field, enter the Application consumer service (ACS) URL that you copied from the Amazon Q Business console.

    • Leave the rest of the fields blank. Choose Save.

      

13. On the Set up single sign-on with SAML page, scroll down to the SAML Certificates section. Download the Federation Metadata XML file and save it in your local drive.

    

14. In the Attributes & Claims section, choose More (three dots) and then choose Edit.

    

15. In the Attributes & Claims page, choose Unique User Identifier (Name ID).

    

16. In the Manage claim page, expand Choose name identifier format. For the Name identifier format field, select Unspecified. Choose Save.

    

17. In the Attributes & Claims page, choose Add new claim.

    

18. For the Name field, enter Email.

19. Expand Choose name format.

    1. For the Name format field, select Unspecified.

    2. Make sure that the Source is set to Attribute.

    3. For the Source attribute field, choose the drop-down arrow and select user.mail.

    4. Choose Save.

       

20. Go back to your application page. In the left navigation pane of your application page, choose Users and groups.

21. In the Users table, select the user that you created earlier. To finish assigning users, choose Assign. Continue with the next steps.

    1. If you do not see the user you want to add to your application, choose + Add user/group.

    2. In the Add Assignment page, choose None Selected.

    3. In the right pane, select the user or search for the user in the search bar and then select the user.

    4. Choose Select and then choose Assign.

22. In the Users and groups page, choose the user name. On the user page, verify that the User principal name and Identities fields are populated.

23. Go back to the Amazon Q Business console, and make sure you're on the Deploy web experience page.

24. Scroll down to the Provide metadata from your IdP section. To upload the metadata XML file that you saved in your previous steps, choose Import from XML.

    

25. In the Configure user and group mapping section, do the following:

    • For Email attribute of SAML assertion – Enter the attribute name that you provided in the Entra ID console. For example, Email could be an attribute name.

      

      Note

      Make sure there are no spaces at the end of Email.

    • For User group field attribute of SAML assertion - optional – Enter an optional user group attribute.

26. Choose Deploy.

27. Once deployment finishes, a URL should appear on your Amazon Q Business application page under Deployed URL.

28. Choose the URL to open your Amazon Q Business web experience and enter credentials for a user that has access to the web experience.

    If you encounter HTTP status code 403 (Forbidden) errors , see Troubleshooting Amazon Q Business and identity provider integration.