Embedding Q Business into existing applications

Amazon Q Business has gotten some new features in the last few months. One of them is the ability to embed Q Business into other applications. This blog post gives some guidance on how this works and what to consider when adding Q Business to another application.

Why?

Often companies use other tools such as MS SharePoint or Confluence as their intranet. In case Q Business should not be treated as a separate tool, it can be integrated into existing applications. Users can then simply open a page that contains Q Business. For example, this screenshot shows the integration into a Confluence page.

How does it work?

First, you need to whitelist the site that embeds Q Business in the Q Business configuration. Open the new "Amazon Q embedded" configuration and add the URL of the site, such as https://julianmichel.de. Don't include the specific path and a trailing slash at the end.

Next, copy the URL of your Q Business application:

Then create an iFrame in the application and reference the URL you copied in the previous step. For example, in Confluence, search for the iFrame element.

Then paste the URL you copied earlier.

You can also do the same change in a plain HTML file by adding the iFrame element.

<iframe src="https://pgs3zrql.chat.qbusiness.us-east-1.on.aws/"
  title="QBusiness"></iframe>

For more details, see the Embedded Q Business section in the documentation.

Testing

You are now ready to open the Confluence page. Q Business will not load directly. Instead, it displays a login page. Press the Sign In-button.

It opens a new tab that handles the login process using the SSO capabilities in AWS IAM Identity Center. You can close this tab.

Next, it displays Q Business integrated into the Confluence page.

The integration into the custom HTML page also works. Again, the sign in page is displayed.

Once you have completed the sign in process, you will see Q Business integrated into the page.

Error handling

What to do if embedding Q Business doesn't work? If you get this error and Q Business doesn't load at all, check the URL you configured before. It is probably incorrect.

If the Grant Permission button doesn't work, check the output in Web Developer Tools.

For example, I received this error when accessing the page in Google Chrome's incognito mode: requestStorageAccess: Request denied because the embedded site has never been interacted with as a top-level context.

Root cause: Third-party cookies are blocked in incognito mode. I had to enable them and it worked.

Also check the iFrame sandbox attribute settings if used in the iFrame.

Whitelisting URLs with IaC

Of course, it makes sense to configure the URL of the embedded web packages using Infrastructure as Code. In an earlier post, I described how to deploy Q Business using AWS CDK. In the WebExperience resource, you can specify an array of URLs in the origins property. Unfortunately, the property isn't called embedded URLs or anything like that, so it's different from the naming in the AWS console.

new q.CfnWebExperience(this, 'WebExperience', {
  applicationId: application.attrApplicationId,
  roleArn: webExperienceRole.roleArn,
  origins: [
    'https://jumic-reinvent.atlassian.net',
    'https://julianmichel.de',
  ],
});

Summary

Embedded Q Business is a great feature for integrating Q Business into existing applications. From my point of view, it improves the user experience when users can access it in familiar applications.

Unfortunately, you have to log in to Q Business first. But this is not a design decision by AWS - it is related to web security standards.

If Q Business Embedded doesn't work out of the box, you can use the web developer tools to debug it.