Microsoft Teams Setup

Configuration Setting	Mandatory?	Default	Available on Admin Config
enable_ms_teams	Yes	False	Yes
microsoft_app_id	Yes	--	No
microsoft_app_password	Yes	--	No
microsoft_tenant_id	Yes	--	No

Register Microsoft Entra App

Info

Microsoft does regular updates to their Azure Platform. Some of these updates introduce new requirements, such as the *App Registration. These are the current instructions to setup a chatbot for Microsoft Teams.

Add App Registration

1. Login to https://portal.azure.com and select "App registrations".
   
2. Select New Registration.
   
3. Enter the name of your app, for example, Chatops-NautobotDev
4. Select Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant). !!! warning You must use Multitenant here, this is what allows the Bot to integrate with Microsoft Teams (which is technically a different Tenant).
5. Select Register.
6. Your app is registered in Microsoft Entra. The app overview page appears. Save Application (client) ID and Directory (tenant) ID for later use.

Add a Web Authentication

1. In the left pane, under Manage, select Authentication.
2. Select Add a platform > Web.
3. Enter the redirect URI for your app by appending /api/plugins/chatops/ms_teams/messages/ to the fully qualified domain name. For example, https://example.com/api/plugins/chatops/ms_teams/messages/.
4. Under Implicit grant and hybrid flows select the Access tokens and ID tokens checkboxes.
5. Select Configure.
   
6. Under Web, select Add URI
7. Enter https://token.botframework.com/.auth/web/redirect.
8. Under Implicit grant and hybrid flows, verify all checkboxes are checked.
9. Under Supported account types lower on the page, verify Accounts in any organizational directory (Any Microsoft Entra ID tenant - Multitenant) is selected.
10. Select Save at the bottom of the page.

Warning

Both entries must be present, one pointing to Nautobot and the other to https://token.botframework.com/.auth/web/redirect

Create a Client Secret

1. In the left pane, under Manage, select Certificates & secrets.
2. Under Client secrets, select + New client secret. The Add a client secret window appears.
3. Enter Description.
4. Configure Expires according to your security policies.
5. Select Add.
6. Under Value select Copy to clipboard to save the Client Secret value. This secret will need to be configured in Nautobot.

Tip

It is highly recommended to document the Expiration somewhere so that the secret can be renewed beforehand. Otherwise, ChatOps will stop working.

Add API Permissions

1. In the left pane, select API permissions.
2. Select + Add a permission.
3. Select Microsoft Graph.
   
4. Select Application permissions.
5. If User > User.Read is not already configured, select it here.
6. Select User > User.Read.All.
7. Select Add Permissions.
   

Warning

The **User > User.Read.All permission requires approval from an Azure Admin before it can be utilized.

Add Application ID URI

1. In the left pane, under Manage, select Expose an API, then Add next to Application ID URI.
2. Add the FQDN to the Application ID URI, be sure to leave the UUID in place.
3. Click on Save.

Add a Scope

1. In the left pane, under Manage, select Expose an API.
2. Select + Add a scope.
3. Enter access_as_user as the Scope name.
4. Under Who can consent?, select Admins and users.
5. Update the values for the rest of the fields as follows:
6. Enter Teams can access the user's profile as Admin consent display name.
7. Enter Allows Teams to call the app's web APIs as the current user as Admin consent description.
8. Enter Teams can access the user profile and make requests on the user's behalf as User consent display name.
9. Enter Enable Teams to call this app's APIs with the same rights as the user as User consent description.
10. Ensure that State is set to Enabled.
11. Select Add scope.

Add Client Application

1. In the left pane, under Manage, select Expose an API. Under Authorized client applications, identify the applications that you want to authorize for your app’s web application.
2. Select + Add a client application.
3. Add Teams mobile/desktop and/or Teams web application. You can add one or both of these Client IDs.
4. For Teams mobile app and desktop client app: Enter the Client ID as 1fec8e78-bce4-4aaf-ab1b-5451cc387264.
5. For Teams web client: Enter the Client ID as 5e3ce6c0-2b1f-4285-8d4b-75ee78787346.
6. Select the Authorized Scopes checkbox for the api:// endpoint we just created in section Add Application ID URI
7. Select Add application.

