Use certificate or MSI for app authentication

You can use certificate- or MSI-based authentication to validate your bot app instead of bot ID and secret. This authentication resolves the compliance concerns related to the use of Microsoft Entra ID and bot secret.

Prerequisites

Ensure that you have a Teams bot app deployed to Azure with the following resources:

• An Azure bot.
• An Entra ID with a secret used for bot authentication.
• A resource that hosts your bot app, such as Azure App Service, Azure Functions.

Update to certificate-based Authentication

To update your bot app to use certificate-based authentication:

1. Create and upload certificate in Azure AD
2. Update the bot app code
3. Delete bot secret

Create and upload certificate in Azure AD

To use a certificate for bot authentication:

1. Prepare a certificate and private key.

2. Go to Azure portal.

3. Select App registrations.

   

4. Select your registered app.

5. In the left pane, under Manage, select Certificates & secrets.

6. Under Certificates, select Upload certificate.

   

   The Upload a certificate window appears.

   Note

   Upload a certificate (public key) with one of the following file types: .cer, .pem, .crt.

7. Upload the certificate you prepared.

8. Enter Description.

9. Select Add.

   

Update the bot app code

Follow the steps to update the bot app code:

1. Open your bot app project in Visual Studio or Visual Studio Code.

2. Update your code.

   JavaScript

       const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
       MicrosoftAppId: config.botId,
       CertificatePrivateKey: '{your private key}',
       CertificateThumbprint: '{your cert thumbprint}',
       MicrosoftAppType: "MultiTenant",
       });
   
       const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
       {},
       credentialsFactory
       );
   
       const adapter = new CloudAdapter(botFrameworkAuthentication);
   

   C#

       builder.Services.AddSingleton<ServiceClientCredentialsFactory>((e) => new CertificateServiceClientCredentialsFactory("{your certificate}", "{your entra id}"));
   

3. Ensure you test your bot to confirm the operation aligns with the updated authentication.

Delete bot secret

Ensure that your bot app uses the certificate for authentication before you delete the bot secret.

To delete the bot secret:

1. Go to Azure portal.

2. Select App registrations.

   

3. Select your registered app.

4. In the left pane, under Manage, select Certificates & secrets.

5. Delete the secrets from Entra.

   

Your bot app now uses the certificate for authentication.

I ran into an issue

Update to MSI-based authentication

To update your bot app to use MSI-based authentication:

1. Create bot service with MSI type in Azure AD
2. Update your bot app code for MSI
3. Delete bot secret

Note

The Azure Bot service ID and type can't be modified after creation.

Create bot service with MSI type in Azure AD

To create a new Azure Bot service with MSI type, follow these steps:

1. Go to Azure portal.

2. Go to Home.

3. Select + Create a resource.

4. In the search box, enter Azure Bot.

5. Select the Enter key.

6. Select Azure Bot.

7. Select Create.

   

8. Enter the bot name in Bot handle.

9. Select your Subscription from the dropdown list.

10. Select your Resource group from the dropdown list.

    

    If you don't have an existing resource group, you can create a new resource group. To create a new Azure bot service and managed identity, follow these steps:

    1. Select Create new.
    2. Enter the resource name and select OK.
    3. Select a location from New resource group location dropdown list.

    

11. Under Microsoft App ID, select Type of App as User-Assigned Managed Identity.

12. From the Creation type, select Create new Microsoft App ID.

    

    OR

    You can manually create a managed identity first, then create the Azure Bot using the Use existing app registration.

13. Update the new Azure Bot messaging endpoint and channels to match those of the old service.

14. Go to your apps hosting resource.

15. Select Settings > Identity > User assigned.

16. Add the managed identity that you've created.

Update your bot app code for MSI

To update the bot app code for MSI, follow these steps:

1. Open your bot app project in Visual Studio or Visual Studio Code.

2. Update your code.

   JavaScript

       const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
       MicrosoftAppType: 'UserAssignedMsi',
       MicrosoftAppId: '{your MSI’s client ID}',
       MicrosoftAppTenantId: '{your MSI’s tenant ID}',
       });
   
       const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
       {},
       credentialsFactory
       );
   
       const adapter = new CloudAdapter(botFrameworkAuthentication);
   

   C#

       builder.Configuration["MicrosoftAppType"] = "UserAssignedMsi";
       builder.Configuration["MicrosoftAppId"] = "{your MSI’s client ID}";
       builder.Configuration["MicrosoftAppTenantId"] = "{your MSI’s tenant ID}";
       builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
   

3. Update the BOT_ID in your .env file.

4. Ensure you test your bot to confirm its operation aligns with the updated authentication.

Delete bot secret

Ensure that your bot app uses the certificate for authentication before you delete the bot secret.

To delete the bot secret:

1. Go to Azure portal.

2. Select App registrations.

   

3. Select your registered app.

4. In the left pane, under Manage, select Certificates & secrets.

5. Delete the secrets from Entra.

   

Your bot app now uses MSI for authentication.

I ran into an issue

See Also

• Build bots for Teams
• Build message extensions
• Authenticate users in Microsoft Teams