NOTE: This blog post is an updated copy of previous ones from April 2021, November 2021, and March 2022. It has been updated with the latest process changes within Microsoft Azure and Teams due to certain original processes being deprecated or modified significantly over time, both on the Microsoft Azure side as well as the Microsoft Teams side.

Network to Code has released a number of amazing apps for Nautobot—one of which, adding ChatOps functionality, can be found here on GitHub. This application adds ChatOps capabilities directly into your existing ChatOps client, in the form of a chatbot, and supports four of the more popular services available right now. The four services currently supported are Slack, Microsoft Teams, Webex, and Mattermost.

If this is your first time hearing about ChatOps or this app (plugin), you can watch the ChatOps demo on YouTube or join slack.networktocode.com and try it out for yourself in the #nautobot-chat channel.

Today, I’ll be going over how to get this app working in Nautobot and how to get a chatbot up and running for Microsoft Teams. The process is fairly different from the other three providers listed, and slightly more complex, but the end results are amazing. Let’s dive right in!

Getting Started

With any ChatOps service, getting the ChatOps plugin working has two main parts: configuring it on the ChatOps service directly, and installing and configuring it on your Nautobot server. Microsoft Teams splits the first part into two sections: creating the service in Azure, and installing the app in the Teams client.

For simplicity, I will assume you already have the base Nautobot server installed and working. If not, you can find the full documentation over on our new Nautobot Documentation site, or join our public Slack channel #nautobot at slack.networktocode.com and ask for assistance.

Part 1: Configuring Microsoft Teams SaaS

Azure and Permissions

To start off, I will be configuring a brand-new bot for Microsoft Teams from scratch. Microsoft runs their bots differently from Slack, Webex, or Mattermost, in that their bot service runs on Azure. If you don’t have a Microsoft Azure account, you will need to create one or get access to it through your company before continuing.

According to the Microsoft docs, you will need “Contributor access either in the subscription or in a specific resource group. A user with the Contributor role in a resource group can create a new bot in that specific resource group. A user in the Contributor role for a subscription can create a bot in a new or existing resource group.”

Configuring Azure

The three main parts to configuring a bot in Azure:

1. Create an Azure Bot Service and Resource Group
2. Configure the Azure Bot Channel
3. Create a Client Secret for the Azure Bot

I’ll break down each part individually, with step-by-step instructions and screenshots along the way.

1 – Create an Azure Bot and Resource Group

First, log into the Azure Portal at https://portal.azure.com.

At the top of the screen is a search bar. Search for “Azure Bot”, then select the option with the same name under “Marketplace” on the right side. This will take you to the page to create a new Azure Bot.

NOTE: You may need to activate this service first within your company’s Azure subscription, which is not covered in this post.

A few key fields to fill out when creating a new Azure Bot are:

• Bot Handle – What you want your bot handle to be. This is not what your bot is called in the MS Teams client, or how users will interact with your bot, but it is unique (case-insensitive) within the overall Azure Bot Framework.
• Subscription – The Azure billing subscription your bot will use for any charges.
• Resource Group – If there’s an existing one you want to use, select it. Otherwise, select the “Create new” link and create a new resource group. In this example, I’m creating a new Resource Group called “RG_nautobot_ntcblog”.
• New Resource Group Location – Choose whichever location works best for you.
• Data Residency – If this preview option is present, leave it set as “Global”.
• Pricing Tier – This defaults to “Standard”, which will incur costs. For demo/development purposes, I changed this to the “Free” tier.
• Type of App – For the purposes of this blog post, selecting “Multi Tenant” works best here to allow the Bot access to different resources.

For Creation Type, leave the default option selected: Create a new Microsoft App ID and click the Review + create button at the bottom.

Note: Tags are optional, but feel free to experiment with them later.

After Azure validates your settings, the Create button will be enabled. Click it to initiate the deployment process in Azure. This may take a few minutes, but it will let you know once the deployment is complete.

Once complete, go to the newly created resource by selecting the Go to resource button. You can also monitor its progress in the upper right of the Azure dashboard, under the alerts icon (looks like a bell).

2 – Configure the Azure Bot Channel

On the main resource page for the new Azure Bot, on the left main bar, select Channels under the Settings section. Then select the Microsoft Teams client icon, as circled in the screenshot below.