Create Azure Bot

Create an Azure Bot Resource

1. Login to https://portal.azure.com and select + Create a Resource.
2. Use the search box to locate Azure Bot, and select Enter.
3. Select Azure Bot
4. Select Create
5. Enter the bot name in the Bot handle.
6. This is used as an identifier in Azure Bot Framework, not what the bot is called in the MS Teams.
7. Select your Subscription from the dropdown list.
8. Select your Resource group from the dropdown list if you want to use an existing one. Otherwise, select the Create New and create a new resource group.
9. Under Pricing, select Change plan.
10. Be sure to select the F0 (free) pricing tier if desired. Otherwise the default is set to the S1 paid tier.
11. Under the Microsoft App ID, select Type of App as Multi Tenant
12. In the Creation type, select Use existing app registration.
13. Enter the App ID. This is the Application ID we saved for later use in Add App Registration
14. Select Review + create.
15. After the validation passes, select Create. The bot takes a few minutes to provision.
16. Select Go to resource.
17. In the left pane, under Settings, select Configuration.
18. Update the Messaging endpoint in the format: https://<nautobot_url>/api/plugins/chatops/ms_teams/messages/

Add a Teams Channel

1. In the left pane, under Settings, select Channels.
2. Under Available Channels, select Microsoft Teams.
3. Select the checkbox to accept the Terms of Service.
4. Select Agree.
5. Select Apply.

Configure The Chatops App

1. Download the Nautobot_ms_teams.zip file containing the Chatops app from the repository
2. Unzip he contents of the Nautobot_ms_teams.zip file to the Nautobot_ms_teams directory and open the manifest.json file for editing.
3. Replace the following values with your bot's Microsoft App ID that we previous saved in Add App Registration
4. id on line 5
5. botId in bots array on line 43
6. webApplicationInfo.id on line 104
7. Save the manifest.json file.
8. Zip the contents of the Nautobot_ms_teams directory to create Nautobot_ms_teams.zip.

Mac OSX

If you are on a Mac, OSX will insert hidden OSX-related files that will cause the import to fail. Instead, open Terminal, navigate to the extracted Nautobot_ms_teams folder, and run the following command:

zip -r Nautobot_ms_teams.zip . -x '**/.*' -x '**/__MACOSX'

Upload the App to MS Teams Portal

1. To deploy the bot to your team, log in to the Microsoft Developer Portal
2. Select “Apps” from the left menu bar.
3. Select "Import App" at the top of the screen.
4. Select the modified Nautobot_ms_teams.zip file created during the steps of Configure The Chatops App.
5. Once imported, the Edit an app page will appear, allowing you to configure the settings for the bot.
6. Confirm Application (client) ID matches the value from Add App Registration.
7. Select App Features under the same Configure section.
8. Confirm the Bot ID matches the Application (client) ID value.

Publish Bot App for Organizational Use

1. Under the Publish section select Publish to org and select the blue Publish your app button.
2. The App will be submitted for approval by your MS Teams administrators.
3. Once approved, the status will change from Submitted to Published, and you can find the app in your MS Teams client.
4. Open your MS Teams client and select Apps at the bottom of the left-side menu.
5. Select Built for your org to see the new Nautobot app.
6. Select the new app and click the blue Add button.
7. Proceed to the Install Guide section.

Nautobot Config

• microsoft_app_id - This is the "Application (client) ID" from Add App Registration.
• microsoft_app_password - This is the "Client Secret" from Create a Client Secret
• microsoft_tenant_id - This is the "Directory (tenant) ID" from Add App Registration.

Handling ChatOps Behind a Firewall

A common security concern with ChatOps is how to protect your network/application from malicious activity. In order to do so proper firewall policy should be implemented. Through trials, researching, and testing in multiple environments, allowing inbound connections from 52.112.0.0/14 has proven to be successful. Although Microsoft doesn't publish all their ranges this range was found in a Microsoft Blog Post and has yielded success in locked down environments. Additionally Microsoft Posted their IP Address and DNS ranges.

General Chat Setup Instructions

See admin_install instructions here for general app setup instructions.