:zap: If you created a new Amazon Q Business application on or after April 30th, 2024, you can now set up a Microsoft Teams gateway using the updated instructions provided below. These new Amazon Q Business applications are integrated with IAM Identity Center. The CloudFormation (CFN) template and the necessary steps have been updated to accommodate the setup of the Teams gateway for new applications. |
---|
Note: The instructions provided in this guide are specific to Okta, but they should also work for other OIDC 2.0 compliant Identity Providers (IdPs) with minor adjustments.
Amazon Q is a new generative AI-powered application that helps users get work done. Amazon Q can become your tailored business expert and let you discover content, brainstorm ideas, or create summaries using your company’s data safely and securely. For more information see: Introducing Amazon Q, a new generative AI-powered assistant (preview)
In this repo we share a project which lets you use Amazon Q business expert's generative AI to enable Microsoft Teams members to access your organizations data and knowledge sources via conversational question-answering.
You can connect to your organization data via data source connectors and integrate it with Teams Gateway for Amazon Q business expert to enable access to your Teams channel members. It allows your users to:
It's amazingly powerful. Here's a demo - seeing is believing!
It's easy to deploy in your own AWS Account, and add to your own teams. We show you how below.
/new_conversation
.This sample Amazon Q business expert Teams application is provided as open source — use it as a starting point for your own solution, and help us make it better by contributing back fixes and features via GitHub pull requests. Explore the code, choose Watch to be notified of new releases, and check back for the latest updates.
Follow the instructions below to deploy the project to your own AWS account and Teams, and start experimenting!
You need to have an AWS account and an IAM Role/User with permissions to create and manage the necessary resources and components for this application. (If you do not have an AWS account, please see How do I create and activate a new Amazon Web Services account?)
You need to have an Okta Workforce Identity Cloud account. If you haven't signed up yet, see Signing up for Okta
You need to configure SAML and SCIM with Okta and IAM Identity Center. If you haven't configured, see Configuring SAML and SCIM with Okta and IAM Identity Center
You also need to have an existing, working Amazon Q business application integrated with IdC. If you haven't set one up yet, see Creating an Amazon Q application
You need to have users subscribed to your Amazon Q business application, and are able to access Amazon Q Web Experience. If you haven't set one up yet, see Subscribing users to an Amazon Q application
You have aws cli latest version installed on your Linux or MacOS system. If you haven't installed yet, see Installing the AWS CLI version 2
Lastly, you need a Microsoft account and a Microsoft Teams subscription to create and publish the app using the steps below. If you don’t have these, see if your company can create sandboxes for you to experiment, or create a new account and trial subscription as needed to complete the directions below. You will need a Office 365 business subscription for Teams admin privileges. This subscription will also provide a business Microsoft account which will be needed since some steps cannot use an account with a personal email address.
Create the client as a 'Web app'. You will want to enable the 'Refresh Token' grant type, 'Allow everyone in your organization to access', and 'Federation Broker Mode'. Use a placeholder URL, like https://example.com
, for the redirect URI, as you will update this later (in step 3).
Create trusted token issuer to trust tokens from OIDC issuer URL using these instructions listed here - https://docs.aws.amazon.com/singlesignon/latest/userguide/using-apps-with-trusted-token-issuer.html. Or you can run the below script.
For the script, you need to have the OIDC issuer URL and the AWS region in which you have your Q business application. To retrieve the OIDC issuer URL, go to Okta account console, click the left hamburger menu and open Security > API and copy the whole 'Issuer URI'.
The script will output trusted token issuer ARN (TTI_ARN) which you will use in the next step.
export AWS_DEFAULT_REGION=<>
OIDC_ISSUER_URL=<>
bin/create-trusted-token-issuer.sh $OIDC_ISSUER_URL
Create customer managed IdC application by running below script.
For the script, you need to have the OIDC client ID, trusted token issuer ARN, and the region in which you have your Q business application. To retrieve the OIDC client ID, go to Okta account console, click the left hamburger menu and open Applications > Applications and click on the application you created in step 1.1. Copy the 'Client ID'. For TTI_ARN, you can use the output from the previous step.
The script will output the gateway IdC application ARN (GATEWAY_IDC_ARN) which you will use in the next step.
export AWS_DEFAULT_REGION=<>
OIDC_CLIENT_ID=<>
TTI_ARN=<>
bin/create-idc-application.sh $OIDC_CLIENT_ID $TTI_ARN
We've made this easy by providing pre-built AWS CloudFormation templates that deploy everything you need in your AWS account.
If you are a developer, and you want to build, deploy and/or publish the solution from code, we've made that easy too! See Developer README
Stack Name
: Name your App, e.g. AMAZON-Q-TEAMS-GATEWAY.AmazonQAppId
: Your existing Amazon Q business expert application ID (copy from Amazon Q console). AmazonQRegion
: Choose the region where you created your Amazon Q business expert application.OIDCIdPName
: The name of the OIDC external identity provider ('Okta' and 'Cognito' are explicitly supported, leave empty to use default for others)OIDCClientId
: The client ID of OIDC client you created in step 1.1.OIDCIssuerURL
: The issuer URL of the OIDC client you created in step 1.1.GatewayIdCAppARN
: The application arn of IdC customer managed application you created in step 1.3.MicrosoftAppId
: The MicrosoftAppId
you copied in step 2.ContextDaysToLive
: Just leave this as the default (90 days)Region | Easy Deploy Button | Template URL - use to upgrade existing stack to a new release |
---|---|---|
N. Virginia (us-east-1) | https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json | |
Oregon (us-west-2) | https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json |
When your CloudFormation stack status is CREATE_COMPLETE, choose the Outputs tab, and keep it open - you'll need it below.
Go the app client settings created in IdP (in step 1.1), and update the client signin redirect URL with exported value in Cloudformation stack for the output with suffix OIDCCallbackEndpointExportedName
.
TeamsEventHandlerApiEndpoint
from your Stack outputs tab (from Step 1). Do not check Enable Streaming Endpoint. Single Tenant
. IMPORTANT In this example we are not enabling app secret rotation. Enable it for a production app by implementing rotation via AWS Secrets Manager. Please create an issue (or, better yet, a pull request!) in this repo if you want this feature added to a future version.
TeamsSecretConsoleUrl
.Retrieve secret value
Edit
MicrosoftAppId
, MicrosoftAppPassword
, and MicrosoftAppTenantId
with the values you noted in the previous steps.OIDCClientSecretConsoleUrl
.Retrieve secret value
Edit
OidcClientSecret
, you will find those values in the IdP app client configuration.https://www.anycompany.com/
etc. Use real ones for production.MicrosoftAppId
from above.MicrosoftAppId
from the earlier stepsAnd, now, at last, you can test your bot in Microsoft Teams!
To use your Amazon Q business expert app in your team channels, first add it to each team:
Time to say Hi!
We welcome your contributions to our project. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community.
See CONTRIBUTING for more information.
See Security issue notifications for more information.
This library is licensed under the MIT-0 License. See the LICENSE file.