Register a bot with Azure
APPLIES TO: SDK v4
If you don't currently host your bot in Azure, you can still make it available in Azure and use Azure to connect your bot to channels. To do so, enter in Azure the web address where your bot is hosted.
This article shows how to register such a bot with Azure AI Bot Service.
Important
You only need to register a bot if it's not hosted in Azure. Bots created using the Azure CLI are already registered with the Azure AI Bot Service.
Your bot identity can be managed in Azure in a few different ways.
- As a user-assigned managed identity, so that you don't need to manage the bot's credentials yourself.
- As a single-tenant app.
- As a multi-tenant app.
Support for the user-assigned managed identity and single-tenant app types was added to the Bot Framework SDK for C# and JavaScript in version 4.15.0. These app types aren't supported in the other languages or in Bot Framework Composer, Bot Framework Emulator, or ngrok.
| App type | Support |
|---|---|
| User-assigned managed identity | Azure AI Bot Service and the C# and JavaScript SDKs |
| Single-tenant | Azure AI Bot Service and the C# and JavaScript SDKs |
| Multi-tenant | Azure AI Bot Service, all Bot Framework SDK languages, Composer, the Emulator, and ngrok |
This article doesn't describe how to create or deploy the bot to register. For more information, see:
- The Create a bot quickstart
- The Deploy a basic bot tutorial
Create the resource
Create the Azure Bot resource, which will allow you to register your bot with the Azure AI Bot Service.
Tip
New Web App Bot and Bot Channels Registration resources can't be created; however, any such existing resources that are configured and deployed will continue to work. Bots created from a VSIX or Yeoman template from SDK version 4.14.1.2 or later contain ARM templates that will generate an Azure Bot resource.
Go to the Azure portal.
In the right pane, select Create a resource.
In the search box enter
bot, then press Enter.Select the Azure Bot card.
Select Create.
Enter values in the required fields and review and update settings.
Provide information under Project details. Select whether your bot will have global or local data residency. Currently, the local data residency feature is available for resources in the "westeurope" and "centralindia" region. For more information, see Regionalization in Azure AI Bot Service.
Provide information under Microsoft App ID. Select how your bot identity will be managed in Azure and whether to create a new identity or use an existing one.
Select Review + create.
If the validation passes, select Create.
Once the deployment completes, select Go to resource. You should see the bot and related resources listed in the resource group you selected.
If you don't already have the Bot Framework SDK, select Download from GitHub to learn how to consume the packages for your preferred language.
You're now ready to build your bot with the Bot Framework SDK.
Tip
When Azure creates a new single-tenant or multi-tenant Azure Bot resource with a new app ID, it also generates a password.
Bot identity information
Follow these steps to add identity information to your bot's configuration file. The file differs depending on the programming language you use to create the bot.
Important
The Java and Python versions of the Bot Framework SDK only support multi-tenant bots. The C# and JavaScript versions support all three application types for managing the bot's identity.
| Language | File name | Notes |
|---|---|---|
| C# | appsettings.json | Supports all three application types for managing your bot's identity. |
| JavaScript | .env | Supports all three application types for managing your bot's identity. |
| Java | application.properties | Only supports multi-tenant bots. |
| Python | config.py | Only supports multi-tenant bots. Provide the identity properties as arguments to the os.environ.get method calls. |
The identity information you need to add depends on the bot's application type. Provide the following values in your configuration file.
Only available for C# and JavaScript bots.
| Property | Value |
|---|---|
MicrosoftAppType |
UserAssignedMSI |
MicrosoftAppId |
The client ID of the user-assigned managed identity. |
MicrosoftAppPassword |
Not applicable. Leave this blank for a user-assigned managed identity bot. |
MicrosoftAppTenantId |
The tenant ID of the user-assigned managed identity. |
To update your app service
If you have an existing App Service resource (web app) for your bot and your bot is a user-assigned managed identity application, you may need to update your bot's app service:
- Go to the App Service blade for your bot's web app.
- Under Settings, select Identity.
- On the Identity blade, select the User assigned tab and Add (+).
- On the Add user assigned managed identity blade:
Select your subscription.
For User assigned managed identities, select the managed identity for your bot. If the managed identity was auto-generated for you, it will have the same name as your bot.
Select Add to use this identity for your bot.
To get your app or tenant ID
To get your bot's app or tenant ID:
- Go to the Azure Bot resource blade for your bot.
- Go to the bot's Configuration blade. From this blade, you can copy the bot's Microsoft App ID or App Tenant ID.
To generate a new password
Single-tenant and multi-tenant bots have an app secret or password that you need for some operations. Azure AI Bot Service hides your bot secret. However, the owner of the bot's App Service resource can generate a new password:
- Go to the Azure Bot resource blade for your bot.
- Go to the bot's Configuration blade.
- Select Manage, next to Microsoft App ID, to go to the Certificates + secrets blade for the app service.
- Follow the instructions on the blade to create a new client secret and record the value in a safe place.
Manual app registration
A manual registration is necessary when:
- You're unable to make the registrations in your organization and need another party to create the App ID for the bot you're building.
- You need to manually create your own app ID and password.
Update the bot
To update your bot's configuration file to include its app ID and password, see Application ID and password in how to Configure bot registration settings.
Additional information
See these articles for more information about Azure applications in general.
| Subject | Article |
|---|---|
| App registration | Quickstart: Register an application with the Microsoft identity platform |
| Managed identities | What are managed identities for Azure resources? |
| Single-tenant and multi-tenant apps | Tenancy in Microsoft Entra ID |
Next steps
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for