How do I troubleshoot errors that I receive when I set up Amazon Q Business with IAM Identity Center?

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

SCPs explicitly deny the action

Service control policies (SCPs) define the maximum permissions available for AWS accounts within AWS Organizations. If an SCP denies the action, then you might receive the following error:

"An error occurred during creation, but we do not know the cause."

To modify an SCP, use a management account. Management accounts restrict member accounts, and member accounts can't modify SCPs. If you use a member account, then contact your management account administrator.

If you use a management account, then complete the following steps:

1. Open the Organizations console.
2. In the navigation pane, choose Service Control Policies.
3. Review the list of SCPs to identify whether an SCP explicitly denies permissions for Amazon Q Business actions. Or, to check for permission-denied events, use AWS CloudTrail logs.
4. If an SCP is denying permissions, then update the SCP.

Or, use AWS Identity and Access Management (IAM) identity federation through an external identity provider (IdP) to set up authentication for Amazon Q Business. When you set up Amazon Q Business through an external IdP, SCP restrictions don't apply because users authenticate in the IdP.

For more information, see Creating an Amazon Q Business application using IAM Federation through Okta.

SCIM synchronization creates duplicate users

System for Cross-domain Identity Management (SCIM) populates users into IAM Identity Center from the IdP. If you use SCIM synchronization to set up IAM Identity Center from an external IdP, such as Okta, then you might receive the following error:

"User <> is not authorized to make this request because there is already an active user for this userId."

If you manually create a user before you activate SCIM, then a duplicate entry is detected. To resolve this issue, delete the existing user, activate SCIM, and then re-add the user.

To check whether the user exists in Amazon Q Business, run the get-user AWS CLI command:

aws qbusiness get-user --application-id  example-app-id --user-id example-user-id

Note: Replace example-app-id with your application ID and example-user-id with your user ID. You can find your application ID in the Amazon Q Business console under Applications.

To delete the user, run the delete-user command:

aws qbusiness delete-user --application-id example-app-id --user-id example-user-id

Note: Replace example-app-id with your application ID and example-user-id with your user ID.

To confirm that the user is deleted, run the get-user command. Then, activate the SCIM synchronization.

To verify that the user is added to Amazon Q Business, complete the following steps:

1. Open the Amazon Q Business console.
2. In the navigation pane, choose Applications.
3. Select your application.
4. Under Manage user access, find the user.

Confirm that the SCIM synchronization is correctly set up to map users to IAM Identity Center.

There are missing identity-aware session settings

Identity-aware sessions are required for Amazon Q Business to authenticate users, call APIs, and perform user-specific operations. If identity-aware sessions aren't activated in your organization's management account, then you might receive the following error:

"Contact your administrator in order to enable Amazon Q in the AWS Console. You must ensure identity-aware sessions are enabled in the AWS Orgs Management account."

To activate identity-aware sessions, complete the following steps:

1. Activate an organization instance of IAM Identity Center.
   Note: If you use an AWS cross-Region IAM Identity Center setup, then make sure that your organization instance supports cross-Region connections.
2. Activate identity-aware sessions.
3. Confirm your Region availability for Amazon Q Business.

Related information

AWS IAM Identity Center

Organization and account instances of IAM Identity Center