Setting up Amazon Q Business with IAM Identity Center as identity provider - Amazon Q Business

Setting up Amazon Q Business with IAM Identity Center 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 AWS IAM Identity Center as your SAML 2.0-compliant identity provider (IdP). Integrating Amazon Q Business with IAM Identity Center requires that you switch between tasks on the Amazon Q Business console and the IAM Identity Center console.

Prerequisites

Before you start to integrate Amazon Q Business with IAM Identity Center, 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 an Amazon Q Business web experience.

  • Enabled an IAM Identity Center instance, provisioned at least one user, and provided each user with a valid email address. For more details, see Configure user access with the default IAM Identity Center directory.

Note

To deploy your web experience using IAM Identity Center as an identity provider, Amazon Q Business requires you to create a custom application. This is because Amazon Q Business is not an AWS managed application. However, IAM Identity Center account instances can't support custom IAM Identity Center applications. So, you need to use an IAM Identity Center organizations instance (which supports custom applications) to integrate IAM Identity Center with Amazon Q Business. For more information on IAM Identity Center instances, see IAM Identity Center capabilities.

To integrate Amazon Q Business with IAM Identity Center

  1. In the Amazon Q Business console, choose the Amazon Q Business application you want to integrate with IAM Identity Center.

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

    Image of Amazon Q Business console: Application details workarea with deploy web experience button.

  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.

    Image of Amazon Q Business console: Deploy web experience workarea with service access configuration options.

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

    Image of Amazon Q Business console: IdP details workarea with configuration details to copy.

    You will use this information later in this procedure.

  5. Then, switch to the IAM Identity Center console.

  6. From the IAM Identity Center console, from the left navigation pane, expand Application assignments and choose Applications.

    Image of IAM Identity Center console with configuration options.

  7. On the Applications page, from Customer managed, choose Add application.

    Image of IAM Identity Center console: Application details workarea with application configuration buttons.

  8. On the Select application type page, for the Setup preference, choose I have an application I want to set up.

    Image of IAM Identity Center console: Application details workarea with setup preference buttons.

  9. In the Application type section, choose SAML 2.0 and choose Next.

    Image of IAM Identity Center console: Application details workarea with application type button.

  10. On the Configure application page, in Display name enter a name for your application. Optionally, enter a description in Description.

    Image of IAM Identity Center console: Application details workarea with application type button.

  11. In the IAM Identity Center metadata section, choose Download to download the IAM Identity Center SAML metadata file. You will need this when you return to the Amazon Q Business console.

    Image of IAM Identity Center console: Configure application workarea with application name field and IAM Identity Center SAML metadata file download button.

  12. In Application properties, (if you're configuring access to the Amazon Q Business application directly from your IdP's application portal instead of using the deployed Amazon Q Business web experience), you must choose to specify the deployed experience URL from the Amazon Q Business console as the Application start URL.

  13. Scroll down to the Application metadata section, and choose Manually type your metadata values.

  14. Then, do the following:

    Then, choose Submit.

    Image of IAM Identity Center console: Application metadata workarea with Application ACS URL and Application and SAML audience URI fields and a Submit button.

  15. On the Custom SAML 2.0 application application page, scroll down to the Assigned users and groups section and choose Assign users and groups.

    Image of IAM Identity Center console: List of users and Assign users button.

  16. On the Assign users to Custom SAML 2.0 application table, select one or more users for your application and then choose Assign users to finish assigning users.

    Image of IAM Identity Center console: List of users and Assign users button.

  17. From the Details pane, choose Actions and then choose Edit attribute mappings.

    Image of IAM Identity Center console: application Details workarea, Actions drop down menu with Edit attribute mappings listed as a menu item.

  18. On the Attribute mappings for Custom SAML 2.0 application page, do the following:

    • Leave the User attribute in the application column set to the default attribute name Subject.

    • For Maps to this string value or user attribute in IAM Identity Center – Map the Subject to the email attribute, for example, ${user:email}. Make sure that the attribute you provide is included in Supported IAM Identity Center attributes.

    • Set the Format to unspecified.

      Image of IAM Identity Center console: Attribute mapping workarea with subject attribute mapped to user email attribute and format set to unspecified.

    • Choose Add new attribute mapping.

  19. Then, on the Attribute mappings for Custom SAML 2.0 application page, add another attribute mapping by completing the following steps:

    1. For User attribute in the application, enter a name for the attribute, for example, Email. Make a note of this attribute name for use later.

    2. For Maps to this string value or user attribute in IAM Identity Center – Enter an attribute or a value that you want to map to the attribute name.

      For example, you might want to map the attribute name Email with the users email attribute ${user:email}.

      Make sure that the attribute you provide is included in Supported IAM Identity Center attributes.

    3. Set the Format to unspecified.

    4. Choose Save changes.

      Image of IAM Identity Center console: New attribute mappings workarea with Add new attribute mappings button, name for the new attribute Email mapped to user email, format set to unspecified, and a Save changes button.

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

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

    Image of Amazon Q Business console: Metadata XML upload area.

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

  23. Choose Deploy.

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

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