forked from OfficeDev/Microsoft-Teams-Samples
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request OfficeDev#44 from OfficeDev/yife/meSso
Query and Config ME with SSO
- Loading branch information
Showing
15 changed files
with
5,060 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,134 @@ | ||
| ## Bot SSO Setup | ||
| This document show how to setup AAD and Azure Bot Services, which are the prerequisites steps to enable Bot SSO. | ||
|
|
||
| ### 1. Create and configure AAD app | ||
|
|
||
| #### 1.1 Create AAD app for SSO | ||
|
|
||
| This step will create an AAD app, it will be reused wherever it needs AAD throughout this sample to simpler the steps. | ||
|
|
||
| - Navigate to [Azure _App Registration_ Blade](https://ms.portal.azure.com/#blade/Microsoft_AAD_RegisteredApps/ApplicationsListBlade) | ||
|
|
||
| - Click "New Registration" on the upper left corner | ||
|
|
||
| - Fill out name and select third option for supported account type | ||
| - Set Redirect Uri to "https://token.botframework.com/.auth/web/redirect" and click "Register": | ||
|
|
||
|  | ||
|
|
||
| - Navigate to the AAD app you just created, _copy and paste the Application ID(will referred as **AppId** in this document) somewhere safe_. You'll need it in a future step: | ||
|  | ||
|
|
||
| #### 1.2 Create Client Secret | ||
|
|
||
| - Navigate to the "Certificates & secrets" blade and add a client secret by clicking "New Client Secret" | ||
|
|
||
|  | ||
| </br> | ||
|
|
||
| - _Copy and paste the secret somewhere safe_. You'll need it in a future step | ||
|
|
||
| #### 1.3. Expose API endpoint | ||
|
|
||
| - Click "_Expose an API_" in the left rail | ||
|
|
||
| - Update your application ID URL to include your bot id - api://botid-<AppId>, where <AppId> is the id of the bot that will be making the SSO request and found in your Teams Application Manifest, which is the same you create and saved in step1.1: | ||
|  | ||
|
|
||
| - Click "_Add a scope_" | ||
|
|
||
| - access_as_user as the Scope name. | ||
|
|
||
| - Set Who can consent? to Admins and users | ||
|
|
||
| - Fill in the fields for configuring the admin and user consent prompts with values that are appropriate for the access_as_user scope. Suggestions: | ||
|
|
||
| - Admin consent title: Teams can access the user’s profile | ||
|
|
||
| - Admin consent description: Allows Teams to call the app’s web APIs as the current user. | ||
|
|
||
| - User consent title: Teams can access your user profile and make requests on your behalf | ||
|
|
||
| - User consent description: Enable Teams to call this app’s APIs with the same rights that you have | ||
|
|
||
| - Ensure that State is set to Enabled | ||
|
|
||
| - Select Add scope (Note: The domain part of the Scope name displayed just below the text field should automatically match the Application ID URI set in the previous step, with /access_as_user appended to the end) | ||
|
|
||
|  | ||
|
|
||
| #### 1.4. Authorize client applications | ||
|
|
||
| Add the following Ids as authorized clients for your application | ||
|
|
||
| - 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile/desktop application) | ||
|
|
||
| - 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application) | ||
|
|
||
|  | ||
|
|
||
| #### 1.5. Add any necessary API permissions for downstream calls | ||
|
|
||
| - Navigate to "API permissions" blade on the left hand side | ||
|
|
||
| - Add any user delegated permissions that your app will need to downstream APIs. This quick start only requires User.Read. | ||
|
|
||
|  | ||
|
|
||
| #### 1.6. Enable implicit grant | ||
|
|
||
| - Navigate to "Authentication" | ||
|
|
||
| - Check the *Access tokens* and *ID tokens* boxes.. | ||
|
|
||
| #### 1.7 | ||
| - Navigate to "Manifest" | ||
| - Confirm the config item: `"accessTokenAcceptedVersion": 2`, if not, change its value to 2, click "save". (If you are already in testing your bot in Teams, you need to signout this app and signout Teams then signin again to see this change work). | ||
|
|
||
|
|
||
| ### 2. Setup bot in Azure Bot Service | ||
|
|
||
| #### 2.1. Run ngrok - point to port 3978 | ||
|
|
||
| ```bash | ||
| ngrok http -host-header=rewrite 3978 | ||
| ``` | ||
|
|
||
| #### 2.2. Create new Bot Channel Registration resource in Azure | ||
|
|
||
| Create [Bot Channels registration resource](https://docs.microsoft.com/en-us/azure/bot-service/bot-service-quickstart-registration) in Azure | ||
| - For the "_Messaging endpoint_", use the current `https` URL you were given by running ngrok. Append with the path `/api/messages`: | ||
| - For "Microsoft App ID and password", click "Create New", fill in the AppId and client secret you created in step1.1 and step 1.2: | ||
|  | ||
|
|
||
|  | ||
|
|
||
| - After you select *Create*, it will take a few moments for your bot service to be provisioned. Once you see a notification indicating the validation process is complete, navigate back to *Home > Bot Services* to find your bot. You may have to refresh the page to see your bot listed. | ||
| - Ensure that you've [enabled the Teams Channel](https://docs.microsoft.com/en-us/azure/bot-service/channel-connect-teams?view=azure-bot-service-4.0) | ||
|
|
||
| ### 3. Setup Bot Service Connection (TokenStore) | ||
|
|
||
| - In the Azure Portal, navigate back to the Bot Channels Registration created in Step 2 | ||
|
|
||
|
|
||
| - Switch to the "Settings" blade and click "Add Setting" under the OAuth Connection Settings section | ||
|
|
||
|  | ||
|
|
||
| - Fill out the Connection Setting form | ||
|
|
||
| - Enter a name for your new Connection setting. This will be the name that gets referenced inside the settings of your bot service code in step 5 | ||
|
|
||
| - In the Service Provider dropdown, select Azure Active Directory V2 | ||
|
|
||
| - Enter in the client id and client secret obtained in step 2 | ||
|
|
||
| - For the Token Exchange URL use the Application ID URL obtained in step 2 | ||
|
|
||
| - Specify "common" as the Tenant ID | ||
|
|
||
| - Add all the scopes configured when specifying permissions to downstream APIs in step 2 | ||
|
|
||
| - Click "Save" | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| MicrosoftAppId= | ||
| MicrosoftAppPassword= | ||
| connectionName= | ||
| SiteUrl= |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| # Teams Search SSO Config Bot | ||
|
|
||
| Bot Framework v4 sample for Teams expands the [52.teams-messaging-extensions-search-auth-config](https://github.com/microsoft/BotBuilder-Samples/tree/main/samples/javascript_nodejs/52.teams-messaging-extensions-search-auth-config) sample to include a configuration page and Bot Service SSO authentication. | ||
|
|
||
| This bot has been created using [Bot Framework](https://dev.botframework.com), it shows how to use a Messaging Extension configuration page, as well as how to sign in from a search Messaging Extension. | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Microsoft Teams is installed and you have an account | ||
| - [NodeJS](https://nodejs.org/en/) | ||
| - [ngrok](https://ngrok.com/) or equivalent tunnelling solution | ||
|
|
||
| ## To try this sample | ||
|
|
||
| > Note these instructions are for running the sample on your local machine, the tunnelling solution is required because | ||
| the Teams service needs to call into the bot. | ||
|
|
||
| ### 1. Setup for Bot SSO | ||
| Refer to [Bot SSO Setup document](../../../BotSSOSetup.md). | ||
|
|
||
| ### 2. Configure this sample | ||
|
|
||
| Update the `.env` configuration for the bot to use the Microsoft App Id and App Password from the Bot Framework registration. The `SiteUrl` is the URL that generated by ngrok and start with "https". (Note the MicrosoftAppId is the AppId created in step 1.1, the MicrosoftAppPassword is referred to as the "client secret" in step1.2 and you can always create a new client secret anytime.) | ||
|
|
||
| ### 3. Run your bot sample | ||
| Under the root of this sample folder, build and run by commands: | ||
| - `npm install` | ||
| - `npm start` | ||
|
|
||
| ### 4. Configure and run the Teams app | ||
| - **Using App Studio** | ||
| - Open your app in App Studio's manifest editor. | ||
| - Open the *Bots* page under *Capabilities*. | ||
| - Choose *Setup*, then choose the existing bot option. Enter your AAD app registration ID from step 1.1. Select any of the scopes you wish to have the bot be installed. | ||
| - Open *Domains and permissions* from under *Finish*. Enter the same ID from the step above in *AAD App ID*, then and append it to "api://botid-" and enter the URI into *Single-Sign-On*. | ||
| - Open *Test and distribute*, then select *Install*. | ||
|
|
||
| - **Manually update the manifest.json** | ||
| - Edit the `manifest.json` contained in the `appPackage/` folder to replace with your MicrosoftAppId (that was created in step1.1 and is the same value of MicrosoftAppId in `.env` file) *everywhere* you see the place holder string `{TODO: MicrosoftAppId}` (depending on the scenario the Microsoft App Id may occur multiple times in the `manifest.json`) | ||
| - Zip up the contents of the `appPackage/` folder to create a `manifest.zip` | ||
| - Upload the `manifest.zip` to Teams (in the left-bottom *Apps* view, click "Upload a custom app") | ||
|
|
||
| - **Interacting with the Message Extension in Teams | ||
| Once the Messaging Extension is installed, find the icon for **Config Auth Search** in the Compose Box's Messaging Extension menu. Right click to choose **Settings** and view the Config page. Click the icon to display the search window, type anything it will show your profile picture. | ||
| ## Deploy the bot to Azure | ||
|
|
||
| To learn more about deploying a bot to Azure, see [Deploy your bot to Azure](https://aka.ms/azuredeployment) for a complete list of deployment instructions. | ||
|
|
||
| ## Further reading | ||
|
|
||
| - [How Microsoft Teams bots work](https://docs.microsoft.com/en-us/azure/bot-service/bot-builder-basics-teams?view=azure-bot-service-4.0&tabs=javascript) |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
116 changes: 116 additions & 0 deletions
116
samples/msgext-search-sso-config/appPackage/manifest.json
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| { | ||
| "$schema": "https://developer.microsoft.com/en-us/json-schemas/teams/v1.8/MicrosoftTeams.schema.json", | ||
| "manifestVersion": "1.8", | ||
| "version": "1.0.2", | ||
| "id": "{TODO: MicrosoftAppId}", | ||
| "packageName": "com.microsoft.teams.samples.msgExt", | ||
| "developer": { | ||
| "name": "Microsoft", | ||
| "websiteUrl": "https://dev.botframework.com", | ||
| "privacyUrl": "https://dev.botframework.com", | ||
| "termsOfUseUrl": "https://dev.botframework.com" | ||
| }, | ||
| "icons": { | ||
| "color": "icon-color.png", | ||
| "outline": "icon-outline.png" | ||
| }, | ||
| "name": { | ||
| "short": "Messaging Extension SSO", | ||
| "full": "ME SSO for Search, Action and link unfurling" | ||
| }, | ||
| "description": { | ||
| "short": "ME Authentication for Search, Action and Link unfurling", | ||
| "full": "ME Authentication sample code for all authentication merged" | ||
| }, | ||
| "accentColor": "#FFFFFF", | ||
| "composeExtensions": [ | ||
| { | ||
| "botId": "{TODO: MicrosoftAppId}", | ||
| "canUpdateConfiguration": true, | ||
| "commands": [ | ||
| { | ||
| "id": "searchQuery", | ||
| "type": "query", | ||
| "title": "Search", | ||
| "description": "Perform a search", | ||
| "initialRun": false, | ||
| "fetchTask": false, | ||
| "context": [ | ||
| "commandBox", | ||
| "compose", | ||
| "message" | ||
| ], | ||
| "parameters": [ | ||
| { | ||
| "name": "searchQuery", | ||
| "title": "Search", | ||
| "description": "Your search query", | ||
| "inputType": "text" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "id": "SHOWPROFILE", | ||
| "type": "action", | ||
| "title": "Compose", | ||
| "description": "Compose and send email", | ||
| "initialRun": false, | ||
| "fetchTask": true, | ||
| "context": [ | ||
| "commandBox", | ||
| "compose", | ||
| "message" | ||
| ], | ||
| "parameters": [ | ||
| { | ||
| "name": "param", | ||
| "title": "param", | ||
| "description": "" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "id": "SignOutCommand", | ||
| "type": "action", | ||
| "title": "Sign Out", | ||
| "description": "Sign out from authenticated services.", | ||
| "initialRun": false, | ||
| "fetchTask": true, | ||
| "context": [ | ||
| "commandBox", | ||
| "compose" | ||
| ], | ||
| "parameters": [ | ||
| { | ||
| "name": "param", | ||
| "title": "param", | ||
| "description": "" | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "messageHandlers": [ | ||
| { | ||
| "type": "link", | ||
| "value": { | ||
| "domains": [ | ||
| "*.botframework.com" | ||
| ] | ||
| } | ||
| } | ||
| ] | ||
| } | ||
| ], | ||
| "permissions": [ | ||
| "identity" | ||
| ], | ||
| "validDomains": [ | ||
| "*.githubusercontent.com", | ||
| "*.ngrok.io", | ||
| "*.botframework.com" | ||
| ], | ||
| "webApplicationInfo": { | ||
| "id": "{TODO: MicrosoftAppId}", | ||
| "resource": "api://{TODO: SiteUrlDomain}/botid-{TODO: MicrosoftAppId}/{TODO: MicrosoftAppId}" | ||
| } | ||
| } |
Oops, something went wrong.