Build private and secure enterprise generative AI applications with Amazon Q Business using IAM Federation

Amazon Q Business is a conversational assistant powered by generative artificial intelligence (AI) that enhances workforce productivity by answering questions and completing tasks based on information in your enterprise systems, which each user is authorized to access. In an earlier post, we discussed how you can build private and secure enterprise generative AI applications with Amazon Q Business and AWS IAM Identity Center. If you want to use Amazon Q Business to build enterprise generative AI applications, and have yet to adopt organization-wide use of AWS IAM Identity Center, you can use Amazon Q Business IAM Federation to directly manage user access to Amazon Q Business applications from your enterprise identity provider (IdP), such as Okta or Ping Identity. Amazon Q Business IAM Federation uses Federation with IAM and doesn’t require the use of IAM Identity Center.

AWS recommends using AWS Identity Center if you have a large number of users in order to achieve a seamless user access management experience for multiple Amazon Q Business applications across many AWS accounts in AWS Organizations. You can use federated groups to define access control, and a user is charged only one time for their highest tier of Amazon Q Business subscription. Although Amazon Q Business IAM Federation enables you to build private and secure generative AI applications, without requiring the use of IAM Identity Center, it is relatively constrained with no support for federated groups, and limits the ability to charge a user only one time for their highest tier of Amazon Q Business subscription to Amazon Q Business applications sharing SAML identity provider or OIDC identity provider in a single AWS accouGnt.

This post shows how you can use Amazon Q Business IAM Federation for user access management of your Amazon Q Business applications.

Solution overview

To implement this solution, you create an IAM identity provider for SAML or IAM identity provider for OIDC based on your IdP application integration. When creating an Amazon Q Business application, you choose and configure the corresponding IAM identity provider.

When responding to requests by an authenticated user, the Amazon Q Business application uses the IAM identity provider configuration to validate the user identity. The application can respond securely and confidentially by enforcing access control lists (ACLs) to generate responses from only the enterprise content the user is authorized to access.

We use the same example from Build private and secure enterprise generative AI apps with Amazon Q Business and AWS IAM Identity Center—a generative AI employee assistant built with Amazon Q Business—to demonstrate how to set it up using IAM Federation to only respond using enterprise content that each employee has permissions to access. Thus, the employees are able to converse securely and privately with this assistant.

Architecture

Amazon Q Business IAM Federation requires federating the user identities provisioned in your enterprise IdP such as Okta or Ping Identity account using Federation with IAM. This involves a onetime setup of creating a SAML or OIDC application integration in your IdP account, and then creating a corresponding SAML identity provider or an OIDC identity provider in AWS IAM. This SAML or OIDC IAM identity provider is required for you to create an Amazon Q Business application. The IAM identity provider is used by the Amazon Q Business application to validate and trust federated identities of users authenticated by the enterprise IdP, and associate a unique identity with each user. Thus, a user is uniquely identified across all Amazon Q Business applications sharing the same SAML IAM identity provider or OIDC IAM identity provider.

The following diagram shows a high-level architecture and authentication workflow. The enterprise IdP, such as Okta or Ping Identity, is used as the access manager for an authenticated user to interact with an Amazon Q Business application using an Amazon Q web experience or a custom application using an API.

The user authentication workflow consists of the following steps:

The client application makes an authentication request to the IdP on behalf of the user.
The IdP responds with identity or access tokens in OIDC mode, or a SAML assertion in SAML 2.0 mode. Amazon Q Business IAM Federation requires the enterprise IdP application integration to provide a special principal tag email attribute with its value set to the email address of the authenticated user. If user attributes such as role or location (city, state, country) are present in the SAML or OIDC assertions, Amazon Q Business will extract these attributes for personalization. These attributes are included in the identity token claims in OIDC mode, and SAML assertions in the SAML 2.0 mode.
The client application makes an AssumeRoleWithWebIdentity (OIDC mode) or AssumeRoleWithSAML (SAML mode) API call to AWS Security Token Service (AWS STS) to acquire AWS Sig V4 credentials. Email and other attributes are extracted and enforced by the Amazon Q Business application using session tags in AWS STS. The AWS Sig V4 credentials include information about the federated user.
The client application uses the credentials obtained in the previous step to make Amazon Q Business API calls on behalf of the authenticated user. The Amazon Q Business application knows the user identity based on the credential used to make the API calls, shows only the specific user’s conversation history, and enforces document ACLs. The application retrieves only those documents from the index that the user is authorized to access and are relevant to the user’s query, to be included as context when the query is sent to the underlying large language model (LLM). The application generates a response based only on enterprise content that the user is authorized to access.

