Register a bot with Azure

APPLIES TO: SDK v4

This article shows how to register a bot with the Azure Bot Service when you develop and host it in Azure.

If the bot is hosted elsewhere, you can also make it available in Azure and connect it to the supported channels. You supply the web address where your bot is hosted.

Important

You only need to register a bot if it is not hosted in Azure. Bots created using Azure CLI are already registered with the Azure Bot Service.

This article doesn't describe how to create or deploy the bot to register. For more information, see:

Create the resource

Create the Azure Bot resource, which will allow you to register your bot with the Azure Bot Service.

Warning

Web App Bot and Bot Channels Registration are deprecated but existing resources will continue to work. You should use Azure Bot, instead.

  1. Go to the Azure portal.

  2. In the right pane, select Create a resource.

  3. In the search box enter bot, then press Enter.

  4. Select the Azure Bot card.

    Select Azure bot resource

  5. Select Create.

  6. Enter values in the required fields. Choose which type of app to create and whether to use existing or create new identity information.

    Create a user-assigned managed identity Azure Bot resource with a new app ID.

  7. Select Review + create.

  8. If the validation passes, select Create.

  9. Select Go to resource group. You should see the bot and related resources listed in the resource group you selected.

  10. Select Get the SDK from GitHub to build your bot with the Bot Framework SDK.

    Create bot in 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 and stores the password in Azure Key Vault.

Key Vault is a service that provides centralized secrets management, with full control over access policies and audit history. For more information, see Use Key Vault references for App Service and Azure Functions. You're charged a small fee for using the service. For more information, see Key Vault pricing.

Bot identity information

You need 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 Leave this blank for a user-assigned managed identity bot.
MicrosoftAppTenantId The bot's app tenant ID.

To add the user-assigned managed identity to your bot's web app:

  1. Go to the app service page for your bot's web app.
  2. In the navigation pane under Settings, select Identity.
  3. On the Identity pane, select the User assigned tab and Add (+).
  4. On the Add user assigned managed identity pane:
    1. Select your subscription.

    2. 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.

    3. Select Add to use this identity for your bot.

      The App Service Identity page with the managed identity for the bot selected.

To get your bot's app or tenant ID:

  1. Go to the Azure Bot resource page for your bot.
  2. Go to the bot's Configuration pane. From here you can copy the bot's Microsoft App ID or App Tenant ID.

Tip

When Azure creates a single-tenant or multi-tenant bot, it stores the app password in Azure Key Vault.

To get the bot's app password from Azure Key Vault, see:

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.

Important

When creating the app, in the section Supports account types, choose one of the following multi-tenant types options:

Type Description
Accounts in any organizational directory (Any Azure AD - Multitenant) This option provides less exposure by restricting access and in case OAuth is not supported.
Accounts in any organizational directory (Any Azure AD - Multitenant) and personal Microsoft accounts (for example, Xbox, Outlook.com) This option is well-suited to support OAuth and bot authentication.

For more information, see Register an application with the Microsoft identity platform.

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.

Next steps