Setting up Amazon Q Business with Okta 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 integrate Amazon Q Business with Okta as your SAML 2.0-compliant identity provider (IdP). Integrating Amazon Q Business with Okta requires that you switch between tasks on the Amazon Q Business console and the Okta admin console.
Prerequisites
Before you start to integrate Amazon Q Business with Okta, 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 Okta account, added at least one user, assigned users to their groups, and provided each user with a valid email address. For more information, see Manage users
on the Okta Help Center.
To integrate Amazon Q Business with Okta
-
In the Amazon Q Business console, choose your application for integrating with Okta.
-
On the Applications page, from Applications, choose the application you want to deploy. Then, choose Deploy web experience.
-
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.
-
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.
-
-
Then, go to the Okta admin console. In the left navigation pane, choose Applications, and then choose Create App Integration.
-
On the Create a new app integration page, choose SAML 2.0 and then choose Next.
-
On the Create SAML Integration page, for General Settings, in App name, enter a name for the application and choose Next.
-
On the Create SAML Integration page, for Configure SAML, in the SAML Settings section, do the following:
-
For the Single sign-on URL field, enter the Assertion Consumer Service(ACS) URL that you copied from the Amazon Q Business console.
-
For the Audience URI (SP Entity ID) field, enter the Audience URI (SP Entity ID that you copied from the Amazon Q Business console.
-
-
Scroll down to the Attribute Statements (optional) section, and provide the following information. This information will be used by the Amazon Q Business application to identify the end user's email address.
-
For the Name field, provide a name for the email attribute, for example
Email
. -
For the Name format field, leave it set to Unspecified.
-
For the Value field, provide a mapping to the attribute by selecting
user.email
from the dropdown list. -
(Optional) To add more attributes, choose Add another and provide an attribute name and a value for each user. Make sure to leave the name format set to Unspecified for each user.
-
Choose Next, and then choose Finish.
-
-
From your Okta app page, select the Assignments tab.
-
Select Assign. To assign users to your Okta app, choose between Assign to People and Assign to Groups.
-
To finish assigning users, choose Done.
-
Go back to the Okta app Settings page, and select the Sign-on tab.
-
In the Metadata details section, to copy the metadata file XML file and save it in
.xml
format, choose Copy.Note
You can also navigate to the metadata URL and copy the network response payload and paste it in a file that you save in
.xml
format.For more information, see Create SAML app integrations
on the Okta Help Center website. -
Go back to the Amazon Q Business console, and make sure you're on the Deploy web experience page.
-
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.
-
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.
-
-
Choose Deploy.
-
Once deployment finishes, a URL should appear on your Amazon Q Business application page under Deployed URL.
-
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.