Setting Up Nautobot ChatOps with Microsoft Teams – Fall 2021
UPDATE October 2022 Since this post was originally created, there have been multiple updates on both the Microsoft Azure and Microsoft Teams side for setting up ChatOps bots. You can reference our updated blog post here, as this post includes outdated information for setting up Azure and the Teams client.
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 see 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
There are two main parts to getting the ChatOps plugin working with any ChatOps service: 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:
- Create an Azure Bot Service and Resource Group
- Configure the Azure Bot Channel
- 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.
- Pricing – This defaults to “Standard”, which will incur costs. For demo/development purposes, I changed this to the “Free” tier.
Under the Microsoft App ID section, leave the default option selected to 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.
All of the options on the next Configure Microsoft Teams
page should be ok 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 – Create a Client Secret for the Azure Bot
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.
A couple options farther down, copy and save the Microsoft App ID
somewhere else as you’ll need this later. Then 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 term 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
orclear
- Subcommand – You can specify permissions for subcommands as well, or all subcommands with an asterisk
*
. Example subcommands:get-devices
orhelp
- 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 toclear
, 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 runclear
, 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 channelbot-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:
- manifest.json – Preconfigured information for the bot
- color.png – Icon to use for the bot
- outline.png – Transparent image to use for the bot
First, log in to 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:
- 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.
- 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.
Conclusion
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!
Additionally, there’s a blog post from earlier this month around creating your own custom chat commands within this plugin. If interested, you can read it here.
Thanks for reading, and I hope you enjoy ChatOps as much as I do!
-Matt
Contact Us to Learn More
Share details about yourself & someone from our team will reach out to you ASAP!