How subscriptions work with Amazon Q Business IAM Federation

The way user subscriptions are handled when you use IAM Identity Center vs. IAM Federation is different.

For applications that use IAM Identity Center, AWS will de-duplicate subscriptions across all Amazon Q Business applications accounts, and charge each user only one time for their highest subscription level. De-duplication will apply only if the Amazon Q Business applications share the same organization instance of IAM Identity Center. Users subscribed to Amazon Q Business applications using IAM federation will be charged one time when they share the same SAML IAM identity provider or OIDC IAM identity provider. Amazon Q Business applications can share the same SAML IAM identity provider or OIDC IAM identity provider only if they are in the same AWS account. For example, if you use Amazon Q Business IAM Federation, and need to use Amazon Q Business applications across 3 separate AWS accounts, each AWS account will require its own SAML identity provider or OIDC identity provider to be created and used in the corresponding Amazon Q Business applications, and a user subscribed to these three Amazon Q Business applications will be charged three times. In another example, if a user is subscribed to some Amazon Q Business applications that use IAM Identity Center and others that use IAM Federation, they will be charged one time across all IAM Identity Center applications and one time per SAML IAM identity provider or OIDC IAM identity provider used by the Amazon Q Business applications using IAM Federation.

For Amazon Q Business applications using IAM Identity Center, the Amazon Q Business administrator directly assigns subscriptions for groups and users on the Amazon Q Business management console. For an Amazon Q Business application using IAM federation, the administrator chooses the default subscription tier during application creation. When an authenticated user logs in using either the Amazon Q Business application web experience or a custom application using the Amazon Q Business API, that user is automatically subscribed to the default tier.

Limitations

At the time of writing, Amazon Q Business IAM Federation has the following limitations:

Amazon Q Business doesn’t support OIDC for Google and Microsoft Entra ID.
There is no built-in mechanism to validate a user’s membership to federated groups defined in the enterprise IdP. If you’re using ACLs in your data sources with groups federated from the enterprise IdP, you can use the PutGroup API to define the federated groups in the Amazon Q Business user store. This way, the Amazon Q Business application can validate a user’s membership to the federated group and enforce the ACLs accordingly. This limitation does not apply to configurations where groups used in ACLs are defined locally within the data sources. For more information, refer to Group mapping.

Guidelines to choosing a user access mechanism

The following table summarizes the guidelines to consider when choosing a user access mechanism.

Federation Type	AWS Account Type	Amazon Q Business Subscription Billing Scope	Supported Identity Source	Other Considerations
Federated with IAM Identity Center	Multiple accounts managed by AWS Organizations	AWS organization, support for federated group-level subscriptions to Amazon Q Business applications	All identity sources supported by IAM Identity Center: IAM Identity Center directory, Active Directory, and IdP	AWS recommends this option if you have a large number of users and multiple applications, with many federated groups used to define access control and permissions.
Federated with IAM using OIDC IAM identity provider	Single, standalone account	All Amazon Q Business applications within a single standalone AWS account sharing the same OIDC IAM identity provider	IdP with OIDC application integration	This method is more straightforward to configure compared to a SAML 2.0 provider. It’s also less complex to share IdP application integrations across Amazon Q Business web experiences and custom applications using Amazon Q Business APIs.
Federated with IAM using SAML IAM identity provider	Single, standalone account	All Amazon Q Business applications within a single standalone AWS account sharing the same SAML IAM identity provider	IdP with SAML 2.0 application integration	This method is more complex to configure compared to OIDC, and requires a separate IdP application integration for each Amazon Q Business web experience. Some sharing is possible for custom applications using Amazon Q Business APIs.

