Authenticate Amazon Q Business data accessors using a trusted token issuer

Since its general availability in 2024, Amazon Q Business (Amazon Q) has enabled independent software vendors (ISVs) to enhance their Software as a Service (SaaS) solutions through secure access to customers’ enterprise data by becoming Amazon Q Business data accessor. To find out more on data accessor, see this page. The data accessor now supports trusted identity propagation. With trusted token issuer (TTI) authorization support, ISVs as data accessor can integrate with Amazon Q index while maintaining enterprise-grade security standards for their software-as-a-service (SaaS) solutions.

Prior to TTI support, data accessors needed to implement authorization code flow with AWS IAM Identity Center integration when accessing the Amazon Q index. With TTI support for data accessors, ISVs can now use their own OpenID Provider to authenticate enterprise users, alleviating the need for double authentication while maintaining security standards.

In this blog post, we show you how to implement TTI authorization for data accessors, compare authentication options, and provide step-by-step guidance for both ISVs and enterprises.

Prerequisites

Before you begin, make sure you have the following requirements:

• An AWS account with administrator access
• Access to Amazon Q Business
• For ISVs:
  • An OpenID Connect (OIDC) compatible authorization server
• For enterprises:
  • Amazon Q Business administrator access
  • Permission to create trusted token issuers

Solution Overview

This solution demonstrates how to implement TTI authentication for Amazon Q Business data accessors. The following diagram illustrates the overall flow between different resources, from ISV becoming a data accessor, customer enabling ISV data accessor, to ISV accessing customer’s Amazon Q index:

Understanding Trusted Token Issuer Authentication

Trusted Token Issuer represents an advanced identity integration capability for Amazon Q. At its core, TTI is a token exchange API that propagates identity information into IAM role sessions, enabling AWS services to make authorization decisions based on the actual end user’s identity and group memberships. This mechanism allows AWS services to apply authorization and security controls based on the authenticated user context. The TTI support simplifies the identity integration process while maintaining robust security standards, making it possible for organizations to ensure that access to Amazon Q respects user-level permissions and group memberships. This enables fine-grained access control and maintains proper security governance within Amazon Q implementations.

Trusted Token Issuer authentication simplifies the identity integration process for Amazon Q by enabling the propagation of user identity information into AWS IAM role sessions. Each token exchange allows AWS services to make authorization decisions based on the authenticated user’s identity and group memberships. The TTI support streamlines the integration process while maintaining robust security standards, enabling organizations to implement appropriate access controls within their Amazon Q implementations.

Understanding Data Accessors

A data accessor is an ISV that has registered with AWS and is authorized to use their customers’ Amazon Q index for the ISV’s Large Language Model (LLM) solution. The process begins with ISV registration, where they provide configuration information including display name, business logo, and OpenID Connect (OIDC) configuration details for TTI support.

During ISV registration, providers must specify their tenantId configuration – a unique identifier for their application tenant. This identifier might be known by different names in various applications (such as Workspace ID in Slack or Domain ID in Asana) and is required for proper customer isolation in multi-tenant environments.

Amazon Q customers then add the ISV as a data accessor to their environment, granting access to their Amazon Q index based on specific permissions and data source selections. Once authorized, the ISV can query the customers’ index through API requests using their TTI authentication flow, creating a secure and controlled pathway for accessing customer data.

Implementing TTI Authentication for Amazon Q index Access

This section explains how to implement TTI authentication for accessing the Amazon Q index. The implementation involves initial setup by the customer and subsequent authentication flow implemented by data accessors for user access.

TTI provides capabilities that enable identity-enhanced IAM role sessions through Trusted Identity Propagation (TIP), allowing AWS services to make authorization decisions based on authenticated user identities and group memberships. Here’s how it works:

To enable data accessor access to a customer’s Amazon Q index through TTI, customers must perform an initial one-time setup by adding a data accessor on Amazon Q Business application. During setup, a TTI with the data accessor’s identity provider information is created in the customer’s AWS IAM Identity Center, allowing the data accessor’s identity provider to authenticate access to the customer’s Amazon Q index.

The process to set up an ISV data accessor with TTI authentication consists of the following steps:

1. The customer’s IT administrator accesses their Amazon Q Business application and creates a trusted token issuer with the ISV’s OAuth information. This returns a TrustedTokenIssuer (TTI) Amazon Resource Name (ARN).
   
2. The IT administrator creates an ISV data accessor with the TTI ARN received in Step 1.
3. Amazon Q Business confirms the provided TTI ARN with AWS IAM Identity Center and creates a data accessor application.
4. Upon successful creation of the ISV data accessor, the IT administrator receives data accessor details to share with the ISV.
5. The IT administrator provides these details to the ISV application.

Once the data accessor setup is complete in the customer’s Amazon Q environment, users can access the Amazon Q index through the ISV application by authenticating only against the data accessor’s identity provider.

The authentication flow proceeds as follows:

1. A user authenticates against the data accessor’s identity provider through the ISV application. The ISV application receives an ID token for that user, generated from the ISV’s identity provider with the same client ID registered on their data accessor.
2. The ISV application needs to use the AWS Identity and Access Management (IAM) role that they created during the data accessor onboarding process by calling AssumeRole API, then make CreateTokenWithIAM API request to the customer’s AWS IAM Identity Center with the ID token. AWS IAM Identity Center validates the ID token with the ISV’s identity provider and returns an IAM Identity Center token.
3. The ISV application requests an AssumeRole API with: IAM Identity Center token, extracted identity context, and tenantId. The tenantId is a security control jointly established between the ISV and their customer, with the customer maintaining control over how it’s used in their trust relationships. This combination facilitates secure access to the correct customer environment.
4. The ISV application calls the SearchRelevantContent API with the session credentials and receives relevant content from the customer’s Amazon Q index.

