Teams Hub

 

About

Integration with the Teams application is accomplished by installing the SmartHub Teams application in your tenant or a specific Team. The integration is compatible with both the web and the desktop version of Teams.

The SmartHub Teams app exposes 3 types of integrations:

  • Message extension
    • Enables you to run searches and embed results as part of your messages in Chat.
  • Personal Tab extension
    • Enables you to access the full functionality of the SmartHub center directly from Teams.
  • Teams Tab extension
    • Enables all the members of your team to access the full functionality of the SmartHub center directly from the Team tabs.

Prerequisites

  • SmartHub must be installed and accessible using HTTPS
    • This requires a trusted, valid certificate to be configured in the IIS bindings
  • Supported Authentication: Only "Azure AD" or "Federated authentication"
    • Windows Authentication is unsupported
  • In the web.config file, remove the X-Frame-Options and Content-Security-Policy headers.

  • If you plan to install the Hub for only someTeams then the Teams external app installation switch needs to be enabled to side-load applications - see Admin settings for apps in Microsoft Teams.



    Note:

    • If you do not configure the Teams Hub correctly, it is made available to the entire Organization.

    • Any user will be able to install the Hub for himself or the Teams he is a member of.

Additional Message Extension Requirements

In Teams, the message extension functionality is based off the Microsoft Bot Framework infrastructure. As a result there are some specific requirements for this feature to work:

  • An Office 365 account with permissions to register a Bot service.
  • SmartHub needs to be accessible from the internet for the Bot Framework to reach it.
  • A bot needs to be registered and configured in the Microsoft Bot Framework Portal - see the Register the SmartHub Teams Bot section.