Prerequisites

To implement the sample use case described in this post, you need an Okta account. This post covers workflows for both OIDC and SAML 2.0, so you can follow either one or both workflows based on your interest. You need to create application integrations for OIDC or SAML mode, and then configure the respective IAM identity providers in your AWS account, which will be required to create and configure your Amazon Q Business applications. Though you use the same Okta account and the same AWS account to create two Amazon Q Business applications one using an OIDC IAM identity provider, and the other using SAML IAM identity provider, the same user subscribed to both these Amazon Q Business applications will be charged twice, since they don’t share the underlying SAML or OIDC IAM identity providers.

Create an Amazon Q Business application with an OIDC IAM identity provider

To set up an Amazon Q Business application with an OIDC IAM identity identifier, you first configure the Okta application integration using OIDC. Then you create an IAM identity provider for that OIDC app integration, and create an Amazon Q Business application using that OIDC IAM identity provider. Lastly, you update the Okta application integration with the web experience URIs of the newly created Amazon Q Business application.

Create an Okta application integration with OIDC

Complete the following steps to create your Okta application integration with OIDC:

On the administration console of your Okta account, choose Applications, then Applications in the navigation pane.
Choose Create App Integration.
For Sign-in method, select OIDC.
For Application type, select Web Application.
Choose Next.

Give your app integration a name.
Select Authorization Code and Refresh Token for Grant Type.
Confirm that Refresh token behavior is set to Use persistent token.
For Sign-in redirect URIs, provide a placeholder value such as https://example.com/authorization-code/callback.

You update this later with the web experience URI of the Amazon Q Business application you create.

On the Assignments tab, assign access to appropriate users within your organization to your Amazon Q Business application.

In this step, you can select all users in your Okta organization, or choose select groups, such as Finance-Group if it’s defined, or select individual users.

Choose Save to save the app integration.

Your app integration will look similar to the following screenshots.

Note the values for Client ID and Client secret to use in subsequent steps.

On the Sign on tab, choose Edit next to OpenID Connect ID Token.
For Issuer, note the Okta URL.
Choose Cancel.

In the navigation pane, choose Security and then API.
Under API, Authorization Servers, choose default.
On the Claims tab, choose Add Claim.
For Name, enter https://aws.amazon.com/tags.
For Include in token type, select ID Token.
For Value, enter {"principal_tags": {"Email": {user.email}}}.
Choose Create.

The claim will look similar to the following screenshot. It is a best practice to use a custom authorization server. However, because this is an illustration, we use the default authorization server.

Set up an IAM identity provider for OIDC

To set up an IAM identity provider for OIDC, complete the following steps:

On the IAM console, choose Identity providers in the navigation pane.
Choose Add provider.
For Provider type, select OpenID Connect.
For Provider URL, enter the Okta URL you copied earlier, followed by /oauth2/default.
For Audience, enter the client ID you copied earlier.
Choose Add provider.

Create an Amazon Q Business application with the OIDC IAM identity provider

Complete the following steps to create an Amazon Q Business application with the OIDC IdP:

On the Amazon Q Business console, choose Create application.
Give the application a name.
For Access management method, select AWS IAM Identity provider.
For Choose an Identity provider type, select OpenID Connect (OIDC).
For Select Identity Provider, choose the IdP you created.
For Client ID, enter the client ID of the Okta application integration you copied earlier.
Leave the remaining settings as default and choose Create.

In the Select retriever step, unless you want to change the retriever type or the index type, choose Next.
For now, select Next on the Connect data sources We configure the data source later.

On the Manage access page, in Default subscription settings, Subscription Tier of Q Business Pro is selected by default. This means that when an authenticated user starts using the Amazon Q Business application, they will automatically get subscribed as Amazon Q Business Pro. The Amazon Q Business administrator can change the subscription tier for a user at any time.

