OfficeDev / microsoft-teams-sample-connector-csharp

A sample Office 365 Connector written in C#/.NET for a task list application, generating notifications whenever tasks are created or modified.

page_type	products	languages	extensions
sample	office-teams office-365	csharp	contentType technologies createdDate samples Connectors 10/10/2020 10:21:42 PM

Note: This repo is archieved and move to this new location: https://github.com/OfficeDev/Microsoft-Teams-Samples/tree/main/samples/connector-todo-notification/csharp

Microsoft Teams Sample Connector in .NET/C#

This is an MVC sample task management application generated using the ASP.NET Web Application (.NET Framework) template. The majority of the code is related to either basic MVC configuration or Task management.

The main connector code is found here:

• ConnectorController.cs - Setup & Save actions
• TaskController.cs - Create & Update actions

This application simulates a real task management system and allows users to create and view tasks. The content is randomly generated to simulate how notification can be sent into Microsoft Teams channel using connector.

For more information on developing apps for Microsoft Teams, please review the Microsoft Teams developer documentation. n

Prerequisites

The minimum prerequisites to run this sample are:

• The latest update of Visual Studio. You can download the community version here for free.
• An Office 365 account with access to Microsoft Teams, with sideloading enabled.
• If you want to run this code locally, use a tunnelling service. These instructions assume you are using ngrok.

How to see the connector working in Microsoft Teams

1. Upload your custom app in Microsoft Teams using this manifest file.
2. Configure the TeamsToDoAppConnector connector.
3. Select either Create or Update on the registration page and click Save.
4. Once the connector is configured, you will get a notification in channel with link to the Task Manager application.
5. Go to Task Manager portal and click on Create New and enter the task details and Save.
6. You will see the MessageCard in the registered Teams channel.
7. You can try the actionable buttons available on the message card.

Note: With the above instructions, you can use sample connector which is deployed on Azure. Please follow the instructions below to create your own connector.

Configure your own connector

The sample shows a simple implementation of a connector registration implementation. It also sends a connector card to the registered connector via a process triggered "externally."

1. Open the TeamsToDoAppConnectorAuthentication.sln solution with Visual Studio.
2. Begin your tunnelling service to get an https endpoint.
   1. Open a new command prompt window.
   2. Change to the directory that contains the ngrok.exe application.
   3. In the command prompt, run the command ngrok http 3978 --host-header=localhost.
   4. Ngrok will fill the entire prompt window. Make note of the https:// Forwarding URL. This URL will be your [BASE_URI] referenced below.
   5. Minimize the ngrok Command Prompt window. It is no longer referenced in these instructions, but it must remain running.
3. Register a new connector in the Connector Developer Portal
   1. Fill in all the basic details such as name, logo, descriptions etc. for the new connector.
   2. For the configuration page, you'll use our sample code's setup endpoint: https://[BASE_URI]/connector/MainSetup
   3. For Valid domains, make entery of your domain's https URL, e.g. XXXXXXXX.ngrok.io.
   4. Enable the action on connector card by selecting the Yes radio button and enter the update endpoint: https://[BASE_URI]/Task/Update
   5. Click on Save. After the save completes, you will see your connector id.
4. In the Web.config file, set the configuration.appSettings.Base_Uri variable to the ngrok https forwarding url from the above.
5. In Visual Studio, press the green arrow (Start button) on the main Visual Studio toolbar, or press F5 or Ctrl+F5 to run the program.
6. Now you can sideload your app package and test your new connector.

Setting up Authentication on Configuration page

Above steps will let you configure connector without authentication. Please follow these steps to enable authentication in your connector config page. To be able to use an identity provider, first you have to register your application.

1. Using Azure AD

   1. Go to the Application Registration Portal and sign in with the your account to create an application.

   2. Navigate to Authentication under Manage and add the following redirect URLs:

      https://<your_ngrok_url>/Authentication/SimpleEnd

   3. Additionally, under the Implicit grant subsection select Access tokens and ID tokens

2. Setting up Authentication on Configuration page

3. Set the ClientAppId in web.config, for example : https://contoso.ngrok.io

   <add key="ClientAppId" value="***Your Client App Id***"/>
   

4. Update your Microsoft Teams application manifest

   1. Add your ngrok URL to validDomains. Teams will only show the sign-in popup if its from a whitelisted domain.

      "validDomains": [
          "<<BASE_URI_DOMAIN>>",
      ],

App structure

Routes

1. /Connector/MainSetup renders the connector config UI.
   • This is the landing page for connector configuration. The purpose of this view is primarily to allow user to navigate to either Simple setup / Setup with auth page.
2. /Connector/Setup renders the connector config UI.
   • This is simple connector configuration page which allows configuration without login.
3. /Connector/SetupAuth renders the connector config UI with auth.
   • This is connector configuration page which shows how to restrict configuration to authenticate users.
4. /Authenication/SimpleStart and /Authenication/SimpleEnd routes are used to grant the permissions. This experience happens in a separate window.
   • The Authenication/SimpleStart view merely creates a valid AAD authorization endpoint and redirects to that AAD consent page.
   • Once the user has consented to the permissions, AAD redirects the user back to Authenication/SimpleEnd. This view is responsible for returning the results back to the start view by calling the notifySuccess API.
   • This workflow is only necessary if you want authorization to use additional Graph APIs. Most apps will find this flow unnecessary if all they want to do is authenticate the user.
   • This workflow is the same as our standard web-based authentication flow that we've always had in Teams before we had single sign-on support. It just so happens that it's a great way to request additional permissions from the user, so it's left in this sample as an illustration of what that flow looks like.
5. /Tasks controller.
   1. /Tasks/Index renders the tasks list page.
   2. /Tasks/Create allows users to create new task, which triggers notification to all the webhooks registered for create event.
   3. /Tasks/Update allows users to update new task, which triggers notification to all the webhooks registered for update event.

More Information

For more information about getting started with Teams, please review the following resources:

• Review Getting Started with Authentications for Tabs
• Review Getting Started with Teams