Prerequisites One-time setup Workflow for each API call session for authenticated user

Making authenticated Amazon Q Business API calls using IAM Identity Center

Amazon Q Business can securely handle data with integrated authentication and authorization. During data ingestion, Amazon Q Business preserves the authorization information—access control lists (ACLs)—from the data source so users can only request answers from the data they already have access to. Through IAM Identity Center, Amazon Q Business uses trusted identity propagation to ensure that an end user is authenticated and receives fine-grained authorization to their user ID and group-based resources.

In order to achieve this, a subset of the Amazon Q Business APIs (Chat, ChatSync, ListConversations, ListMessages, DeleteConversation, PutFeedback) require identity-aware AWS Sig V4 credentials for the authenticated user on whose behalf the API call is being made.

This page provides an overview of the workflows needed to obtain AWS Sig V4 credentials for a user authenticated using an identity provider (IdP), such as Okta. While we use Okta as an example, the same principles and steps apply to any other identity provider synced with your IAM Identity Center instance.

Prerequisites

Before you begin setting up for making Sig V4 authenticated API calls, make sure you've done the following:

Created an Amazon Q Business application.
Created an Okta IdP instance and configured users and groups within it.
Created an IAM Identity Center instance for your Amazon Q Business application that uses Okta as your as the identity source.
Synchronized the users and groups from Okta by configuring SAML and SCIM with Okta and IAM Identity Center.
Configured access to the AWS CLI.

One-time setup

The following section outlines the steps to set up the Amazon Q Business control plane. You only need to perform these steps once.

Create an OIDC app integration in Okta.
Then, in the IAM Identity Center instance you have created, create a Trusted Token Issuer to trust IdP issuer with the issuer URL. For example, https://<your-okta-instance>.okta.com/oauth2/default.

In your IAM Identity Center instance, create a customer managed custom application using the following AWS CLI command:



aws sso-admin create-application \
--application-provider-arn arn:aws:sso::aws:applicationProvider/custom \
--instance-arn your-identity-center-arn \
--name your-custom-application-name

Then, disable user assignment or provide explicit user assignments to the custom application you created using the following AWS CLI command:
```
aws sso-admin put-application-assignment-configuration \
--application-arn your-custom-application-arn \
--no-assignment-required
                            
```

Then, add a JWT bearer grant to your application environment using the put application environment grant CLI command. For example:



aws sso-admin put-application-grant \
--cli-input-json '{
   "ApplicationArn":"identity-center-custom-application-arn",
   "Grant":{
      "JwtBearer":{
         "AuthorizedTokenIssuers":[
            {
               "AuthorizedAudiences":[
                  "idp-authorized-audience"
               ],
               "TrustedTokenIssuerArn":"trusted-token-issuer-arn"
            }
         ]
      }
   },
   "GrantType":"urn:ietf:params:oauth:grant-type:jwt-bearer"
}'

You will then need to add an authentication method for a Amazon Q Business application environment using the put application environment authentication method AWS CLI command:



aws sso-admin put-application-authentication-method \
--cli-input-json '{
            "ApplicationArn": "'identity-center-custom-application-arn",
            "AuthenticationMethod": {
                "Iam": {
                    "ActorPolicy": {
                        "Version": "2012-10-17",
                        "Statement": [
                            {
                                "Effect": "Allow",
                                "Principal": {
                                    "AWS": "your-aws-account-id"
                                },
                                "Action": "sso-oauth:CreateTokenWithIAM",
                                "Resource": "your-identity-center-custom-application-arn"
                            }
                        ]
                    }
                }
            },
            "AuthenticationMethodType": "IAM"
        }'

Next, add a list of authorized targets for an IAM Identity Center access scope for an Amazon Q Business application environment using the following put application environment access scope AWS CLI command:
```
aws sso-admin put-application-access-scope \
--application-arn identity-center-custom-application-arn \
--scope "qbusiness:conversations:access"
```
```
aws sso-admin put-application-access-scope \
--application-arn identity-center-custom-application-arn
```

Then, create an IAM role that your application environment will use to call AssumeRole API with the following policies:

Trust policy


{
     "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "QCLITrustPolicy",
            "Effect": "Allow",
            "Principal": {
                "AWS": "idc-custom-application-arn"
            },
            "Action": [
                "sts:AssumeRole",
                "sts:SetContext"
            ]
        }
    ]
 }

Permissions policy


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "QBusinessConversationPermission",
            "Effect": "Allow",
            "Action": [
                "qbusiness:Chat",
                "qbusiness:ChatSync",
                "qbusiness:ListMessages",
                "qbusiness:ListConversations",
                "qbusiness:DeleteConversation",
                "qbusiness:PutFeedback",
                "qbusiness:GetWebExperience",
                "qbusiness:GetApplication",
                "qbusiness:ListPlugins",
                "qbusiness:GetChatControlsConfiguration"
            ],
            "Resource": "amazon-qbusiness-application-arn"
        },
        {
            "Sid": "QBusinessKMSDecryptPermissions",
            "Effect": "Allow",
            "Action": [
                "kms:Decrypt"
            ],
            "Resource": [
                "arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
            ]
        },
        {
            "Sid": "QBusinessSetContextPermissions"
            "Effect": "Allow",
            "Action": "sts:SetContext",
            "Resource": "arn:aws:sts:account-id:self"
        }
    ]
}

Workflow for each API call session for authenticated user

First, use the CreateTokenWithIAM API call to obtain an IAM Identity Center-provided JWT bearer grant token using your:
- clientID: Your IAM Identity Center custom application environment ARN.
- grantType: For example, 'urn:ietf:params:oauth:grant-type:jwt-bearer'.
- assertion: The user authenticated ID token obtained from Okta.
Then, use the AssumeRole API call to obtain user decorated AWS Sig V4 credentials using your:
- RoleArn: The IAM role ARN.
- RoleSessionName: A unique session name.
- DurationSeconds: The session duration in seconds.
- ProvidedContexts: A list of previously acquired trusted context assertions in the format of a JSON array. The trusted context assertion is signed and encrypted by AWS STS. For example:
```
[{
    'ProviderArn': "arn:aws:iam::aws:contextProvider/IdentityCenter",
    'ContextAssertion': claims["sts:identity_context"]
}]
```
  Note
  The ContextAssertion uses the “sts:identity_context” object from the claims object of the decoded JWT bearer grant token obtained as part of Step 1 in this procedure.
Use the identity-aware AWS Sig V4 credentials in the previous step to initialize the AWS SDK client and then make Amazon Q Business API calls using that client.

First, set the following environment variables in your command line environment:
```
AWS_ACCESS_KEY_ID="identity-aware-sigv4-access-key"
AWS_SECRET_ACCESS_KEY="identity-aware-sigv4-secret-key"
AWS_SESSION_TOKEN="identity-aware-sigv4-session-token"
```
Then, run the follwoing Python script from the same window:
```
import boto3
import json
import random

import boto3

aq_client = boto3.client(
    "qbusiness",
    region_name="your-aws-region"
)

resp = aq_client.chat_sync(
    applicationId = "amazon-qbusiness-application-id",
    userMessage = "chat-request",
    clientToken = str(random.randint(0,10000)
)

print(f"Amazon Q Business response: {resp["systemMessage"]}")
```
Important
As a security best practice, the credentials should not be hard coded in your scripts or code. For more information, refer to Boto 3 documentation on using credentials.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Setting up a streaming chat

User and group management

Making authenticated Amazon Q Business API calls using IAM Identity Center

Prerequisites

One-time setup

Workflow for each API call session for authenticated user

Note

Important