In Web experience settings uncheck Create web experience. Choose Done.
On the Amazon Q Business Applications page, choose the application you just created to view the details.
In the Application Details page, note the Application ID.
In a new tab of your web browser open the management console for AWS Secrets Manager. Choose Store a new secret.
For Choose secret type choose Other type of secret. For Key/value pairs, enter client_secret as key and enter the client secret you copied from the Okta application integration as value. Choose Next.
For Configure secret give a Secret name.
For Configure rotation, unless you want to make any changes, accept the defaults, and choose Next.
For Review, review the secret you just stored, and choose Store.
On AWS Secrets Manager, Secrets page choose the secret you just created. Note the Secret name and Secret ARN.
Follow the instructions on IAM role for an Amazon Q web experience using IAM Federation to create Web experience IAM role, and Secret Manager Role. You will require the Amazon Q Business Application ID, Secret name and Secret ARN you copied earlier.
Open the Application Details for your Amazon Q Business application. Choose Edit.
For Update application, there is no need to make changes. Choose Update.
For Update retriever, there is no need to make changes. Choose Next.
For Connect data sources, there is no need to make changes. Choose Next.
For Update access, select Create web experience.
For Service role name select the web experience IAM role you created earlier.
For AWS Secrets Manager secret, select the secret you stored earlier.
For Web Experience to use Secrets: Service role name, select the Secret Manager Role you created earlier.
Choose Update.
On the Amazon Q Business Applications page, choose the application you just updated to view the details.
Note the value for Deployed URL.

Before you can use the web experience to interact with the Amazon Q Business application you just created, you need to update the Okta application integration with the redirect URL of the web experience.

Open the Okta administration console, then open the Okta application integration you created earlier.
On the General tab, choose Edit next to General Settings.
For Sign-in redirect URIs, replace the placeholder https://example.com/ with the value for Deployed URL of your web experience. Make sure the authorization-code/callback suffix is not deleted. The full URL should look like https://your_deployed_url/authorization-code/callback.
Choose Save.

Create an Amazon Q Business application with a SAML 2.0 IAM identity provider

The process to set up an Amazon Q Business application with a SAML 2.0 IAM identity provider is similar to creating an application using OIDC. You first configure an Okta application integration using SAML 2.0. Then you create an IAM identity provider for that SAML 2.0 app integration, and create an Amazon Q Business application using the SAML 2.0 IAM identity provider. Lastly, you update the Okta application integration with the web experience URIs of the newly created Amazon Q Business application.

Create an Okta application integration with SAML 2.0

Complete the following steps to create your Okta application integration with SAML 2.0:

On the administration console of your Okta account, choose Applications, then Applications in the navigation pane.
Choose Create App Integration.
For Sign-in method, select SAML 2.0.
Choose Next.

On the General Settings page, enter an app name and choose Next.

This will open the Create SAML Integration page.

For Single sign-on URL, enter a placeholder URL such as https://example.com/saml and deselect Use this for Recipient URL and Destination URL.
For Recipient URL, enter https://signin.aws.amazon.com/saml.
For Destination URL, enter the placeholder https://example.com/saml.
For Audience URL (SP Entity ID), enter https://signin.aws.amazon.com/saml.
For Name ID format, choose Persistent.
Choose Next and then Finish.

The placeholder values of https://example.com will need to be updated with the deployment URL of the Amazon Q Business web experience, which you create in subsequent steps.

On the Sign On tab of the app integration you just created, note the value for Metadata URL.

Open the URL in your web browser, and save it on your local computer.

The metadata will be required in subsequent steps.

Set up an IAM identity provider for SAML 2.0

To set up an IAM IdP for SAML 2.0, complete the following steps:

On the IAM console, choose Identity providers in the navigation pane.
Choose Add provider.
For Provider type, select SAML.
Enter a provider name.
For Metadata document, choose Choose file and upload the metadata document you saved earlier.
Choose Add provider.

From the list of identity providers, choose the identity provider you just created.
Note the values for ARN, Issuer URL, and SSO service location to use in subsequent steps.