When implementing Amazon Q integration, ISVs need to consider two approaches, each with its own benefits and considerations:

TTI excels in providing a seamless user experience through single authentication on the ISV system and enables backend-only implementations for SearchRelevantContent API access without requiring direct user interaction. However, this approach requires ISVs to maintain their own OIDC authorization server, which may present implementation challenges for some organizations. Additionally, some enterprises might have concerns about ISVs having persistent ability to make API requests on behalf of their users without explicit per-session authorization.

Next Steps

For ISVs: Becoming a Data Accessor with TTI Authentication

Getting started on Amazon Q data accessor registration process with TTI authentication is straightforward. If you already have an OIDC compatible authorization server for your application’s authentication, you’re most of the way there.

To begin the registration process, you’ll need to provide the following information:

• Display name and business logo that will be displayed on AWS Management Console
• OIDC configuration details (OIDC ClientId and discovery endpoint URL)
• TenantID configuration details that specify how your application identifies different customer environments

For details, see Information to be provided to the Amazon Q Business team.

For ISVs using Amazon Cognito as their OIDC authorization server, here’s how to retrieve the required OIDC configuration details:

1. To get the OIDC ClientId:- Navigate to the Amazon Cognito console- Select your User Pool- Go to “Applications” > “App clients”- The ClientId is listed under “Client ID” for your app client
2. To get the discovery endpoint URL:- The URL follows this format:https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/openid-configuration– Replace {region} with your AWS region (e.g., us-east-1)- Replace {userPoolId} with your Cognito User Pool IDFor example, if your User Pool is in us-east-1 with ID ‘us-east-1_abcd1234’, your discovery endpoint URL would be:

   https://cognito-idp.us-east-1.amazonaws.com/us-east-1_abcd1234/.well-known/openid-configuration

Note: While this example uses Amazon Cognito, the process will vary depending on your OIDC provider. Common providers like Auth0, Okta, or custom implementations will have their own methods for accessing these configuration details.

Once registered, you can enhance your generative AI application with the powerful capabilities of Amazon Q, allowing your customers to access their enterprise knowledge base through your familiar interface. AWS provides comprehensive documentation and support to help you implement the authentication flow and API integration efficiently.

For Enterprises: Enabling TTI-authenticated Data Accessor

To enable a TTI-authenticated data accessor, your IT administrator needs to complete the following steps in the Amazon Q console:

1. Create a trusted token issuer using the ISV’s OAuth information
2. Set up the data accessor with the generated TTI ARN
3. Configure appropriate data source access permissions

This streamlined setup allows your users to access Amazon Q index through the ISV’s application using their existing ISV application credentials, alleviating the need for multiple logins while maintaining security controls over your enterprise data.

Both ISVs and enterprises benefit from AWS’s comprehensive documentation and support throughout the implementation process, facilitating a smooth and secure integration experience.

Clean up resources

To avoid unused resources, follow these steps if you no longer need the data accessor:

• Delete the data accessor:
  • On the Amazon Q Business console, choose Data accessors in the navigation pane
  • Select your data accessor and choose Delete.
• Delete the TTI:
  • On the IAM Identity Center console, choose Trusted Token Issuers in the navigation pane.
  • Select the associated issuer and choose Delete.

Conclusion

The introduction of Trusted Token Issuer (TTI) authentication for Amazon Q data accessors marks a significant advancement in how ISVs integrate with Amazon Q Business. By enabling data accessors to use their existing OIDC infrastructure, we’ve alleviated the need for double authentication while maintaining enterprise-grade security standards through TTI’s robust tenant isolation mechanisms and secure multi-tenant access controls, making sure each customer’s data remains protected within their dedicated environment. This streamlined approach not only enhances the end-user experience but also simplifies the integration process for ISVs building generative AI solutions.

In this post, we showed how to implement TTI authentication for Amazon Q data accessors. We covered the setup process for both ISVs and enterprises and demonstrated how TTI authentication simplifies the user experience while maintaining security standards.

To learn more about Amazon Q Business and data accessor integration, refer to Share your enterprise data with data accessors using Amazon Q index and Information to be provided to the Amazon Q Business team. You can also contact your AWS account team for personalized guidance. Visit the Amazon Q Business console to begin using these enhanced authentication capabilities today.

About the Authors

Takeshi Kobayashi is a Senior AI/ML Solutions Architect within the Amazon Q Business team, responsible for developing advanced AI/ML solutions for enterprise customers. With over 14 years of experience at Amazon in AWS, AI/ML, and technology, Takeshi is dedicated to leveraging generative AI and AWS services to build innovative solutions that address customer needs. Based in Seattle, WA, Takeshi is passionate about pushing the boundaries of artificial intelligence and machine learning technologies.

Siddhant Gupta is a Software Development Manager on the Amazon Q team based in Seattle, WA. He is driving innovation and development in cutting-edge AI-powered solutions.

Akhilesh Amara is a Software Development Engineer on the Amazon Q team based in Seattle, WA. He is contributing to the development and enhancement of intelligent and innovative AI tools.