How to Register the SmartHub Teams Bot

  1. Navigate to Bot Framework Portal.
  2. Click on the Create button. You are redirected to the Create an Azure Bot Blade.
  3. Enter a Bot handle.
  4. Choose the Subscription.
  5. Select a Resource Group (or create a new one).
  6. Select a Pricing Tier.
  7. In the Microsoft App ID field, choose one of the following:
    1. If you don't own an application, select Create new Microsoft App ID.
    2. If you already have a registered application, select Use existing app registration.
      1. If you selected this option, an Existing app ID and Existing app password should be provided.
      2. App ID
        • This can be obtained from an existing registered application
        • This is marked as Application (client) ID in the "Overview" section on the left side nav. See the image below
      3. App password:
        • This is the client secret that can be obtained from the Certificates & Secrets page.
          • The existing app should be multi-tenant.

      4. Directory (tenant) ID: Note this value as it will be used later in configuration.

  8. Click on Review + create > Create.

  9. Wait until the deployment is finished, then click Go to resource.

  10. Select the configuration blade and enter the Messaging endpoint in the following format: https://smartHubAddress:port/_bai/v1.0/msteamsbot
    Example
    https://smarthub.contoso.com/_bai/v1.0/msteamsbot

    Tip: Ensure that the URL you entered is accessible from the internet

  11. Check Enable Streaming Endpoint.

  12. Take note of the Microsoft App ID and Client Secret values which are required later on.

    The Client secret can be obtained by accessing Manage > Certificates & secrets. If there is no client secret, create new one.
  13. Click on the Channels section and choose the Microsoft Teams from the Available Channels section.
  14. Agree to the terms of Service, select Microsoft Teams Commercial (most common), and click Save.

  15. Configure the bot for single sign-on (SSO):

    1. Navigate to the newly created bot

    2. Adjacent to Microsoft App ID:

      1. Select Manage.

      2. From the left pane of your bot resource, select Authentication.

    3. If the Web Platform has not been created, choose Add a platform > Web.

    4. Enter the following Redirect URI: https://token.botframework.com/.auth/web/redirect.

    5. Check the Access tokens and ID tokens checkboxes.

    6. Click Configure.

    7. If the Web Platform is already created, just add the URI and select those checkboxes.

  16. The current application should be registered as multi-tenant, otherwise the bot framework is not allowed to access the exposed api that will be created in next steps.

    1. If the Microsoft App ID was created at the same time with the Azure Bot, the app registration is already set to multi-tenant.

    2. Otherwise, if you used an existing app registration, the following changes should be made:

      1. Navigate to the Manifest section.

      2. Change the property for signInAudience to AzureADandPersonalMicrosoftAccount.
        A multi-tenant application does not allow custom Application ID URI. For example:

        • https://localhost:1234, https://my-app-id-URI

        • The property must use a verified domain of the organization or its sub-domain.

      3. Ensure that the config item is set to: "accessTokenAcceptedVersion": 2.

      4. Click Save.

  17. Select Expose an API from the left pane. Select Set for the Application ID URI.

    1. If the newly created application was used, use the Application ID URI shown and append api://botid- to the beginning of the URI.

    2. If an existing app was used, set the Application ID URI as follows: api://botid-<MicrosoftAppId>.
      You must use the exact Application ID URI template as described above, otherwise the SSO process fails.

  18. Select Save. Take a note of Application ID URI value which are required later on.

  19. On the Scopes defined by this API section, create a new scope with following configuration:

    1. Scope name: Enter a scope name.

    2. Who can consent?: Admins and users

    3. Admin consent display name: Enter a consent display name.

    4. Admin consent description: Enter a description for the Admin consent.

    5. State: Enabled

  20. Save the newly created scope.

  21. Add the following IDs as Authorized client applications and also select the checkbox for Authorized scopes:

    • 1fec8e78-bce4-4aaf-ab1b-5451cc387264 (Teams mobile or desktop application)

    • 5e3ce6c0-2b1f-4285-8d4b-75ee78787346 (Teams web application)

    • Your MicrosoftAppId.

  22. Select Token configuration from the left-side navigation.

    1. Click Add optional claim. Select Access as *Token type.

    2. Select upn under Claim. Click Add.

    3. Click Add optional claim. Select ID as *Token type.

    4. Select upn under Claim. Click Add.

  23. Navigate to API Permissions > Add a permission > Microsoft Graph > Delegated permissions and select all OpenId permissions:

    • email

    • offline_access

    • openid

    • profile

  24. Navigate to API Permissions > Add a permision > My APIs > Select your app used for authentication in SmartHub and choose the scope used in SmartHub for Authentication.

    • SH.ALL

  25. Open the Azure Bot and go to Configuration page > Add OAuth Connection Settings.

    • In New Connection Setting enter the following details:

      • Name: Enter your name for your new connection string. Take a note of the connection name.

      • Service Provider: Select Azure Active Directory V2.

      • Client id: Enter the Microsoft App Id noted above.

      • Client secret: Enter the Secret value noted above.

      • Token Exchange URL: Enter the Application ID URI noted above.

      • Tenant ID: enter the Tenant ID noted above.

      • Scopes: enter email offline_access openid profile smarthub-auth-app-scope/SH.ALL.

        • smarthub-auth-app-scope/SH.ALL: This is the scope from the app used for SmartHub Authentication (used above in API Permissions).

  26. Click Save.

  27. After the OAuth Connection is saved, click on it and press Test Connection.

  28. A popup about permissions should be displayed. Click Approve.

  29. If everything is configured correctly, a token should be generated. You can now close this tab.

How to Configure the App

To install the app you must first update the manifest with your own configuration details:

  1. Navigate to the installation directory of your SmartHub website.
  2. Open the folder integrations\msteams\SmartHubApp.
  3. Edit the manifest.json, SmartHub Security Settings, and web.config file as instructed in the following sections.

Personal Tab Settings

This is used for configuring what page the Personal tab of the users that install the Hub will display.

  • To fully disable this functionality remove the entire staticTabs node and its children from the manifest.
  • Look for staticTabs property and change the contentUrl and websiteUrl to point to your SmartHub address
Example 
"contentUrl": "https://smartHubAddress:port/integrations/msteams/"
"websiteUrl": "https://smartHubAddress:port/Index.html#pn=msteams"

Messaging Extension Settings

This is used for configuring what bot the Messaging extension communicates with.

  • To fully disable this functionality remove the entire composeExtensions node and its children from the manifest.
  1. Look for composeExtensions and change the botId property by replacing it with Microsoft App ID that you noted during the Bot Service creation.

  2. Look for webApplicationInfo and change the following:

    • Replace the id property with the Microsoft App ID.

    • replace the resource property with the Application ID URI that you noted.

  3. From your SmartHub root folder, open the web.config file for editing.

  4. Change the following keys:

    • TeamsBotConnectionName with connection name that you noted.

    • TeamsBotSiteURL with the smarthub address: https://smartHubAddress:port.

    • TeamsBotClientId with the Client ID from the Bot App that you noted.

  5. Go to SmartHub Admin page > Security Settings > Trusted App Registration > Click to Expand the section.

    • Add the Trusted App Registrations.

    • Add the Client ID (Azure Bot App) that you noted above.

    • Add the Client Secret (Azure Bot App) that you noted above.

    • Click OK.