Create an Amazon Q Business application with the SAML 2.0 IAM identity provider

Complete the following steps to create an Amazon Q Business application with the SAML 2.0 IAM identity provider:

On the Amazon Q Business console, choose Create application.
Give the application a name.
For Access management method, select AWS IAM Identity provider.
For Choose an Identity provider type, select SAML.
For Select Identity Provider, choose the IdP you created.
Leave the remaining settings as default and choose Create.

In the Select retriever step, unless you want to change the retriever type or the index type, choose Next.
For now, choose Next on the Connect data sources We will configure the data source later.

For Web experience settings, uncheck Create web experience. Choose Done.
On the Amazon Q Business Applications page, choose the application you just created.
In the Application Details page, note the Application ID.
Follow the instructions on IAM role for an Amazon Q web experience using IAM Federation to create Web experience IAM role. You will require the Amazon Q Business Application ID you copied earlier.
Open the Application Details for your Amazon Q Business application. Choose Edit.
For Update application, there is no need to make changes. Choose Update.
For Update retriever, there is no need to make changes. Choose Next.
For Connect data sources, there is no need to make changes. Choose Next.
For Update access, select Create web experience.
For this post, we continue with the default setting.
For Authentication URL, enter the value for SSO service location that you copied earlier.
Choose Update.
On the Amazon Q Business Applications page, choose the application you just updated to view the details.
Note the values for Deployed URL and Web experience IAM role ARN to use in subsequent steps.

Open the Okta administration console, then open the Okta application integration you created earlier.
On the General tab, choose Edit next to SAML Settings.
For Single sign-on URL and Destination URL, replace the placeholder https://example.com/ with the value for Deployed URL of your web experience. Make sure the /saml suffix isn’t deleted.
Choose Save.

On the Edit SAML Integration page, in the Attribute Statements (optional) section, add attribute statements as listed in the following table.

This step is not optional and these attributes are used by the Amazon Q Business application to determine the identity of the user, so be sure to confirm their correctness.

Name	Name format	Value
`https://aws.amazon.com/SAML/Attributes/PrincipalTag:Email`	Unspecified	`user.email`
`https://aws.amazon.com/SAML/Attributes/Role`	Unspecified	`<Web experience IAM role ARN>,<identity-provider-arn>`
`https://aws.amazon.com/SAML/Attributes/RoleSessionName`	Unspecified	`user.email`

For the value of the https://aws.amazon.com/SAML/Attributes/Role attribute, you need to concatenate the web experience IAM role ARN and IdP ARN you copied earlier with a comma between them, without spaces or any other characters.

Choose Next and Finish.
On the Assignments tab, assign users who can access the app integration you just created.

This step controls access to appropriate users within your organization to your Amazon Q Business application. In this step, you can enable self-service so that all users in your Okta organization, or choose select groups, such as Finance-Group if it’s defined, or select individual users.

Set up the data source

Whether you created the Amazon Q Business application using an OIDC IAM identity provider or SAML 2.0 IAM identity provider, the procedure to create a data source remains the same. For this post, we set up a data source for Atlassian Confluence. The following steps show how to configure the data source for the Confluence environment. For more details on how to set up a Confluence data source, refer to Connecting Confluence (Cloud) to Amazon Q Business.

On the Amazon Q Business Application details page, choose Add data source.

On the Add data source page, choose Confluence.

For Data source name, enter a name.
For Source, select Confluence Cloud and enter the Confluence URL.

For Authentication, select Basic authentication and enter the Secrets Manager secret.
For IAM role, select Create a new service role.
Leave the remaining settings as default.

For Sync scope, select the appropriate content to sync.
Under Space and regex patterns, provide the Confluence spaces to be included.
For Sync mode, select Full sync.
For Sync run schedule, choose Run on demand.
Choose Add data source.

After the data source creation is complete, choose Sync now to start the data source sync.

Wait until the sync is complete before logging in to the web experience to start querying.

Employee AI assistant use case