A small window may pop up asking you to accept the Terms of Service. If so, review and select “Agree” to continue.

All of the options on the next Configure Microsoft Teams page should be okay when left to default, but should be reviewed anyway for your specific use case.

Once done, click Save at the bottom of the page, and review and Agree to any ToS pop-ups.

3 – Configure the Messaging Endpoint

Next, on the left sidebar, select Configuration under the Settings section.

For the Messaging Endpoint, enter your Nautobot service URL in this format: https://<server>/api/plugins/chatops/ms_teams/messages/.

In this demo example, I’m using the Ngrok service. For a production Nautobot server, you would enter in the publicly facing DNS endpoint for inbound webhooks into your Nautobot server.

Also take note of the read-only Microsoft App ID listed on your screen. This will be needed later on in the setup process.

Click Apply to save the changes.

4 – Create a Client Secret for the Azure Bot

On this same Configuration page, select the “Manage” link directly above the App ID.

This will take you to the Certificates & Secrets page.

Click New client secret. Name it something descriptive, configure the expiration setting as necessary, and click Add.

Once it’s created, it will appear in the Client Secrets table at the bottom of the page. Copy and save the newly generated secret for later, as there’s no way to recover it once you leave the page.

NOTE: If you lose the key or copy it incorrectly, you will have to return to this page and generate a new secret.

Azure Recap

At this point, the Nautobot ChatOps plugin is fully set up within Azure. You should have two pieces of information for later use: the App ID and the Client Secret.

Part 2: Installing and Configuring the Nautobot ChatOps App (Plugin)

Note: The terms plugin and app are being used interchangeably in this post.

Next, you must install and configure the Nautobot ChatOps plugin on your Nautobot server. Luckily, the fine folks at Network to Code have made this process incredibly simple!

Installing the Plugin

First, log into your Nautobot server and change to the user account Nautobot is running as. From there, it’s as simple as installing the plugin via a pip install command.

$ sudo -iu nautobot
$ pip3 install nautobot-chatops

Once the package is installed, the plugin will need to be enabled in your nautobot_config.py. If Nautobot was originally set up according to the default installation docs, this file will be located at /opt/nautobot/nautobot_config.py. In this file, add in the name of the plugins to the PLUGINS variable, then configure the required settings in the PLUGINS_CONFIG variable below it.

PLUGINS = ["nautobot_chatops"]

PLUGINS_CONFIG = {
    "nautobot_chatops": {
        "enable_ms_teams": True,
        "microsoft_app_id": "<app_id>",
        "microsoft_app_password": "<client_secret>"
    }
}

Make sure to replace <app_id> and <client_secret> with the App ID and Client Secret saved from Azure in the previous steps. Then save the file and restart the NGINX and Nautobot services.

sudo systemctl restart nginx
sudo systemctl restart nautobot-worker.service

Configuring the Plugin in Nautobot

Next, we need to configure the plugin in Nautobot to accept commands. For most deployments, open and unrestricted access to the bot from any chat account is undesirable. Therefore, access to the chatbot defaults to “deny all” when initially installed. Permissions for individual organizations, channels, and users must be set up here. For the purposes of this blog post, we will grant all access.

First, log into your Nautobot server. If this is the first plugin installed, a new menu option called Plugins will appear at the top. Under it, in section Nautobot ChatOps, select Access Grants.

Select the Add button to create a new access grant.

• Command – You can specify permissions on a command-by-command basis, or specify all commands with an asterisk * as a wildcard. Example commands: nautobot or clear
• Subcommand – You can specify permissions for subcommands as well, or all subcommands with an asterisk *. Example subcommands: get-devices or help
• Grant Type – You need to create permissions for all three options: Organization, Channel, and User.
  • Organization – This is for permissions specific to your organization. This is good for configuring allowed/blocked commands organization-wide.
  • Channel – This is for configuring permissions on a per-channel basis.
  • User – This is for configuring permissions on a per-user basis.
• Name – The corresponding name of the organization, channel, or user. This is used more like a description, whereas the value below is used when interacting with the MS Teams SaaS API on the back end.
• Value – Corresponding ID value to grant access to. Enter an asterisk * to grant access to all organizations, channels, or users.

