Update

msteams-platform/TOC.yml

@@ -175,6 +175,8 @@
           - name: Add single sign-on to Teams app
             href: toolkit/add-single-sign-on.md
           - name: Using existing Microsoft Entra app in TeamsFx project
+            href: toolkit/use-existing-aad-app.md
+          - name: Update bot/ME project to use Certificate or MSI for Authentication
             href: toolkit/use-existing-aad-app.md  
         - name: Customize Manifest
           items:

msteams-platform/toolkit/update-bot-me-project-to-use-certificate-or-msi-for-authentication.md

@@ -9,115 +9,157 @@ ms.localizationpriority: high
 
 # Update bot/ME project to use Certificate or MSI for Authentication
 
-## Introduction
-
-This guide provides step-by-step instructions to update your existing bot project from using a Bot ID and secret for authentication to using a certificate or Managed Service Identity (MSI). This change helps address compliance concerns related to using Entra ID with a secret.
+Update your bot project to authenticate using a certificate or Managed Service Identity (MSI), rather than a bot ID and secret. This addresses compliance issues associated with the use of Entra ID and a secret.
 
 ## Prerequisites
 
-Before proceeding, ensure that you have a Teams bot app deployed to Azure with the following resources:
-
-- An Azure Bot Service.
-- An Entra ID with a secret used for bot authentication.
-- A resource that hosts your bot app (e.g., Azure App Service, Azure Functions).
+Ensure that you have a Teams bot app deployed to Azure with the following resources:
 
-## Updating to Certificate-Based Authentication
+* 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, and so on.
 
-### Step 1: Prepare and Upload the Certificate
+## Update to Certificate based Authentication
 
 1. Obtain a certificate and private key.
-2. Upload the certificate to your Entra ID.
 
-### Step 2: Update Your Code and Deploy
+1. Go to [Azure portal.](https://ms.portal.azure.com)
+
+1. Select **App registrations**.
+
+    :::image type="content" source="../../assets/images/include-files/azure-app-registration.png" alt-text="Screenshot shows the Azure services to select App registrations.":::
+
+1. Select your registered app.
+
+1. In the left pane, under **Manage**, select **Certificates & secrets**.
+
+1. Under **Certificates**, select **Upload certificate**.
+
+    :::image type="content" source="../assets/images/teams-toolkit-v2/certificates-secrets.png" alt-text="Screenshot shows the certificates and secrets option.":::
+
+    The **Upload a certiificate** window appears.
+
+    > [!NOTE]
+    > Upload a certiificate (public key) with one of the following file types: .cer, .pem, .crt
+
+1. Upload a certificate.
+
+1. Enter **Description**.
+
+1. Select **Add**.
+
+    :::image type="content" source="../assets/images/teams-toolkit-v2/upload-certificate.png" alt-text="Screenshot shows the upload certificate option.":::
+
+1. Update your code and deploy.
+
+    ```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);
+    ```
+
+    ```csharp
+    builder.Services.AddSingleton<ServiceClientCredentialsFactory>((e) => new CertificateServiceClientCredentialsFactory("{your certificate}", "{your entra id}"));
+    ```
+
+1. Ensure you test your bot to confirm its operation aligns with the updated authentication.
 
-#### For TypeScript/JavaScript Projects
+1. Delete the secrets from Entra.
 
-```javascript
-const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
-  MicrosoftAppId: config.botId,
-  CertificatePrivateKey: '{your private key}',
-  CertificateThumbprint: '{your cert thumbprint}',
-  MicrosoftAppType: "MultiTenant",
-});
+    :::image type="content" source="../assets/images/teams-toolkit-v2/delete-client-secret-value.png" alt-text="Screenshot shows the delete client secret value.":::
 
-const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
-  {},
-  credentialsFactory
-);
+## Update to MSI based Authentication
 
-const adapter = new CloudAdapter(botFrameworkAuthentication);
-```
+> [!NOTE]
+> The **Azure Bot** service ID and type can't be modified after creation.
 
-#### For C# Projects
+To create a new **Azure Bot** service with MSI type, follow these steps:
 
-```csharp
-builder.Services.AddSingleton<ServiceClientCredentialsFactory>((e) => 
-  new CertificateServiceClientCredentialsFactory("{your certificate}", "{your Entra ID}")
-);
-```
+1. Go to **Home**.
+1. Select **+ Create a resource**.
+1. In the search box, enter **Azure Bot**.
+1. Select **Enter**.
+1. Select **Azure Bot**.
+1. Select **Create**.
 
-### Step 3: Test Your Bot App
+    :::image type="content" source="../../assets/images/include-files/azure-bot.png" alt-text="Screenshot shows the creation of Azure bot.":::
 
-Ensure your bot functions correctly with the updated authentication method.
+1. Enter the bot name in **Bot handle**.
+1. Select your **Subscription** from the dropdown list.
+1. Select your **Resource group** from the dropdown list.
 
-### Step 4: Clean Up Secrets
+    :::image type="content" source="../../assets/images/include-files/create-azure-bot.png" alt-text="Screenshot shows the option resource group and subscription in the Azure portal.":::
 
-Once verified, delete the secrets in your Entra ID to maintain security compliance.
+    If you don't have an existing resource group, you can create a new resource group. To create a new resource group, follow these steps:
 
-## Updating to MSI-Based Authentication
+    1. Select **Create new**.
+    1. Enter the resource name and select **OK**.
+    1. Select a location from **New resource group location** dropdown list.
 
-### Step 1: Create a New Azure Bot Service with MSI
+    :::image type="content" source="../../assets/images/include-files/new-resource-location.png" alt-text="Screenshot shows the new resource group option in Azure portal.":::
 
-Since the Azure Bot Service’s ID and type cannot be modified after creation, follow these steps:
+1. Under **Pricing**, select **Change plan**.
 
-1. Create a new Azure Bot Service, selecting **User-Assigned Managed Identity** as the type and **Create new Microsoft App ID** as the creation type. This will automatically create the Azure Bot Service and the associated managed identity.
+    :::image type="content" source="../../assets/images/include-files/pricing-tier.png" alt-text="Screenshot shows the pricing option in Azure portal.":::
 
-   *Alternatively*: You can manually create a managed identity first, then create the Azure Bot Service using the "Use existing app registration" option.
+1. Select **FO Free** > **Select**.
 
-2. Update the new Azure Bot Service’s messaging endpoint and channels to match those of the old service.
+    :::image type="content" source="../../assets/images/include-files/pricing-free.png" alt-text="Screenshot shows the option to select free.":::
 
-### Step 2: Assign the Managed Identity to Your Hosting Resource
+1. Under **Microsoft App ID**, select **Type of App** as **User-Assigned Managed Identity**.
 
-1. Navigate to your app’s hosting resource.
-2. Select **Settings > Identity > User assigned**.
-3. Add the managed identity created in the previous step.
+1. In the **Creation type**, select **Create new Microsoft App ID**.
 
-### Step 3: Update Your Code and Deploy
+    :::image type="content" source="../assets/images/teams-toolkit-v2/microsoft-app-id.png" alt-text="Screenshot shows the microsoft app id option.":::
 
-#### For TypeScript/JavaScript Projects
+OR
 
-```javascript
-const credentialsFactory = new ConfigurationServiceClientCredentialFactory({
-  MicrosoftAppType: 'UserAssignedMsi',
-  MicrosoftAppId: '{your MSI’s client ID}',
-  MicrosoftAppTenantId: '{your MSI’s tenant ID}',
-});
+1. You can manually create a managed identity first, then create the **Azure Bot** using the **Use existing app registration**.
 
-const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(
-  {},
-  credentialsFactory
-);
+1. Update the new **Azure Bot** messaging endpoint and channels to match those of the old service.
 
-const adapter = new CloudAdapter(botFrameworkAuthentication);
-```
+1. Go to your apps hosting resource.
 
-#### For C# Projects
+1. Select **Settings > Identity > User assigned**.
 
-```csharp
-builder.Configuration["MicrosoftAppType"] = "UserAssignedMsi";
-builder.Configuration["MicrosoftAppId"] = "{your MSI’s client ID}";
-builder.Configuration["MicrosoftAppPassword"] = "{your MSI’s tenant ID}";
-builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
-```
+1. Add the managed identity that you've created.
 
-### Step 4: Update the `BOT_ID` Value in the `.env` File
+1. Update your code and deploy.
 
-Update the `BOT_ID` value in your `.env` file to reflect your newly created managed identity’s client ID.
+    ```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);
+    ```
 
-### Step 5: Test Your Bot App
+    ```csharp
+    builder.Configuration["MicrosoftAppType"] = "UserAssignedMsi";
+    builder.Configuration["MicrosoftAppId"] = "{your MSI’s client ID}";
+    builder.Configuration["MicrosoftAppPassword"] = "{your MSI’s tenant ID}";
+    builder.Services.AddSingleton<BotFrameworkAuthentication, ConfigurationBotFrameworkAuthentication>();
+    ```
 
-Verify that your bot operates as expected with the updated authentication.
+1. Update the `BOT_ID` in your `.env` file.
 
-### Step 6: Clean Up Unneeded Resources
+1. Ensure you test your bot to confirm its operation aligns with the updated authentication.
 
-If everything is functioning correctly, you can delete the old Azure Bot Service and the old Entra ID to clean up unnecessary resources.
+1. Delete the old Azure bot and the Entra ID.