To illustrate how you can build a secure and private generative AI assistant for your employees using Amazon Q Business applications, let’s take a sample use case of an employee AI assistant in an enterprise corporation. Two new employees, Mateo Jackson and Mary Major, have joined the company on two different projects, and have finished their employee orientation. They have been given corporate laptops, and their accounts are provisioned in the corporate IdP. They have been told to get help from the employee AI assistant for any questions related to their new team member activities and their benefits.

The company uses Confluence to manage their enterprise content. The sample Amazon Q application used to run the scenarios for this post is configured with a data source using the built-in connector for Confluence to index the enterprise Confluence spaces used by employees. The example uses three Confluence spaces with the following permissions:

HR Space – All employees, including Mateo and Mary
AnyOrgApp Project Space – Employees assigned to the project, including Mateo
ACME Project Space – Employees assigned to the project, including Mary

Let’s look at how Mateo and Mary experience their employee AI assistant.

Both are provided with the URL of the employee AI assistant web experience. They use the URL and sign in to the IdP from the browsers of their laptops. Mateo and Mary both want to know about their new team member activities and their fellow team members. They ask the same questions to the employee AI assistant but get different responses, because each has access to separate projects. In the following screenshots, the browser window on the left is for Mateo Jackson and the one on the right is for Mary Major. Mateo gets information about the AnyOrgApp project and Mary gets information about the ACME project.

Mateo chooses Sources under the question about team members to take a closer look at the team member information, and Mary chooses Sources under the question for the new team member checklist. The following screenshots show their updated views.

Mateo and Mary want to find out more about the benefits their new job offers and how the benefits are applicable to their personal and family situations.

The following screenshot shows that Mary asks the employee AI assistant questions about her benefits and eligibility.

Mary can also refer to the source documents.

The following screenshot shows that Mateo asks the employee AI assistant different questions about his eligibility.

Mateo looks at the following source documents.

Both Mary and Mateo first want to know their eligibility for benefits. But after that, they have different questions to ask. Even though the benefits-related documents are accessible by both Mary and Mateo, their conversations with the employee AI assistant are private and personal. The assurance that their conversation history is private and can’t be seen by any other user is critical for the success of a generative AI employee productivity assistant.

Clean up

If you created a new Amazon Q Business application to try out the integration with IAM federation, and don’t plan to use it further, you can unsubscribe, remove automatically subscribed users from the application, and delete it so that your AWS account doesn’t accumulate costs.

To unsubscribe and remove users, go to the application details page and choose Manage subscriptions.

Select all the users, choose Remove to remove subscriptions, and choose Done.

To delete the application after removing the users, return to the application details page and choose Delete.

Conclusion

For enterprise generative AI assistants such as the one shown in this post to be successful, they must respect access control as well as assure the privacy and confidentiality of every employee. Amazon Q Business achieves this by integrating with IAM Identity Center or with IAM Federation to provide a solution that authenticates each user and validates the user identity at each step to enforce access control along with privacy and confidentiality.

In this post, we showed how Amazon Q Business IAM Federation uses SAML 2.0 and OIDC IAM identity providers to uniquely identify a user authenticated by the enterprise IdP, and then that user identity is used to match up document ACLs set up in the data source. At query time, Amazon Q Business responds to a user query utilizing only those documents that the user is authorized to access. This functionality is similar to that achieved by the integration of Amazon Q Business with IAM Identity Center we saw in an earlier post. Additionally, we also provided the guidelines to consider when choosing a user access mechanism.

To learn more, refer to Amazon Q Business, now generally available, helps boost workforce productivity with generative AI and the Amazon Q Business User Guide.

About the authors

Abhinav Jawadekar is a Principal Solutions Architect in the Amazon Q Business service team at AWS. Abhinav works with AWS customers and partners to help them build generative AI solutions on AWS.

Venky Nagapudi is a Senior Manager of Product Management for Q Business, Amazon Comprehend and Amazon Translate. His focus areas on Q Business include user identity management, and using offline intelligence from documents to improve Q Business accuracy and helpfulness.