Team Tab Extension Settings

This is used for configuring what page should be opened when users navigate to the SmartHub tab in their Team.

  • To fully disable this functionality remove the entire configurableTabs node and its children from the manifest.
  1. Look for configurableTab and modify the configurationUrl to point to your SmartHub address - make sure you leave the following relative path in the URL:
       /integrations/msteams/ConfigPage.html

  2. If you want to point the Team Tab to a custom page that is based on the default Index and Results pages from Teams you must append the following to the end of the URL:
       ?address=<address to the page that should be opened by the tab>
  • By default, it automatically opens the built-in /integrations/msteams pages.
For proper operation, the value of the ?address parameter must be encoded.

After Settings Are Complete

  1. Save the changes and go to the parent directory: integrations\msteams.
  2. Go to SmartHubApp directory and select all (CTRL + A) files inside.
    1. Right-click the files and choose the option Send To → Compressed (zipped) folder

  3. After the archive is created, copy it to the environment where you have the Teams desktop client installed.

How to Install the SmartHub Teams App

The SmartHub Teams App can be installed at 3 levels:

  • Me or My Teams → Personal (Add for you)
    • The Messaging extension is installed only for you
    • The Personal Tab extension is installed to your account
    • The Team Tab extension is not installed
  • Me or My Teams → Team (Add to a team)
    • The Messaging extension is installed for all of your team members
    • The Personal tab extension is only installed to your account
    • The Team Tab extension is installed for the Teams you select
  • Organization
    • The app is uploaded and made available for all of your users but is not automatically installed to any user or team.

Note: The app needs to be installed individually for each team that is planing to use it.

How to Install the Teams App for a Specific User or Team

  1. Navigate to the Store and click on Upload a custom app → Upload for me or my teams

  2. Select the ZIP file created in step 2 in the topic After Settings Are Complete.

How to Make the Teams App Available to Your Organization

  1. Navigate to the Store

  2. Click on Upload a custom app → Upload for [OrganizationName] and select the ZIP file created in step 2 in the topic After Settings Are Complete.

  3. This does not install the application but makes it available under the Store → [Organization Name] subsection.


  1. Now you and everyone from your organization can select the Teams app and install it personally or to any Team the user owns.

How to Uninstall the SmartHub Teams App

The SmartHub Teams App must be uninstalled from 4 sections, or tabs, listed here:

  • Personal tab
  • Team tab
  • Conversations tab
  • <Your Custom Named> SmartHub tab

Personal Tab

  1. Select Teams from the right side menu.
  2. From the menu, select SmartHub.
  3. Click the dots icon "..." and select Uninstall.


Team Tab

  1. Click the icon More options.
  2. Click Manage team.


  3. On the top, horizontal menu, select Apps.
  4. Click the trash can icon to delete your (custom) Smart Hub app.

How to Change the Results Icon from the Bot

  1. Navigate to the installation directory of your SmartHub website
  2. Open the folder integrations\msteams\image
  3. Add your custom icons, using as name of the file the expected extension
    • Example: For results with a PDF extension, the icon name is "pdf.png"

Note: The file icon.png represents the default icon

How to Use Open In Tab

  1. The Open in tab button enables the user to open a SmartHub Teams tab directly from the messaging extension.

  2. The button can be found by clicking on the Actions button and selecting Open in tab

How to Track Queries from Bot in SmartAnalytics

To see reports about queries from Bot, go to http://<ReportingPageAddress>/Pages/QueryAnalytics/QueriesBySource.aspx

Conversations Tab

  1. Go to your team's General page.
  2. Go to the Conversations tab.
  3. Click on the Messagingextensions icon.
  4. Go to the Smart Hub App and click "Uninstall."

Remove <YourCustomNamed> SmartHub

To remove the "SmartHub Enterprise Search" (or the name of your SmartHub) tab:

  1. Go to your team's General page.
  2. Select your SmartHub from the top horizontal menu.
  3. Click Remove.