Once all three permissions are created, the plugin is done being set up in Nautobot. The minimum amount of permissions required are three. You can allow everyone in your organization access to all commands (not recommended) by using wildcards for organization, channel, and user permissions.

In the above example, here’s how I’ve set it up:

• Organization – The org has access only to the nautobot command. It does not have access to clear, or any future commands the plugin may end up supporting.
• User – Anyone can run just the nautobot get-devices command, however user John Doe can run any command. Note that he cannot run clear, as that is restricted at the Organization permission above.
• Channel – Anyone can access the bot from any channel, but again, only the nautobot get-devices command. However, anyone in channel bot-admins can access any command available to them.

To summarize, anyone can run nautobot get-devices, whereas John Doe and anyone in the channel Bot Admins can run any nautobot subcommand. Nobody can run clear or any command that doesn’t start with nautobot.

The last step is configuring the Microsoft Teams client.

Part 3: Installing and Configuring the App in Teams

The last main step needed is uploading and installing the app into your Microsoft Teams web portal for use within your organization.

Before continuing, you need to download a single ZIP file from the ChatOps plugin repo, found here. This will be used later for ease of configuring your app for your organization.

The ZIP file contains three files:

1. manifest.json – Preconfigured information for the bot
2. color.png – Icon to use for the bot
3. outline.png – Transparent image to use for the bot

First, log into the Microsoft Developer Portal. Select Apps from the left menu bar, then Import App at the top of the screen. Select the Nautobot_ms_teams.zip file you downloaded earlier to import.

Note: You may get the below import error. This can be safely ignored, as we want the root ID it references to be auto-generated _after import. Click the blue Import button to ignore this error and complete the import._

Once imported, the Edit an app page will appear, allowing you to configure the settings for the bot.

Required Setting Changes

There are two settings that must be modified for the Azure Bot Application ID. This is the same App ID that was copied out of Azure earlier in the setup process.

First, scroll to the bottom of the Basic Information page under the Configure section. In the field Application (client) ID, paste in the application ID you copied out earlier from Azure. Then click Save at the bottom.

Next, click on App Features under the same Configure section. Near the top will be one or more tiles. Select the ... for Bot, then select Edit.

On the next screen, under Identify your bot, select the existing Bot ID from the drop-down list. If it doesn’t show up (as in the below screenshot), you can select Enter a bot ID and copy in the Bot ID from Azure manually. Then click Save.

All other settings are preconfigured as necessary, but you are welcome to adjust them as needed.

Submit Bot App for Organizational Use

Once you are ready, under the Publish section select Publish to org and select the blue Publish your app button.

It will then be submitted for approval by your MS Teams administrators.

Once approved, the status will change from Submitted to Published, and you can find the app in your MS Teams client. However, we still need to activate it first.

Note: I had to wait approximately 30 minutes and restart my client before the app appeared in this section. If it doesn’t show up right away, you may have to wait up to a few hours.

Open your MS Teams client and select Apps at the bottom of the left-side menu. Select “Built for your org” to see the new Nautobot app. Select the new app and click the blue Add button.

Done

That’s it! Your new Nautobot ChatOps plugin should now be installed for your Microsoft Teams client and usable by anyone with the appropriate permissions (configured earlier in part 2).

You can do some really cool things with the bot once it’s up and running and you have some data in Nautobot. You can send the message nautobot help to the app (no / forward slash) to see a list of all supported commands.

Interacting with Nautobot in Microsoft Teams

There are currently a couple of ways to interact with the Nautobot plugin by default directly in the Microsoft Teams client, although these can be modified in the app permissions in the same area where you installed the app originally (in part 3). They are:

1. Chat – In the main left sidebar, select Chat, then search for “Nautobot” (or whatever you renamed the bot to). You can message the bot directly here.
2. App – In the main left sidebar, select the three dots, then in the pop-out menu, search for “Nautobot” and select it. I recommend right-clicking the icon in the left sidebar once the window opens to pin it for future interactions.

Forward Looking

Here at Network to Code, as we continue developing Nautobot, we will be adding functionality to this ChatOps plugin as well. With the code publicly available here on GitHub, we encourage anyone looking to contribute to do so and join our growing open-source community around Nautobot!