Akber A Choudhry

Using TTI and AWS IDC for Amazon Q Business Querying

Akber A Choudhry -

Connecting external identities to AWS services for seamless, secure access is a common challenge. When integrating an external Identity Provider (IdP) with Amazon Q Business for secure querying, the architecture involves a sophisticated game of "pass the credential," ensuring identity context and permissions are maintained across boundaries.

This post breaks down how a Trusted Token Issuer (TTI) works in concert with AWS IAM Identity Center (IDC) to enable secure querying of an Amazon Q index, focusing on the flow of identity and Access Control Lists (ACLs).

The Challenge: Maintaining Identity Context Across Trust Boundaries

When a user queries Amazon Q Business, the system needs to know who they are and what groups they belong to in order to filter search results based on document ACLs.

Often, the user's primary identity resides outside of AWS (e.g., in Okta, Azure AD, or a custom application). The challenge is securely transmitting that identity's group membership—which defines their access rights—into the Amazon Q environment.

This is achieved through a multi-stage token exchange involving a TTI and AWS IDC.

1. The First Hop: Enclosing the Initial SSO Token

The process begins when a user authenticates with their external IdP (the "initial SSO"). They receive an identity token (e.g., an OIDC IdToken).

However, AWS IDC cannot always directly consume this raw external token for API authorization, especially in complex custom scenarios. Enter the Trusted Token Issuer (TTI).

The TTI is an intermediate service you control that acts as a protocol converter and trusted bridge. Its job is encapsulation:

  1. The client application sends the initial external SSO token to your TTI.
  2. The TTI validates this token against the external IdP.
  3. The TTI extracts the crucial identity information—specifically the user's unique identifier and their group claims.
  4. The TTI mints a new signed JWT intended specifically for AWS IDC. It encloses the extracted identity and group information as claims within this new token.

This step is crucial because it allows you to normalize claims into a format AWS IDC expects.

2. How ACLs are Handled

Access Control List (ACL) handling is the primary driver for this entire architecture. Amazon Q Business indexes documents with attached ACLs (e.g., "Only members of group 'Finance-Managers' can see this document").

To enforce security, the token presented to Amazon Q must contain the user's group memberships.

The TTI is responsible for ensuring these group claims are accurately extracted from the initial SSO token and placed securely into the token destined for AWS IDC. Without this accurate propagation of group claims, Amazon Q cannot filter results, either showing too much data or nothing at all.

The TTI Alternative: Static Well-Known JWKS

Running a dynamic TTI service (like a Lambda function that mints tokens on demand) adds operational overhead. Is it always necessary?

No. If your token generation process is predictable, you can replace the dynamic TTI component with a static well-known JSON Web Key Set (JWKS) endpoint.

In this scenario:

  1. You generate a private/public key pair.
  2. You configure AWS IDC to trust the public key, hosted at a static, secured HTTPS URL (the well-known JWKS endpoint).
  3. Your application (the "issuer") uses the highly protected private key to sign tokens destined for IDC.

AWS IDC simply fetches the static public key to validate incoming tokens. This simplifies infrastructure but places a premium on protecting the private signing key.

The Final Stage: The IDC Token Analysis

The complexity of this flow culminates in the second stage of encapsulation.

The token from the TTI (or the static issuer) is exchanged with AWS IDC using the CreateTokenWithIAM API. AWS IDC validates the incoming token's signature based on the pre-configured trust.

Once validated, AWS IDC performs identity resolution and issues its own short-lived access token. This IDC token is the second stage of encapsulation.

Finally, the client application uses this IDC-issued token to make the actual query request to the Amazon Q Business API.

Crucially, the AWS account that owns the Q Index analyzes only this final IDC token. It does not see or care about the original external IdP token or the intermediate TTI token. It trusts AWS IDC, validates the IDC token, extracts the user principal and group claims from it, and uses that data to enforce document ACLs against the search index.

Technical Guidance

What is the IDC?

IDC stands for IAM Identity Center (formerly AWS Single Sign-On).

It is the centralized service in AWS for managing workforce identities. In this architecture, IDC acts as the "Identity Broker." It trusts your external TTI (via the public keys) and issues its own tokens that downstream AWS services (like Amazon Q Business) recognize and accept. This eliminates the need for Amazon Q to know about every possible external Identity Provider; it only needs to trust IDC.

The Token Structure (Code)

Below is a simplified representation of the JWT (JSON Web Token) that your TTI would sign and send to IDC.

The most critical part for ACLs is the claims section, specifically how groups are formatted so IDC can map them to the user.

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "key-id-from-your-well-known-jwks"
}
.
{
  "iss": "https://your-tti-service.com",   // Must match the TTI Issuer URL in IDC
  "sub": "user-123-abc",                   // Unique user ID
  "aud": "urn:aws:call:us-east-1:123456789012:qbusiness", // The Audience (AWS Service)
  "exp": 1715000000,
  "iat": 1714999000,
  "email": "jane.doe@example.com",         // Used for mapping to IDC user
  "groups": [                              // CRITICAL: These drive the ACLs in Q
    "finance-admin",
    "project-alpha-viewers" 
  ]
}
.
[Signature]

How the Exchange Works in Code (Python/Boto3): Once your application has the token above (let's call it tti_signed_token), it swaps it for an IDC token using the create_token_with_iam API.

import boto3

client = boto3.client('sso-oidc')

response = client.create_token_with_iam(
    clientId='YOUR_IDC_APP_CLIENT_ID',
    grantType='urn:ietf:params:oauth:grant-type:jwt-bearer',
    assertion=tti_signed_token  # The token shown above
)

# The result is the IDC token that you send to Amazon Q
idc_access_token = response['accessToken']

Here are the specific AWS documentation pages that detail these steps: