Amazon Q Business - Identity Federation Application

Quiz

Amazon Q Business connects with your company's identity system for user management and authentication through AWS Identity and Access Management. This chapter will provide brief knowledge about creating and configuring an Amazon Q Business application using IAM Federation to manage end user access.

Okta IAM Federation

The following steps show how to integrate Amazon Q Business with Okta:

Prerequisites

Before you start to integrate Amazon Q Business with Okta, make sure that you have:

Created an Okta account and added at least one user with a valid email address.
Created IAM policies containing the permissions outlined in IAM role for an Amazon Q Business web experience using IAM Federation.

Step 1: Set Up Okta App

To create an Okta instance follow the steps mentioned below:

Sign into Okta and go to the 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, in General Settings, for App name, enter a name for the application and choose Next.
In Configure SAML, do the following:

For Single sign-on URL, enter your web application endpoint.

Custom app endpoint URL format: [your URL]/saml (e.g. http://localhost:8000/saml)

Generated web experience endpoint URL format: [your URL]/saml (e.g. https://abcdefgh.qbusiness.us-east-1.on.aws/saml)

Uncheck the Use this for Recipient URL and Destination URL box.
Then, for the Recipient URL field, enter the following AWS endpoint: https://signin.aws.amazon.com/saml.
For Destination URL, enter your web application endpoint.

Custom app endpoint URL format: [your URL]/saml (e.g. http://localhost:8000/saml)

Generated web experience endpoint URL format: [your URL]/saml (e.g. https://abcdefgh.qbusiness.us-east-1.on.aws/saml)

Generated web experience endpoint URL format: Enter a placeholder URL (e.g. http://sampleurl.com) for now, to be updated at the end of the Amazon Q Business application creation process.

For Audience URI (SP Identity ID), enter the following AWS endpoint: https://signin.aws.amazon.com/saml.
For Name ID format, set to Persistent.
The, scroll down to the bottom of the page and select Next.

Select the best option on the Create SAML Integration page and click Finish. You'll be redirected to the application summary page.
On the application summary page, from the top navigation menu, select Assignments, and then select Assign
Next, you download the SAML payload and copy your Sign on URL.

Step 2: Add IAM Identity Provider

To connect Okta to AWS Identity and Access Management, follow the steps mentioned below:

Sign in to the AWS Identity and Access Management console.
In the left navigation menu, from Access management, select Identity providers.
From Identity providers, select Add provider.
In Add an identity provider, for Configure provider do the following:

For Provider type, Select SAML.
For Provider name, Add a name to identify your identity provider.
For Metadata document, Upload the .xml file you downloaded and saved from Okta in Step 1.
Select Add provider.

On the Identity provider summary page, from Provider, select the provider you just added do the following:

Copy and save the ARN from the Summary page. You'll need it for your trust policy and Okta setup. ARN format: arn:aws:iam::aws-account-id:saml-provider/assigned-iam-idp-name.
Then, select Assign role to create an IAM role with the necessary permissions for your identity provider.

In Assign role, for Role options select Create a new role.
Then, on the Selected trusted entity page, do the following:

For Trusted entity type select SAML 2.0 federation.
In SAML 2.0 federation, from the SAML 2.0-based provider dropdown, select the identity provider you added.
For Access to be allowed, select Allow programmatic access only.
For Attribute, select SAML:aud.
For Value, enter the following: https://signin.aws.amazon.com/saml.
Select Next.

Choose an IAM policy with required permissions on the Add permissions page and click Next.
Enter a Role name, optional description, and tags on the Name, review, and create page. Then, click Create role.
From the Roles page, select the IAM role you just created. Then, from the role summary page, do the following:

Copy and save the role ARN (e.g., arn:aws:iam::111122223333:role/sample-role) for connecting your AWS IAM identity provider instance to Okta
Edit the trust policy by adding a new statement, replacing 'account_id' with your AWS account ID and 'saml_provider' with the assigned-iam-idp-name from your IAM identity provider ARN.

"Version": "2012-10-17",
"Statement": [
    {
        "Effect": "Allow",
        "Principal": {
            "Federated": "arn:aws:iam::{{account_id}}:saml-provider/[[saml_provider]]"
        },
        "Action": "sts:AssumeRoleWithSAML",
        "Condition": {
            "StringEquals": {
                "SAML:aud": "https://signin.aws.amazon.com/saml"
            }
        }
    },
    {
        "Effect": "Allow",
        "Principal": {
            "Federated": "arn:aws:iam::{{account_id}}:saml-provider/[[saml_provider]]"
        },
        "Action": "sts:TagSession",
        "Condition": {
            "StringLike": {
                "aws:RequestTag/Email": "*"
            }
        }
    }
]

Then, select Update policy.

Step 3: Connect IAM to Okta

In this steps we are Configuring the trust relationship between AWS IAM and Okta.

Sign into Okta and go to the admin console.
In the left navigation pane, choose Applications, and then choose the Okta application you created.
In General, from SAML Settings choose Edit.
In Edit SAML, for General Settings choose Next.
In Configure SAML, scroll down to the Attribute Statements section, and add the attribute

Step 4: Create Q Business App

To create an application using concole follow the steps mentioned below:

Sign in to the AWS Management Console and open the Amazon Q Business console.
From the How it works menu, choose Try quick application.
On the Create application page, for Application settings, enter the Application name for your Amazon Q Business application
In Service access, select method to authorize Amazon Q Business from the options such as "Create and use a new service-linked role (SLR)","Create and use a new service role (SR)","Use an existing service role (SR)/service-linked role (SLR)" and "Service role name".
To customize your encryption settings, select Customize encryption settings (advanced).
For Access management method, choose IAM Identity Center.
To enable cross-region calls in Amazon Q Business for IAM Identity Center integration, create an IAM Identity Center instance then Activate Enable cross-region calls.
Then Connect Amazon Q Business to IAM Identity Center
To start creating your application, choose Create.

Step 5: Set Up Q Business Retriever

To create an Amazon Q Business retriever using console follow the steps mentioned below:

Sign in to the AWS Management Console and open the Amazon Q Business console.
Complete the steps to create your Amazon Q Business application.
Then, for Select retriever, choose Use native retriever
In Index provisioning, Choose between Starter and Enterprise index types based on your use case and Choose the Number of units that you need.
For Tags, Choose whether you want to add Index tags.
To create your retriever and index, choose Create.

To create an Amazon Kendra retriever using console follow the steps mentioned below:

Sign in to the AWS Management Console and open the Amazon Q Business console.
Complete the steps to create your Amazon Q Business application.
In Select retriever, choose Use existing retriever
In Tags, Choose whether you want to add Retriever tags.
To connect your application environment to your data sources, choose Next.

Step 6: Link Q Business Data Sources

Choose a retriever for your Amazon Q Business app, then connect data sources to it. The available data sources depend on the retriever you pick.

If you use an Amazon Q Business retriever, you can choose from the following options:

Connect to any Amazon Q Business supported data source connectors by using the CreateDataSource API operation.
Upload documents directly by using the BatchPutDocument API operation.

Step 7: Manage access

To manage user acess, follow the steps mentioned below:

Sign in to the AWS Management Console and open the Amazon Q Business console.
Complete the steps to create your Amazon Q Business application.
Set default subscription tier to Q Business Pro or Q Business Lite. This will be the default for all users logging in to your web experience.
Select Create application.

Customizing a web experience

To customize an Amazon Q Business web experience you need to follow the steps mentioned below:

Sign in to the AWS Management Console and open the Amazon Q Business console.
Complete the steps to create your Amazon Q Business application.
Then, from the Amazon Q Business application environment page, select your application, and then select Customize web experience.
In Customize web experience, from the right navigation pane, select Customize web experience.
In Customize web experience enter title, welcome message, display sample prompts.
Then choose Save

Connect Apps to Single IdP

You can connect multiple Amazon Q Business custom applications to a single SAML 2.0 or OIDC based identity provider (IdP) application.

Using SAML

To connect multiple Amazon Q Business custom applications to Okta using SAML follow the steps mentioned below:

Sign into Okta and go to the admin console.
In the left navigation pane, choose Applications, and then choose your existing SAML 2.0 application.
From General, choose SAML settings.
Keep your General Settings as is and select Next.
Edit SAML Integration: Enter Single sign-on URL and Audience URI for your first SAML application under General in SAML Settings.
Then, from General, select Show Advanced Settings.
Scroll down to Other Requestable SSO URLs and select Add Another.
Add Single sign-on URLs for additional SAML applications, including an index value for each. Use format: http://localhost:8000/saml.
Then, scroll down and select Next.
On the Feedback page, select Finish.

Using OIDC

To connect multiple Amazon Q Business custom applications to Okta using OIDC follow the steps mentioned below:

Sign into Okta and go to the admin console.
From General, scroll down to General Settings, and then select Edit.
From LOGIN, for Sign-in redirect URIs, and then select Edit.
In Sign-in redirect URIs, choose Add URI to add multiple URIs. Then, select Save.

Create IAM API App

Complete the steps mentioned below to create an IAM federated applications using APIs

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.
Create an Okta IdP instance and set up users and groups. These steps also apply to other identity providers connected to your IAM instance.
Created an IAM instance for your Amazon Q Business application and connected Okta as your identity source.
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.
Create the IAM identity provider using the following command:

aws iam \
create-open-id-connect-provider \
--url issuer-url

Next, create the IAM role. To do so, perform the following steps:

Create a directory named policies.
In that directory, create and save a file named trustpolicyforfederation.json with the following JSON included:

{
    "Version": "2012-10-17",
    "Statement": {
        "Sid": "RoleForOkta",
        "Effect": "Allow",
        "Principal": {
            "Federated": "OpenIdConnectProviderArn"
        },
        "Action": "sts:AssumeRoleWithWebIdentity",
        "Condition": {
            "StringEquals": {
                "issuer-url:aud": "client-id"
            }
        }
    }
}

Next, create the IAM policy for your web experience. To do so, perform the following steps:

In the policies directory, create and save a new file named permspolicyforfederation.json with the following JSON included:


"Version": "2012-10-17",
"Statement": [{
    "Sid": "QBusinessConversationPermissions",
    "Effect": "Allow",
    "Action": [
        "qbusiness:Chat",
        "qbusiness:ChatSync",
        "qbusiness:ListMessages",
        "qbusiness:ListConversations",
        "qbusiness:PutFeedback",
        "qbusiness:DeleteConversation",
        "qbusiness:GetWebExperience",
        "qbusiness:GetApplication",
        "qbusiness:ListPlugins",
        "qbusiness:GetChatControlsConfiguration",
        "qbusiness:ListRetrievers"
    ],
    "Resource": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
},
{
    "Sid": "QBusinessRetrieverPermission",
    "Effect": "Allow",
    "Action": [
        "qbusiness:GetRetriever"
    ],
    "Resource": [
        "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}",
        "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}/retriever/*"
    ]
},
{
    "Sid": "QBusinessAutoSubscriptionPermission",
    "Effect": "Allow",
    "Action":  [
        "user-subscriptions:CreateClaim" 
    ],
    "Condition":  {
        "Bool":  {
            "user-subscriptions:CreateForSelf": "true" 
        },
        "StringEquals":  {
            "aws:CalledViaLast": "qbusiness.amazonaws.com" 
        }
    },
    "Resource":  [
        "*" 
    ]
},
{
    "Sid": "QBusinessKMSDecryptPermissions",
    "Effect": "Allow",
    "Action": [
        "kms:Decrypt"
    ],
    "Resource": [
        "arn:aws:kms:{{region}}:{{account_id}}:key/[[key_id]]"
    ],
    "Condition": {
        "StringLike": {
            "kms:ViaService": [
                "qbusiness.{{region}}.amazonaws.com",
                "qapps.{{region}}.amazonaws.com"
            ]
        }
    }
},
{
    "Sid": "QAppsResourceAgnosticPermissions",
    "Effect": "Allow",
    "Action": [
        "qapps:CreateQApp",
        "qapps:PredictQApp",
        "qapps:PredictProblemStatementFromConversation",
        "qapps:PredictQAppFromProblemStatement",
        "qapps:ListQApps",
        "qapps:ListLibraryItems",
        "qapps:CreateSubscriptionToken"
    ],
    "Resource": "arn:aws:qbusiness:{{region}}:{{source_account}}:application/{{application_id}}"
},
{
    "Sid": "QAppsAppUniversalPermissions",
    "Effect": "Allow",
    "Action": [
        "qapps:DisassociateQAppFromUser"
    ],
    "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*"
},
{
    "Sid": "QAppsAppOwnerPermissions",
    "Effect": "Allow",
    "Action": [
        "qapps:GetQApp",
        "qapps:CopyQApp",
        "qapps:UpdateQApp",
        "qapps:DeleteQApp",
        "qapps:ImportDocument",
        "qapps:ImportDocumentToQApp",
        "qapps:CreateLibraryItem",
        "qapps:UpdateLibraryItem",
        "qapps:StartQAppSession"
    ],
    "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*",
    "Condition": {
        "StringEqualsIgnoreCase": {
            "qapps:UserIsAppOwner": "true"
        }
    }
},
{
    "Sid": "QAppsPublishedAppPermissions",
    "Effect": "Allow",
    "Action": [
        "qapps:GetQApp",
        "qapps:CopyQApp",
        "qapps:AssociateQAppWithUser",
        "qapps:GetLibraryItem",
        "qapps:CreateLibraryItemReview",
        "qapps:AssociateLibraryItemReview",
        "qapps:DisassociateLibraryItemReview",
        "qapps:StartQAppSession"
    ],
    "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*",
    "Condition": {
        "StringEqualsIgnoreCase": {
            "qapps:AppIsPublished": "true"
        }
    }
},
{
    "Sid": "QAppsAppSessionModeratorPermissions",
    "Effect": "Allow",
    "Action": [
        "qapps:ImportDocument",
        "qapps:ImportDocumentToQAppSession",
        "qapps:GetQAppSession",
        "qapps:GetQAppSessionMetadata",
        "qapps:UpdateQAppSession",
        "qapps:UpdateQAppSessionMetadata",
        "qapps:StopQAppSession"
    ],
    "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*/session/*",
    "Condition": {
        "StringEqualsIgnoreCase": {
            "qapps:UserIsSessionModerator": "true"
        }
    }
},
{
    "Sid": "QAppsSharedAppSessionPermissions",
    "Effect": "Allow",
    "Action": [
        "qapps:ImportDocument",
        "qapps:ImportDocumentToQAppSession",
        "qapps:GetQAppSession",
        "qapps:GetQAppSessionMetadata",
        "qapps:UpdateQAppSession"
    ],
    "Resource": "arn:aws:qapps:{{region}}:{{source_account}}:application/{{application_id}}/qapp/*/session/*",
    "Condition": {
        "StringEqualsIgnoreCase": {
            "qapps:SessionIsShared": "true"
        }
    }
}

Finally, create and attach the roles in IAM using the following command:

aws iam \
create-role \
--role-name 
--assume-role-policy-document file://policies/trustpolicyforfederation.json \
--policy-document file://policies/permspolicyforfederation.json

API Call Session Workflow

First, use the IdToken from Okta to call the AssumeRoleWithWebIdentity API to get AWS credentials. To do so, use the following command:

aws sts
assume-role-with-web-identity
--role-arn role arn
--role-session-name session-name
--web-identity-token id-token-from-okta

Then, set the following environment variables in your command line environment using the credentials you received as a response from the AssumeRoleWithWebIdentity API call.

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, make Amazon Q Business API calls using the following command:

aws qbusiness \
chat-sync \
--application-id application-id
--user-message sample-chat-request

Print Page