├── .eslintignore
├── .eslintrc
├── .github
└── ISSUE_TEMPLATE
│ ├── bug_report.md
│ └── feature_request.md
├── .gitignore
├── .npmignore
├── .prettierignore
├── .prettierrc.json
├── CHANGELOG.md
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── README_DEVELOPERS.md
├── README_ENTRA_ID.md
├── bin
├── convert-cfn-template.js
├── create-idc-application.sh
├── create-trusted-token-issuer.sh
├── environment.sh
├── my-amazon-q-teams-bot.ts
└── precheck.sh
├── cdk.json
├── deploy.sh
├── images
├── AddToTeam.png
├── QBotIcon-small.png
├── QBotIcon.png
├── entra_id_integration
│ ├── deploy_cfn
│ │ ├── deploy_cfn_1.png
│ │ ├── deploy_cfn_2.png
│ │ ├── deploy_cfn_3.png
│ │ ├── deploy_cfn_4.png
│ │ ├── deploy_cfn_5.png
│ │ ├── deploy_cfn_6.png
│ │ └── deploy_cfn_7.png
│ ├── note_app
│ │ ├── note_app_1.png
│ │ └── note_app_2.png
│ ├── register_bot
│ │ ├── register_bot_1.png
│ │ ├── register_bot_2.png
│ │ ├── register_bot_3.png
│ │ ├── register_bot_4.png
│ │ ├── register_bot_5.png
│ │ └── register_bot_6.png
│ ├── register_gateway
│ │ ├── register_gateway_1.png
│ │ ├── register_gateway_10.png
│ │ ├── register_gateway_11.png
│ │ ├── register_gateway_12.png
│ │ ├── register_gateway_13.png
│ │ ├── register_gateway_14.png
│ │ ├── register_gateway_15.png
│ │ ├── register_gateway_16.png
│ │ ├── register_gateway_17.png
│ │ ├── register_gateway_2.png
│ │ ├── register_gateway_3.png
│ │ ├── register_gateway_4.png
│ │ ├── register_gateway_5.png
│ │ ├── register_gateway_6.png
│ │ ├── register_gateway_7.png
│ │ ├── register_gateway_8.png
│ │ └── register_gateway_9.png
│ ├── register_oidc
│ │ ├── register_oidc_1.png
│ │ ├── register_oidc_10.png
│ │ ├── register_oidc_11.png
│ │ ├── register_oidc_12.png
│ │ ├── register_oidc_2.png
│ │ ├── register_oidc_3.png
│ │ ├── register_oidc_4.png
│ │ ├── register_oidc_5.png
│ │ ├── register_oidc_6.png
│ │ ├── register_oidc_7.png
│ │ ├── register_oidc_8.png
│ │ └── register_oidc_9.png
│ ├── register_teams_app
│ │ ├── register_teams_app_1.png
│ │ ├── register_teams_app_10.png
│ │ ├── register_teams_app_11.png
│ │ ├── register_teams_app_12.png
│ │ ├── register_teams_app_13.png
│ │ ├── register_teams_app_14.png
│ │ ├── register_teams_app_15.png
│ │ ├── register_teams_app_16.png
│ │ ├── register_teams_app_17.png
│ │ ├── register_teams_app_2.png
│ │ ├── register_teams_app_3.png
│ │ ├── register_teams_app_4.png
│ │ ├── register_teams_app_5.png
│ │ ├── register_teams_app_6.png
│ │ ├── register_teams_app_7.png
│ │ ├── register_teams_app_8.png
│ │ └── register_teams_app_9.png
│ └── update_secrets
│ │ ├── update_secrets_1.png
│ │ ├── update_secrets_2.png
│ │ ├── update_secrets_3.png
│ │ ├── update_secrets_4.png
│ │ ├── update_secrets_5.png
│ │ └── update_secrets_6.png
└── thread-demo.png
├── init.sh
├── jest.config.ts
├── lib
└── my-amazon-q-teams-bot-stack.ts
├── package-lock.json
├── package.json
├── publish.sh
├── src
├── functions
│ ├── oidc-callback-handler.ts
│ └── teams-event-handler.ts
├── helpers
│ ├── amazon-q
│ │ └── amazon-q-client.ts
│ ├── cache
│ │ └── cache.ts
│ ├── dynamodb-client.ts
│ ├── idc
│ │ ├── encryption-helpers.ts
│ │ └── session-helpers.ts
│ └── teams
│ │ └── q-teams-bot.ts
├── logging.ts
└── utils.ts
├── tsconfig.json
└── tst
├── functions
└── teams-event-handler.test.ts
└── mocks
├── amazon-q
├── valid-response-1.json
└── valid-response-2.json
└── slack
├── app-mention-no-thread.json
└── app-mention-thread.json
/.eslintignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | package.lock.json
3 | dist
4 | cdk.out
5 | build
--------------------------------------------------------------------------------
/.eslintrc:
--------------------------------------------------------------------------------
1 | {
2 | "root": true,
3 | "parser": "@typescript-eslint/parser",
4 | "plugins": [
5 | "@typescript-eslint",
6 | "prettier"
7 | ],
8 | "extends": [
9 | "eslint:recommended",
10 | "plugin:@typescript-eslint/eslint-recommended",
11 | "plugin:@typescript-eslint/recommended",
12 | "plugin:prettier/recommended"
13 | ],
14 | "env": {
15 | "node": true
16 | },
17 | "overrides": [
18 | {
19 | "files": ["*.js"],
20 | "rules": {
21 | "@typescript-eslint/no-var-requires": "off"
22 | }
23 | }
24 | ]
25 | }
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/bug_report.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Bug report
3 | about: Create a report to help us improve
4 | title: ''
5 | labels: ''
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Important:** Bug reports submitted here should relate specifically to the open source sample amazon-q-teams-gateway project. Do not submit bugs related to the Amazon Q service itself.
11 | If your issue relates to Amazon Q setup, user provisioning, document ingestion, accuracy, or other aspects of the service, then first check the Amazon Q documentation, and then reproduce the problem using the Amazon Q console web experience before engaging AWS support directly. Thank you.
12 |
13 | **Describe the bug**
14 | A clear and concise description of what the bug is.
15 |
16 | **To Reproduce**
17 | Steps to reproduce the behavior:
18 | 1. Go to '...'
19 | 2. Click on '....'
20 | 3. Scroll down to '....'
21 | 4. See error
22 |
23 | **Expected behavior**
24 | A clear and concise description of what you expected to happen.
25 |
26 | **Screenshots**
27 | If applicable, add screenshots to help explain your problem.
28 |
29 | **Additional context**
30 | Add any other context about the problem here.
31 |
--------------------------------------------------------------------------------
/.github/ISSUE_TEMPLATE/feature_request.md:
--------------------------------------------------------------------------------
1 | ---
2 | name: Feature request
3 | about: Suggest an idea for this project
4 | title: ''
5 | labels: ''
6 | assignees: ''
7 |
8 | ---
9 |
10 | **Is your feature request related to a problem? Please describe.**
11 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
12 |
13 | **Describe the solution you'd like**
14 | A clear and concise description of what you want to happen.
15 |
16 | **Describe alternatives you've considered**
17 | A clear and concise description of any alternative solutions or features you've considered.
18 |
19 | **Additional context**
20 | Add any other context or screenshots about the feature request here.
21 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | !jest.config.js
2 | *.d.ts
3 | node_modules
4 |
5 | # CDK asset staging directory
6 | .cdk.staging
7 | cdk.out
8 | dist
9 | .idea
10 | cdk-outputs.json
11 | environment.json*
12 | build
13 | awsrelease.sh
--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | *.ts
2 | !*.d.ts
3 |
4 | # CDK asset staging directory
5 | .cdk.staging
6 | cdk.out
7 |
--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | package.lock.json
3 | dist
4 | cdk.out
5 | build
--------------------------------------------------------------------------------
/.prettierrc.json:
--------------------------------------------------------------------------------
1 | {
2 | "printWidth": 100,
3 | "semi": true,
4 | "singleQuote": true,
5 | "tabWidth": 2,
6 | "useTabs": false,
7 | "trailingComma": "none",
8 | "endOfLine": "auto"
9 | }
--------------------------------------------------------------------------------
/CHANGELOG.md:
--------------------------------------------------------------------------------
1 | # Changelog
2 | All notable changes to this project will be documented in this file.
3 |
4 | The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
5 | and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
6 |
7 | ## [Unreleased]
8 |
9 | ## [0.2.0] - 2024-06-03
10 | ### Added
11 | Add support for Q Business Apps integrated with IdC.
12 | - The gateway registers the Amazon Q Business Microsoft Teams Gateway as an OpenID Connect (OIDC) app with Okta (or other OIDC compliant Identity Providers).
13 | - This registration allows the gateway to invoke the Q Business ChatSync API on behalf of the end-user.
14 | - The gateway provisions an OIDC callback handler for the Identity Provider (IdP) to return an authorization code after the end-user authenticates using the authorization grant flow.
15 | - The callback handler exchanges the authorization code for IAM session credentials through a series of interactions with the IdP, IdC, and AWS Security Token Service (STS).
16 | - The IAM session credentials, which are short-lived (15-minute duration), are encrypted and stored in a DynamoDB table along with the refresh token from the IdP.
17 | - The IAM session credentials are then used to invoke the Q Business ChatSync and PutFeedback APIs.
18 | - If the IAM session credentials expire, the refresh token from the IdP is used to obtain new IAM session credentials without requiring the end-user to sign in again.
19 |
20 |
21 | ## [0.1.1] - 2024-01-11
22 | ### Added
23 | Initial release
24 | - In DMs it responds to all messages
25 | - In channels it responds only to @mentions, and always replies in thread
26 | - Renders answers containing markdown - e.g. headings, lists, bold, italics, tables, etc.
27 | - Provides thumbs up / down buttons to track user sentiment and help improve performance over time
28 | - Provides Source Attribution - see references to sources used by Amazon Q
29 | - Aware of conversation context - it tracks the conversation and applies context
30 | - Aware of multiple users - when it's tagged in a thread, it knows who said what, and when - so it can contribute in context and accurately summarize the thread when asked.
31 | - Process up to 5 attached files for document question answering, summaries, etc.
32 | - Reset and start new conversation in DM channel by using `/new_conversation`
33 |
34 | [Unreleased]: https://github.com/aws-samples/amazon-q-teams-gateway/compare/v0.1.1...develop
35 | [0.1.1]: https://github.com/aws-samples/amazon-q-teams-gateway/releases/tag/v0.1.1
36 | [0.1.0]: https://github.com/aws-samples/amazon-q-teams-gateway/releases/tag/v0.1.0
37 |
--------------------------------------------------------------------------------
/CODE_OF_CONDUCT.md:
--------------------------------------------------------------------------------
1 | ## Code of Conduct
2 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
3 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
4 | opensource-codeofconduct@amazon.com with any additional questions or comments.
5 |
--------------------------------------------------------------------------------
/CONTRIBUTING.md:
--------------------------------------------------------------------------------
1 | # Contributing Guidelines
2 |
3 | Thank you for your interest in contributing to our project. Whether it's a bug report, new feature, correction, or additional
4 | documentation, we greatly value feedback and contributions from our community.
5 |
6 | Please read through this document before submitting any issues or pull requests to ensure we have all the necessary
7 | information to effectively respond to your bug report or contribution.
8 |
9 |
10 | ## Reporting Bugs/Feature Requests
11 |
12 | We welcome you to use the GitHub issue tracker to report bugs or suggest features.
13 |
14 | When filing an issue, please check existing open, or recently closed, issues to make sure somebody else hasn't already
15 | reported the issue. Please try to include as much information as you can. Details like these are incredibly useful:
16 |
17 | * A reproducible test case or series of steps
18 | * The version of our code being used
19 | * Any modifications you've made relevant to the bug
20 | * Anything unusual about your environment or deployment
21 |
22 |
23 | ## Contributing via Pull Requests
24 | Contributions via pull requests are much appreciated. Before sending us a pull request, please ensure that:
25 |
26 | 1. You are working against the latest source on the *main* branch.
27 | 2. You check existing open, and recently merged, pull requests to make sure someone else hasn't addressed the problem already.
28 | 3. You open an issue to discuss any significant work - we would hate for your time to be wasted.
29 |
30 | To send us a pull request, please:
31 |
32 | 1. Fork the repository.
33 | 2. Modify the source; please focus on the specific change you are contributing. If you also reformat all the code, it will be hard for us to focus on your change.
34 | 3. Ensure local tests pass.
35 | 4. Commit to your fork using clear commit messages.
36 | 5. Send us a pull request, answering any default questions in the pull request interface.
37 | 6. Pay attention to any automated CI failures reported in the pull request, and stay involved in the conversation.
38 |
39 | GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
40 | [creating a pull request](https://help.github.com/articles/creating-a-pull-request/).
41 |
42 |
43 | ## Finding contributions to work on
44 | Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
45 |
46 |
47 | ## Code of Conduct
48 | This project has adopted the [Amazon Open Source Code of Conduct](https://aws.github.io/code-of-conduct).
49 | For more information see the [Code of Conduct FAQ](https://aws.github.io/code-of-conduct-faq) or contact
50 | opensource-codeofconduct@amazon.com with any additional questions or comments.
51 |
52 |
53 | ## Security issue notifications
54 | If you discover a potential security issue in this project we ask that you notify AWS/Amazon Security via our [vulnerability reporting page](http://aws.amazon.com/security/vulnerability-reporting/). Please do **not** create a public github issue.
55 |
56 |
57 | ## Licensing
58 |
59 | See the [LICENSE](LICENSE) file for our project's licensing. We will ask you to confirm the licensing of your contribution.
60 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT No Attribution
2 |
3 | Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy of
6 | this software and associated documentation files (the "Software"), to deal in
7 | the Software without restriction, including without limitation the rights to
8 | use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
9 | the Software, and to permit persons to whom the Software is furnished to do so.
10 |
11 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
12 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
13 | FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
14 | COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
15 | IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
16 | CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
17 |
18 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | ## Deprecated
2 | *Q Business Microsoft Teams integration* has been launched during re:invent 2024, please refer the [documentation](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/msteams.html) to know more. This project will no longer be maintained as it duplicates the functionality of official integration.
3 |
4 | # Microsoft Teams gateway for Amazon Q Business
5 | | :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.
6 | |-----------------------------------------|
7 |
8 | **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.
9 |
10 |
11 | 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)](https://aws.amazon.com/blogs/aws/introducing-amazon-q-a-new-generative-ai-powered-assistant-preview)
12 |
13 | 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.
14 |
15 | 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:
16 | - Converse with Amazon Q business expert using Teams Direct Message (DM) to ask questions and get answers based on company data, get help creating new content such as emails, and performing tasks.
17 | - You can also invite it to participate in your team channels.
18 | - In a channel users can ask it questions in a new message, or tag it in a thread at any point. Get it to provide additional data points, resolve a debate, or summarize the conversation and capture next steps.
19 |
20 | It's amazingly powerful. Here's a demo - seeing is believing!
21 |
22 | https://github.com/aws-samples/amazon-q-teams-gateway/assets/10953374/a9bc5f5c-c317-4d93-870e-a9a49b2518e4
23 |
24 | It's easy to deploy in your own AWS Account, and add to your own teams. We show you how below.
25 |
26 | Note: For an illustrated guide on setting up the integration using Microsoft Entra ID, [check this walkthrough](./README_ENTRA_ID.md).
27 |
28 | ### Features
29 | - In DMs it responds to all messages
30 | - Renders answers containing markdown - e.g. headings, lists, bold, italics, tables, etc.
31 | - In channels it responds only to @mentions, and always replies in thread.
32 | - Provides thumbs up / down buttons to track user sentiment and help improve performance over time.
33 | - Provides Source Attribution - see references to sources used by Amazon Q.
34 | - Aware of conversation context - it tracks the conversation and applies context.
35 | - Aware of multiple users - when it's tagged in a thread, it knows who said what, and when - so it can contribute in context and accurately summarize the thread when asked.
36 | - Process up to 5 attached files for document question answering, summaries, etc.
37 | - Reset and start new conversation in DM channel by using `/new_conversation`.
38 |
39 | 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.
40 |
41 | 
42 |
43 | Follow the instructions below to deploy the project to your own AWS account and Teams, and start experimenting!
44 |
45 | ## Deploy the solution
46 |
47 | ### Prerequisites
48 |
49 | 1. 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?](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/))*
50 |
51 | 2. You need to have an Okta Workforce Identity Cloud account. If you haven't signed up yet, see [Signing up for Okta](https://www.okta.com/)
52 |
53 | 3. 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/gs-okta.html)
54 |
55 | 4. 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](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/create-app.html)
56 |
57 | 5. 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/adding-users-groups.html)
58 |
59 | 6. 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](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
60 |
61 | 7. Lastly, you need a [Microsoft account](https://account.microsoft.com/) and a [Microsoft Teams subscription](https://www.microsoft.com/en-us/microsoft-teams/compare-microsoft-teams-business-options-b) 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.
62 |
63 | ### 1. Setup
64 |
65 | #### 1.1 Create an OIDC app integration, for the gateway, in Okta.
66 |
67 | Create the client as a ['Web app'](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm). 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).
68 |
69 | #### 1.2 Create Trusted token issuer in IAM Identity Center
70 |
71 | 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.
72 | Or you can run the below script.
73 |
74 | 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'.
75 |
76 | The script will output trusted token issuer ARN (TTI_ARN) which you will use in the next step.
77 |
78 | ```
79 | export AWS_DEFAULT_REGION=<>
80 | OIDC_ISSUER_URL=<>
81 | bin/create-trusted-token-issuer.sh $OIDC_ISSUER_URL
82 | ```
83 |
84 | #### 1.3 Create Customer managed application in IAM Identity Center
85 |
86 | Create customer managed IdC application by running below script.
87 |
88 | 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.
89 |
90 | The script will output the gateway IdC application ARN (GATEWAY_IDC_ARN) which you will use in the next step.
91 |
92 | ```
93 | export AWS_DEFAULT_REGION=<>
94 | OIDC_CLIENT_ID=<>
95 | TTI_ARN=<>
96 | bin/create-idc-application.sh $OIDC_CLIENT_ID $TTI_ARN
97 | ```
98 |
99 | ### 2. Register a new app in the Microsoft Azure portal
100 |
101 | 1. Go to the Azure Portal: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade and login with your Microsoft account.
102 | 1. Choose **+ New registration**
103 | 1. For **Name**, provide the name for your app, e.g. AMAZON-Q-TEAMS-GATEWAY.
104 | 1. For **Who can use this application or access this API?**, choose **Accounts in this organizational directory only (AWS only - Single tenant)**
105 | 1. Choose **Register**
106 | 1. *Note down the **Application (client) ID** value, and the **Directory (tenant) ID** from the **Overview** page. You'll need them later when asked for **MicrosoftAppId** and **MicrosoftAppTenantId**.*
107 | 1. In the **API permissions** page (on the left navigation menu)
108 | 1. Choose **Add a permission**
109 | 1. Choose **Microsoft Graph**
110 | 1. Choose **Application permissions**
111 | 1. Select **User.Read.All**
112 | 1. Select **ChannelMessage.Read.All**
113 | 1. Select **Team.ReadBasic.All**
114 | 1. Select **Files.Read.All**
115 | 1. Choose **Add permissions**. *This permission allows the app to read data in your organization's directory about the signed in user.*
116 | 1. Remove the original **User.Read - Delegated** permission (use the … menu on the right to choose **Remove permission**)
117 | 1. Choose **✓ Grant admin consent for Default Directory**
118 | 1. In the **Certificates & secrets** page
119 | 1. Choose **+ New client secret**
120 | 1. For **Description**, provide a value such as *\-client-secret*
121 | 1. Choose a value for **Expires**. *NOTE: In production, you'll need to manually rotate your secret before it expires.*
122 | 1. Choose **Add**
123 | 1. *Note down the **Value** (not Secret ID) for your new secret. You'll need it later when asked for **MicrosoftAppPassword**.*
124 | 1. (Optional) Choose **Owners** to add any additional owners for the application.
125 |
126 | ### 3. Deploy the stack
127 | We've made this easy by providing pre-built AWS CloudFormation templates that deploy everything you need in your AWS account.
128 |
129 | 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](./README_DEVELOPERS.md)
130 |
131 | 1. Log into the [AWS console](https://console.aws.amazon.com/) if you are not already.
132 | 2. Choose one of the **Launch Stack** buttons below for your desired AWS region to open the AWS CloudFormation console and create a new stack.
133 | 3. Enter the following parameters:
134 | 1. `Stack Name`: Name your App, e.g. AMAZON-Q-TEAMS-GATEWAY.
135 | 2. `AmazonQAppId`: Your existing Amazon Q business expert application ID (copy from Amazon Q console).
136 | 3. `AmazonQRegion`: Choose the region where you created your Amazon Q business expert application.
137 | 4. `OIDCIdPName`: The name of the OIDC external identity provider ('Okta' and 'Cognito' are explicitly supported, leave empty to use default for others)
138 | 5. `OIDCClientId`: The client ID of OIDC client you created in step 1.1.
139 | 6. `OIDCIssuerURL`: The issuer URL of the OIDC client you created in step 1.1.
140 | 7. `GatewayIdCAppARN`: The application arn of IdC customer managed application you created in step 1.3.
141 | 8. `MicrosoftAppId`: The `MicrosoftAppId` you copied in step 2.
142 | 9. `ContextDaysToLive`: Just leave this as the default (90 days)
143 |
144 |
145 | Region | Easy Deploy Button | Template URL - use to upgrade existing stack to a new release
146 | --- | --- | ---
147 | N. Virginia (us-east-1) | [](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json&stackName=AMAZON-Q-TEAMS-GATEWAY) | https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json
148 | Oregon (us-west-2) | [](https://us-west-2.console.aws.amazon.com/cloudformation/home?region=us-west-2#/stacks/create/review?templateURL=https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json&stackName=AMAZON-Q-TEAMS-GATEWAY) | https://s3.us-west-2.amazonaws.com/aws-ml-blog-us-west-2/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json
149 |
150 |
151 | When your CloudFormation stack status is CREATE_COMPLETE, choose the **Outputs** tab, and keep it open - you'll need it below.
152 |
153 | ### 4. Update OIDC Client Redirect URL.
154 |
155 | 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`.
156 |
157 | ### 5. Register your new app in the Microsoft Bot Framework
158 |
159 | 1. Go to the Microsoft Bot Framework: https://dev.botframework.com/bots/new - login with your Microsoft account.
160 | 1. (Optional) Create and upload a cool custom icon for your new Amazon Q Bot. Or, use this one that I created using [Amazon Bedrock image playground](https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/image-playground?modelId=stability.stable-diffusion-xl-v1)!
161 | 
162 | 1. Enter your prefered **Display name**, **Bot handle**, and **Long description**.
163 | 1. For **Messaging endpoint** copy and paste the value suffixed with `TeamsEventHandlerApiEndpoint` from your Stack outputs tab (from Step 1). *Do not check Enable Streaming Endpoint*.
164 | 1. For **App type**, choose `Single Tenant`.
165 | 1. For **Paste your app ID below to continue**, enter the *MicrosoftAppId* value you noted above.
166 | 1. For **App Tenant ID**, enter the *MicrosoftAppTenantId* value you noted above.
167 | 1. Leave the other values as they are, agree to the terms, and choose **Register**.
168 | 1. On the **Channels** page, under **Add a featured channel** choose **Microsoft Teams**
169 | 1. Choose **Microsoft Teams Commercial (most common)**, and then **Save**.
170 | 1. Agree to the Terms of Service and choose **Agree**
171 |
172 | ### 6. Configure your Secrets in AWS
173 |
174 | #### 6.1 Configure your Teams secrets in order to (1) verify the signature of each request, (2) post on behalf of your bot
175 |
176 | > **IMPORTANT**
177 | > In this example we are not enabling app secret rotation. Enable it for a production app by implementing
178 | > rotation via AWS Secrets Manager.
179 | > Please create an issue (or, better yet, a pull request!) in this repo if you want this feature added to a future version.
180 |
181 | 1. Login to your AWS console
182 | 2. In your AWS account go to Secret manager, using the URL shown in the stack output suffixed with `TeamsSecretConsoleUrl`.
183 | 3. Choose `Retrieve secret value`
184 | 4. Choose `Edit`
185 | 5. Replace the value of `MicrosoftAppId`, `MicrosoftAppPassword`, and `MicrosoftAppTenantId` with the values you noted in the previous steps.
186 | 6. Choose **Save**
187 |
188 | #### 6.2 Configure OIDC Client Secret in order to exchange the code for token
189 |
190 | 1. Login to your AWS console
191 | 2. In your AWS account go to Secret manager, using the URL shown in the stack output suffixed with `OIDCClientSecretConsoleUrl`.
192 | 3. Choose `Retrieve secret value`
193 | 4. Choose `Edit`
194 | 5. Replace the value of `OidcClientSecret`, you will find those values in the IdP app client configuration.
195 |
196 | ### 7. Finally, deploy into Microsoft Teams
197 |
198 | 1. Go to Developer Portal for Teams: https://dev.teams.microsoft.com/home - login with your Microsoft Teams user account.
199 | 1. Choose Apps (left side pane) and then **+ New app**
200 | 1. For **Name**, enter your bot name.
201 | 1. Enter **Full name** and both short and full **Descriptions** *(you can just use the bot name for them all if you want - just don't leave them empty)*
202 | 1. Enter values for **Developer information** and **App URLs** fields.
203 | 1. *For testing, you can make up values, and URLs like `https://www.anycompany.com/` etc. Use real ones for production.*
204 | 1. For **Application (client) ID*** enter the value of `MicrosoftAppId` from above.
205 | 1. Choose **Save**.
206 | 1. Under **Branding** you can upload my AI generated icons, or different icon(s), or none at all.. it's up to you.
207 | - [Color icon 192x192](./images/QBotIcon.png) / [Outline icon 32x32](./images/QBotIcon-small.png)
208 | 
209 | 1. Under **App features**, choose **Bot**
210 | 1. Select **Enter a bot ID**, and enter the `MicrosoftAppId` from the earlier steps
211 | 1. Under **What can your bot do?**, check **Upload and download files**.
212 | 1. Under **Select the scopes in which people can use this command**, check all 3 boxes (**Personal**, **Team**, and **Group chat**).
213 | 1. Choose **Save**
214 | 1. Choose **Publish**
215 | 1. Choose **Download the app package** to download a zip file to your computer.
216 | 1. Choose **Preview in Teams** to **Microsoft Teams (work or school)** app
217 | 1. From the Microsoft Teams left navigation bar, choose **Apps**, then **Manage your apps**, then **⤒ Upload an app**
218 | 1. Choose **Upload an app to your orgs app catalog**, and select the zip file downloaded in the previous step. This adds the app to Teams.
219 | 1. Select the card for your new app and choose **Add**.
220 |
221 | And, now, at last, you can test your bot in Microsoft Teams!
222 |
223 | ### Add your bot to one or more Teams
224 | To use your Amazon Q business expert app in your team channels, first add it to each team:
225 | 1. In the Teams app, select your Team and choose 'Manage team'
226 | 2. In the Apps tab, choose the new Amazon Q app, and Add.
227 |
228 | 
229 |
230 | ### Say hello
231 | > Time to say Hi!
232 |
233 | 1. Go to Teams
234 | 2. Under Apps add your new Amazon Q business expert app to a Chat
235 | 3. Optionally add your app to one or more Team channels
236 | 4. In the app DM chat, say *Hello*. In a team channel, ask it for help with an @mention.
237 | 5. You'll be prompted in DM chat to Sign In with your Okta credentials to authenticate with Amazon Q. Click the button to sign in.
238 | 6. You'll be redirected to browser to sign in with Okta. Once you sign in, you can close the browser window and return to Microsoft Teams.
239 | 7. You're now authenticated and can start asking questions!
240 | 8. Enjoy.
241 |
242 | ## Contributing, and reporting issues
243 |
244 | We welcome your contributions to our project. Whether it's a bug report, new feature, correction, or additional
245 | documentation, we greatly value feedback and contributions from our community.
246 |
247 | See [CONTRIBUTING](CONTRIBUTING.md) for more information.
248 |
249 | ## Security
250 |
251 | See [Security issue notifications](CONTRIBUTING.md#security-issue-notifications) for more information.
252 |
253 | ## License
254 |
255 | This library is licensed under the MIT-0 License. See the [LICENSE](./LICENSE) file.
256 |
--------------------------------------------------------------------------------
/README_DEVELOPERS.md:
--------------------------------------------------------------------------------
1 | # Developer README
2 |
3 | The main README is here: [Microsoft Teams gateway for Amazon Q, your business expert (preview)](./README.md)
4 |
5 | This Developer README describes how to build the project from the source code - for developer types. You can:
6 | - [Deploy the solution](#deploy-the-solution)
7 | - [Publish the solution](#publish-the-solution)
8 |
9 | ### 1. Dependencies
10 |
11 | To deploy or to publish, you need to have the following packages installed on your computer:
12 |
13 | 1. bash shell (Linux, MacOS, Windows-WSL)
14 | 2. node and npm: https://docs.npmjs.com/downloading-and-installing-node-js-and-npm
15 | 3. tsc (typescript): `npm install -g typescript`
16 | 4. esbuild: `npm i -g esbuild`
17 | 5. jq: https://jqlang.github.io/jq/download/
18 | 6. aws (AWS CLI): https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html
19 | 7. cdk (AWS CDK): https://docs.aws.amazon.com/cdk/v2/guide/cli.html
20 |
21 | Copy the GitHub repo to your computer. Either:
22 | - use the git command: git clone https://github.com/aws-samples/amazon-q-teams-gateway.git
23 | - OR, download and expand the ZIP file from the GitHub page: https://github.com/aws-samples/amazon-q-teams-gateway/archive/refs/heads/main.zip
24 |
25 | ### 2. Prerequisites
26 |
27 | 1. 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?](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account/))*
28 |
29 | 2. You need to have an Okta Workforce Identity Cloud account. If you haven't signed up yet, see [Signing up for Okta](https://www.okta.com/)
30 |
31 | 3. 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](https://docs.aws.amazon.com/singlesignon/latest/userguide/gs-okta.html)
32 |
33 | 4. 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](https://docs.aws.amazon.com/amazonq/latest/business-use-dg/create-app.html)
34 |
35 | 5. 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](https://docs.aws.amazon.com/amazonq/latest/qbusiness-ug/adding-users-groups.html)
36 |
37 | 6. 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](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html)
38 |
39 | 7. Lastly, you need a [Microsoft account](https://account.microsoft.com/) and a [Microsoft Teams subscription](https://www.microsoft.com/en-us/microsoft-teams/compare-microsoft-teams-business-options-b) 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.
40 |
41 | ## Deploy the solution
42 |
43 | ### 1. Setup
44 |
45 | #### 1.1 Create an OIDC app integration, for the gateway, in Okta.
46 |
47 | Create the client as a ['Web app'](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm). 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).
48 |
49 | #### 1.2 Create Trusted token issuer in IAM Identity Center
50 |
51 | 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.
52 | Or you can run the below script.
53 |
54 | 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'.
55 |
56 | The script will output trusted token issuer ARN (TTI_ARN) which you will use in the next step.
57 |
58 | ```
59 | export AWS_DEFAULT_REGION=<>
60 | OIDC_ISSUER_URL=<>
61 | bin/create-trusted-token-issuer.sh $OIDC_ISSUER_URL
62 | ```
63 |
64 | #### 1.3 Create Customer managed application in IAM Identity Center
65 |
66 | Create customer managed IdC application by running below script.
67 |
68 | 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.
69 |
70 | The script will output the gateway IdC application ARN (GATEWAY_IDC_ARN) which you will use in the next step.
71 |
72 | ```
73 | export AWS_DEFAULT_REGION=<>
74 | OIDC_CLIENT_ID=<>
75 | TTI_ARN=<>
76 | bin/create-idc-application.sh $OIDC_CLIENT_ID $TTI_ARN
77 | ```
78 |
79 | ### 2. Register a new app in the Microsoft Azure portal
80 |
81 | 1. Go to the Azure Portal: https://portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade and login with your Microsoft account.
82 | 1. Choose **+ New registration**
83 | 1. For **Name**, provide the name for your app, e.g. AMAZON-Q-TEAMS-GATEWAY.
84 | 1. For **Who can use this application or access this API?**, choose **Accounts in this organizational directory only (AWS only - Single tenant)**
85 | 1. Choose **Register**
86 | 1. *Note down the **Application (client) ID** value, and the **Directory (tenant) ID** from the **Overview** page. You'll need them later when asked for **MicrosoftAppId** and **MicrosoftAppTenantId**.*
87 | 1. In the **API permissions** page (on the left navigation menu)
88 | 1. Choose **Add a permission**
89 | 1. Choose **Microsoft Graph**
90 | 1. Choose **Application permissions**
91 | 1. Select **User.Read.All**
92 | 1. Select **ChannelMessage.Read.All**
93 | 1. Select **Team.ReadBasic.All**
94 | 1. Select **Files.Read.All**
95 | 1. Choose **Add permissions**. *This permission allows the app to read data in your organization's directory about the signed in user.*
96 | 1. Remove the original **User.Read - Delegated** permission (use the … menu on the right to choose **Remove permission**)
97 | 1. Choose **✓ Grant admin consent for Default Directory**
98 | 1. In the **Certificates & secrets** page
99 | 1. Choose **+ New client secret**
100 | 1. For **Description**, provide a value such as *\-client-secret*
101 | 1. Choose a value for **Expires**. *NOTE: In production, you'll need to manually rotate your secret before it expires.*
102 | 1. Choose **Add**
103 | 1. *Note down the **Value** (not Secret ID) for your new secret. You'll need it later when asked for **MicrosoftAppPassword**.*
104 | 1. (Optional) Choose **Owners** to add any additional owners for the application.
105 |
106 | ### 3. Initialize and deploy the stack
107 |
108 | Navigate into the project root directory and, in a bash shell, run:
109 |
110 | 1. `./init.sh` - checks your system dependencies for required packages (see Dependencies above), sets up your environment file, and bootstraps your cdk environment.
111 | 2. `./deploy.sh` - runs the cdk build and deploys or updates a stack in your AWS account, and outputs value that you'll need in the next section:
112 | - url for EventHandler API endpoint
113 | - links to the AWS Secrets Manager secrets
114 |
115 | ### 4. Update OIDC Client Redirect URL.
116 |
117 | 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`.
118 |
119 | ### 5. Register your new app in the Microsoft Bot Framework
120 |
121 | 1. Go to the Microsoft Bot Framework: https://dev.botframework.com/bots/new - login with your Microsoft account.
122 | 1. (Optional) Create and upload a cool custom icon for your new Amazon Q Bot. Or, use this one that I created using [Amazon Bedrock image playground](https://us-east-1.console.aws.amazon.com/bedrock/home?region=us-east-1#/image-playground?modelId=stability.stable-diffusion-xl-v1)!
123 |
124 | 1. Enter your prefered **Display name**, **Bot handle**, and **Long description**.
125 | 1. For **Messaging endpoint** copy and paste the value suffixed with `TeamsEventHandlerApiEndpoint` from your Stack outputs tab (from Step 1). *Do not check Enable Streaming Endpoint*.
126 | 1. For **App type**, choose `Single Tenant`.
127 | 1. For **Paste your app ID below to continue**, enter the *MicrosoftAppId* value you noted above.
128 | 1. For **App Tenant ID**, enter the *MicrosoftAppTenantId* value you noted above.
129 | 1. Leave the other values as they are, agree to the terms, and choose **Register**.
130 | 1. On the **Channels** page, under **Add a featured channel** choose **Microsoft Teams**
131 | 1. Choose **Microsoft Teams Commercial (most common)**, and then **Save**.
132 | 1. Agree to the Terms of Service and choose **Agree**
133 |
134 | ### 6. Configure your Secrets in AWS
135 |
136 | #### 6.1 Configure your Teams secrets in order to (1) verify the signature of each request, (2) post on behalf of your bot
137 |
138 | > **IMPORTANT**
139 | > In this example we are not enabling app secret rotation. Enable it for a production app by implementing
140 | > rotation via AWS Secrets Manager.
141 | > Please create an issue (or, better yet, a pull request!) in this repo if you want this feature added to a future version.
142 |
143 | 1. Login to your AWS console
144 | 2. In your AWS account go to Secret manager, using the URL shown in the stack output suffixed with `TeamsSecretConsoleUrl`.
145 | 3. Choose `Retrieve secret value`
146 | 4. Choose `Edit`
147 | 5. Replace the value of `MicrosoftAppId`, `MicrosoftAppPassword`, and `MicrosoftAppTenantId` with the values you noted in the previous steps.
148 | 6. Choose **Save**
149 |
150 | #### 6.2 Configure OIDC Client Secret in order to exchange the code for token
151 |
152 | 1. Login to your AWS console
153 | 2. In your AWS account go to Secret manager, using the URL shown in the stack output suffixed with `OIDCClientSecretConsoleUrl`.
154 | 3. Choose `Retrieve secret value`
155 | 4. Choose `Edit`
156 | 5. Replace the value of `OidcClientSecret`, you will find those values in the IdP app client configuration.
157 |
158 | ### 7. Finally, deploy into Microsoft Teams
159 |
160 | 1. Go to Developer Portal for Teams: https://dev.teams.microsoft.com/home - login with your Microsoft Teams user account.
161 | 1. Choose Apps (left side pane) and then **+ New app**
162 | 1. For **Name**, enter your bot name.
163 | 1. Enter **Full name** and both short and full **Descriptions** *(you can just use the bot name for them all if you want - just don't leave them empty)*
164 | 1. Enter values for **Developer information** and **App URLs** fields.
165 | 1. *For testing, you can make up values, and URLs like `https://www.anycompany.com/` etc. Use real ones for production.*
166 | 1. For **Application (client) ID*** enter the value of `MicrosoftAppId` from above.
167 | 1. Choose **Save**.
168 | 1. Under **Branding** you can upload my AI generated icons, or different icon(s), or none at all.. it's up to you.
169 | - [Color icon 192x192](./images/QBotIcon.png) / [Outline icon 32x32](./images/QBotIcon-small.png)
170 |
171 | 1. Under **App features**, choose **Bot**
172 | 1. Select **Enter a bot ID**, and enter the `MicrosoftAppId` from the earlier steps
173 | 1. Under **What can your bot do?**, check **Upload and download files**.
174 | 1. Under **Select the scopes in which people can use this command**, check all 3 boxes (**Personal**, **Team**, and **Group chat**).
175 | 1. Choose **Save**
176 | 1. Choose **Publish**
177 | 1. Choose **Download the app package** to download a zip file to your computer.
178 | 1. Choose **Preview in Teams** to **Microsoft Teams (work or school)** app
179 | 1. From the Microsoft Teams left navigation bar, choose **Apps**, then **Manage your apps**, then **⤒ Upload an app**
180 | 1. Choose **Upload an app to your orgs app catalog**, and select the zip file downloaded in the previous step. This adds the app to Teams.
181 | 1. Select the card for your new app and choose **Add**.
182 |
183 | And, now, at last, you can test your bot in Microsoft Teams!
184 |
185 | ### Add your bot to one or more Teams
186 | To use your Amazon Q business expert app in your team channels, first add it to each team:
187 | 1. In the Teams app, select your Team and choose 'Manage team'
188 | 2. In the Apps tab, choose the new Amazon Q app, and Add.
189 |
190 | 
191 |
192 | ### Say hello
193 | > Time to say Hi!
194 |
195 | 1. Go to Teams
196 | 2. Under Apps add your new Amazon Q business expert app to a Chat
197 | 3. Optionally add your app to one or more Team channels
198 | 4. In the app DM chat, say *Hello*. In a team channel, ask it for help with an @mention.
199 | 5. You'll be prompted in DM chat to Sign In with your Okta credentials to authenticate with Amazon Q. Click the button to sign in.
200 | 6. You'll be redirected to browser to sign in with Okta. Once you sign in, you can close the browser window and return to Microsoft Teams.
201 | 7. You're now authenticated and can start asking questions!
202 | 8. Enjoy.
203 |
204 | ## Publish the solution
205 |
206 | In our main README, you will see that we provided Easy Deploy Buttons to launch a stack using pre-built templates that we published already to an S3 bucket.
207 |
208 | If you want to build and publish your own template, to your own S3 bucket, so that others can easily use a similar easy button approach to deploy a stack, using *your* templates, here's how.
209 |
210 | Navigate into the project root directory and, in a bash shell, run:
211 |
212 | 1. `./publish.sh `.
213 | This:
214 | - checks your system dependencies for required packages (see Dependencies above)
215 | - bootstraps your cdk environment if needed
216 | - creates a standalone CloudFormation template (that doesn't depend on CDK)
217 | - publishes the template and required assets to an S3 bucket in your account called `cfn_bucket_basename-region` (it creates the bucket if it doesn't already exist)
218 | - optionally add a final parameter `public` if you want to make the templates public. Note: your bucket and account must be configured not to Block Public Access using new ACLs.
219 |
220 | That's it! There's just one step.
221 |
222 | When completed, it displays the CloudFormation templates S3 URLs and 1-click URLs for launching the stack creation in CloudFormation console, e.g.:
223 | ```
224 | OUTPUTS
225 | Template URL: https://s3.us-east-1.amazonaws.com/yourbucketbasename-us-east-1/qteams-test/AmazonQTeamsGateway.json
226 | CF Launch URL: https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3.us-east-1.amazonaws.com/yourbucketbasename-us-east-1/qteams-test/AmazonQTeamsGateway.json&stackName=AMAZON-Q-TEAMS-GATEWAY
227 | Done
228 | ``````
229 |
230 | Follow the deployment directions in the main [README](./README.md), but use your own CF Launch URL instead of our pre-built templates (Launch Stack buttons).
231 |
232 |
233 | ## Contributing, and reporting issues
234 |
235 | We welcome your contributions to our project. Whether it's a bug report, new feature, correction, or additional
236 | documentation, we greatly value feedback and contributions from our community.
237 |
238 | See [CONTRIBUTING](CONTRIBUTING.md) for more information.
239 |
240 | ## Security
241 |
242 | See [Security issue notifications](CONTRIBUTING.md#security-issue-notifications) for more information.
243 |
244 | ## License
245 |
246 | This library is licensed under the MIT-0 License. See the [LICENSE](./LICENSE) file.
247 |
--------------------------------------------------------------------------------
/README_ENTRA_ID.md:
--------------------------------------------------------------------------------
1 | # Integrating Amazon Q Business with Microsoft Teams using Microsoft Entra ID
2 |
3 | ## Contributors
4 |
5 | - Bartosz Wieciech
6 | - Md Arshad Ahmed
7 |
8 |
9 | ## Prerequisites
10 |
11 | - Microsoft Business 365 account and access to the Azure cloud tied with it
12 | - IAM Identity Center enabled in the AWS account
13 | - Amazon Q Business application created
14 | - Ability to run CloudFormation scripts
15 |
16 |
17 | ## Values template
18 |
19 | During the process you will have to note down several values. Because it is easy to mix up which one is which, this
20 | template is meant to be an aid for you to keep track of them. Values will be referenced both by name, as well
21 | highlighted with a dedicated colour. Delete the placeholder values, they are there just to show you what types of
22 | strings you should expect.
23 |
24 | AMAZON_Q_APP_ID: c6dd7f1c-6f...
25 | OIDC_SECRET: op8Qh_hjID3-HGWu...
26 | OIDC_URL: https://login.microsoftonline.com/8f...5/v2.0
27 | OIDC_CLIENT_ID: 9d881ada-5882-4fcc...
28 | TTI_ARN: arn:aws:sso::...:trustedTokenIssuer/ssoins-.../tti-a498f458...
29 | GATEWAY_IDC_ARN: arn:aws:sso::...:application/ssoins-.../apl-00702...
30 | GATEWAY_CLIENT_ID: a5cb05c1-ed51-47...
31 | GATEWAY_TENANT_ID: 8f15c65e-f8e5-4b...
32 | GATEWAY_SECRET: pyd8QZOo_A3...
33 |
34 |
35 | ## Steps
36 |
37 | ### Note down your Amazon Q app ID
38 |
39 | 1. In the AWS console, go to _Amazon Q Business_
40 | 2. Select the application you wish to integrate with Microsoft Teams
41 | 
42 | 3. Note down the value of Application ID as **AMAZON_Q_APP_ID**
43 | 
44 |
45 |
46 | ### Register OIDC in Microsoft Entra ID (ex Active Directory)
47 |
48 | 1. Open https://portal.azure.com/ and log in using a user with permissions to add new app registrations in
49 | _Microsoft Entra ID_
50 | 2. Go to Microsoft Entra ID
51 | 
52 | 3. Click _+Add_ → _App registration_
53 | 
54 | 4. Give the OIDC app a name (e.g. _Tutorial-OIDC-Application_). For account type, select _Single tenant_.
55 | For the redirect URL, choose _Web_ and enter a placeholder value (e.g. [https://localhost](https://localhost/)) which
56 | we will later change
57 | 
58 | 5. Click _Register_
59 | 
60 | 6. You will be redirected to the page of your newly-created app registration. On the left pane, under _Manage_,
61 | select _Certificates & secrets_
62 | 
63 | 7. Click _+ Create client secret_
64 | 
65 | 8. Give the secret a name and time to live and click _Add_
66 | 
67 | 9. Note down the secret value (**not** Secret ID) under **OIDC_SECRET**
68 | 
69 | 10. In the _Overview_ section of the application (left pane), click on _Endpoints_
70 | 
71 | 11. Copy the value under _OpenID Connect metadata document_ up to v2.0 (i.e. discard /well-known/openid-configuration),
72 | and write it down under **OIDC_URL**
73 | 
74 | 12. On the left pane, select _Authentication_
75 | 
76 | 13. Scroll to the _Implicit grant and hybrid flows_ section and select _ID tokens (used for implicit and hybrid flows)_.
77 | Confirm by clicking _Save_
78 | 
79 | 14. In the Overview section of the OIDC application, note down the value of _Application (client) ID_ under
80 | **OIDC_CLIENT_ID**
81 |
82 |
83 | ### Create trusted token issuer in IAM Identity Center
84 |
85 | 1. Open a terminal through which you are able to interact with the relevant AWS account (e.g. by generating temporary
86 | security credentials). Clone [this Git repository](https://github.com/aws-samples/amazon-q-teams-gateway) by running:
87 | ```
88 | git clone https://github.com/aws-samples/amazon-q-teams-gateway.git
89 | ```
90 | 2. Change the directory to the cloned repository by running:
91 | ```
92 | cd amazon-q-teams-gateway
93 | ```
94 | 3. Run the following lines:
95 | ```
96 | export AWS_DEFAULT_REGION=''
97 | export OIDC_ISSUER_URL='**OIDC_URL**'
98 | ./bin/create-trusted-token-issuer.sh $OIDC_ISSUER_URL
99 | ```
100 | 4. The output of the script will be a value in the form of **TTI_ARN=arn:aws:sso...** which you should note down under
101 | **TTI_ARN** *without* the TTI_ARN= prefix (i.e. you should note
102 | down arn:aws:sso...)
103 | 5. Run the following commands, replacing **TTI_ARN** and
104 | **OIDC_CLIENT_ID** with their respective values
105 | ```
106 | export TTI_ARN='**TTI_ARN**'
107 | export OIDC_CLIENT_ID='**OIDC_CLIENT_ID**'
108 | ./bin/create-idc-application.sh $OIDC_CLIENT_ID $TTI_ARN
109 | ```
110 | 6. You should see an output similar to the below:
111 | > Created GATEWAY_IDC_ARN: arn:aws:sso::...:application/ssoins-.../apl-00702... is setup with GATEWAY_IDC_ARN:
112 | > arn:aws:sso::...:application/ssoins-.../apl-00702...
113 | 7. Note down the value of **GATEWAY_IDC_ARN**
114 |
115 |
116 | ### Register the Microsoft Teams Gateway in Microsoft Entra ID (ex Active Directory)
117 |
118 | 1. Open https://portal.azure.com/ and log in using a user with permissions to add new app registrations in Microsoft
119 | Entra ID
120 | 2. Go to _Microsoft Entra ID_
121 | 
122 | 3. Click _+Add_ → _App registration_
123 | 
124 | 4. Give the OIDC app a name (e.g. _Tutorial-Amazon-Q-Teams-Gateway_). For account type, select _Single tenant_. For the
125 | redirect URL. Leave other fields unchanged. Confirm by clicking _Register_.
126 | 
127 | 5. You will be redirected to the page of your newly-created application. Note down the values of _Application (client)
128 | ID_ as **GATEWAY_CLIENT_ID**, and _Directory (tenant) ID_ as
129 | **GATEWAY_TENANT_ID**.
130 | 
131 | 6. On the left pane, select _API permissions_
132 | 
133 | 7. Click _+ Add a permission_
134 | 
135 | 8. Click _Microsoft Graph_
136 | 
137 | 9. Click _Application permissions_
138 | 
139 | 10. Select the following permissions:
140 | * User.Read.All
141 | * ChannelMessage.Read.All
142 | * Team.ReadBasic.All
143 | * Files.Read.All
144 | 11. Confirm by clicking _Add permissions_
145 | 
146 | 12. Remove the _User.Read_ delegated permission (**not** _User.Read.All_, which you have just added) by clicking "..."
147 | → _Remove permission_. Confirm when prompted.
148 | 
149 | 
150 | 13. Click _Grant admin consent for _. Confirm when prompted. Green ticks should appear, for
151 | the permissions you have added, in the status column.
152 | 
153 | 
154 | 
155 | 14. On the left pane, under _Manage_, select _Certificates & secrets_
156 | 
157 | 15. Click _+ New client secret_
158 | 
159 | 16. Give the secret a name and time to live and click _Add_
160 | 
161 | 17. Note down the secret value (_not_ Secret ID) under **GATEWAY_SECRET**
162 | 
163 |
164 |
165 | ### Deploy CloudFormation stack
166 |
167 | 1. Make sure you are logged in to the appropriate AWS account and have permissions necessary to run CloudFormation
168 | 2. Click on the [following link](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://s3.us-east-1.amazonaws.com/aws-ml-blog-us-east-1/artifacts/amazon-q-teams-gateway/AmazonQTeamsGateway.json&stackName=AMAZON-Q-TEAMS-GATEWAY)
169 | 3. Configure the parameters as following:
170 | - **Stack name**: e.g. _AMAZON-Q-TEAMS-GATEWAY_
171 | - **AmazonQAppId**: value of **AMAZON_Q_APP_ID**
172 | - **AmazonQRegion**: whichever region you are using, e.g. _us-east-1_
173 | - **ContextDaysToLive**: (default: 90) number of days to keep the conversation context
174 | - **GatewayIdcAppARN**: value of **GATEWAY_IDC_ARN**
175 | - **MicrosoftAppId**: value of **GATEWAY_CLIENT_ID**
176 | - **OIDCClientId**: value of **OIDC_CLIENT_ID**
177 | - **OIDCIdPName**: type _Other_
178 | - **OIDCIssuerURL**: value of **OIDC_URL**
179 |
180 | 
181 | 4. Acknowledge the capabilities and click _Create stack_. Grab a coffee and wait until the creation process has finished
182 | (takes about 10 minutes).
183 | 
184 | 5. After the stack is created, go to _Outputs_ and copy the value of the key ending with
185 | _OIDCCallbackEndpointExportedName_
186 | 
187 | 6. Open https://portal.azure.com/ and go to the OIDC application registration page (e.g. _Tutorial-OIDC-Application_)
188 | 7. Click on the value next to Redirect URIs
189 | 
190 | 8. Change the placeholder you have created in the
191 | [Register OIDC in Microsoft Entra ID (ex Active Directory)](#register-oidc-in-microsoft-entra-id-ex-active-directory)
192 | section to the URL you have copied:
193 | - **BEFORE**
194 | 
195 | - **AFTER** (your URL will differ)
196 | 
197 | 9. Hit _Save_
198 | 
199 |
200 |
201 | ### Updating Secrets in the AWS console
202 |
203 | 1. In the Outputs tab of your stack, click on the value associated with _...TeamsSecretConsoleUrl_
204 | 
205 | 2. Under _Secret value_, select _Retrieve secret value_
206 | 
207 | 3. Click _Edit_
208 | 
209 | 4. Fill in the following values and hit _Save_:
210 | - **MicrosoftAppId**: value of **GATEWAY_CLIENT_ID**
211 | - **MicrosoftAppPassword**: value of **GATEWAY_SECRET**
212 | - **MicrosoftAppTenantId**: value of **GATEWAY_TENANT_ID**
213 |
214 | 
215 | 5. In the Outputs tab of your stack, click on the value associated with _...OIDCClientSecretConsoleUrl_
216 | 
217 | 6. Retrieve and edit secret values
218 | 7. Set **OIDCClientSecret** to the value of **OIDC_SECRET** and hit
219 | _Save_
220 | 
221 |
222 |
223 | ### Register bot
224 |
225 | 1. From the output of your CloudFormation stack creation process, copy the value associated with
226 | _...TeamsEventHandlerApiEndpoint..._
227 | 
228 | 2. Go to https://dev.botframework.com/bots/new and log in using your MS account
229 | 3. Fill in the necessary values:
230 | - **Display name**
231 | - **Bot handle**: A bot handle represents a bot's registration with the online Azure AI Bot Service and cannot be changed
232 | - **Messaging endpoint**: paste the value copied from the first point, i.e. the one associated with
233 | _...TeamsEventHandlerApiEndpoint..._
234 | - Change the _App type_ to _Single Tenant_
235 | - For _Paste your app ID below to continue_, paste the value of **GATEWAY_CLIENT_ID**
236 | - For _App Tenant ID_, paste the value of **GATEWAY_TENANT_ID**
237 | 
238 | 4. Select the checkbox to acknowledge the terms and click _Register_
239 | 
240 | 5. You will be redirected to the page of your bot. You must connect it to the MS Teams channel. This can either be
241 | present in the _Add a featured channel_ section, or in _More channels_
242 | 
243 | 6. For messaging, you are likely to select _Microsoft Teams Commercial_. Hit _Save_.
244 | 
245 | 7. Select the checkbox to acknowledge the terms and click the _Agree_ button
246 | 
247 |
248 |
249 | ### Register Microsoft Teams application
250 |
251 | 1. Go to https://dev.teams.microsoft.com/ and log in using an account with permissions to add MS Teams apps
252 | 2. Go to the _Apps_ tab
253 | 
254 | 3. Click _+ New app_
255 | 
256 | 
257 | 4. Give the app a name. **The name must be globally unique**. Hit the _Add_ button (yes, the colour may appear as if it
258 | was inactive, especially when using dark mode `:)`)
259 | 
260 | 5. Do not change the App ID. For obligatory fields like _Short description_, _Long description_, _Developer or company
261 | name_, _Website_, _Privacy policy_ and _Terms of use_ fill in your customer’s details, or use placeholders if you’re
262 | just playing around.
263 | 
264 | 6. For the _Application (client) ID_, fill the value of **GATEWAY_CLIENT_ID**
265 | and hit _Save_
266 | 
267 | 7. Under _Configure_ → _App features_ on the left pane, select _Bot_
268 | 
269 | 8. In _Identify your bot_, select _Enter a bot ID_ and paste the value of **GATEWAY_CLIENT_ID**.
270 | For _What can your bot do?_, select _Upload and download files_. For Select the scopes where people can use your bot,
271 | select _Personal_, _Team_ and _Group Chat_ (or fewer scopes, if you wish). Save the changes.
272 | 
273 | 9. Click on _Publish_ in the top-right corner. Then select _Download the app package_.
274 | 
275 | 
276 | 10. Open your Microsoft Teams application or go to https://teams.microsoft.com/
277 | 11. On the left pane, choose _Apps_
278 | 
279 | 12. From the bottom-left, choose _Manage your apps_, and upload an app
280 | 
281 | 
282 | 13. Choose _Upload an app to your organisation’s app catalogue_
283 | 
284 | 14. Select the app package you have previously downloaded
285 | 15. After the app is uploaded, click _Add_ next to the application name. A popup will appear. Click _Add_ again.
286 | 
287 | 
288 | 16. You can now start chatting with Amazon Q (make sure you have synced the data sources and/or allowed reverting to
289 | the LLM’s internal knowledge). Your first message will result in an option to authenticate.
290 | 
291 |
--------------------------------------------------------------------------------
/bin/convert-cfn-template.js:
--------------------------------------------------------------------------------
1 | const { S3Client, PutObjectCommand } = require('@aws-sdk/client-s3');
2 | const fs = require('fs');
3 | const path = require('path');
4 | const JSZip = require('jszip');
5 |
6 | // Read command line arguments
7 | const templateName = process.argv[2];
8 | const destinationBucket = process.argv[3];
9 | const destinationPrefix = process.argv[4];
10 | const awsRegion = process.argv[5];
11 | if (!templateName || !destinationBucket || !destinationPrefix || !awsRegion) {
12 | console.error('Error: All arguments must be provided.');
13 | console.error(
14 | 'Usage: