[DotNet] Add details to README in certificate samples

samples/csharp_dotnetcore/84.bot-authentication-certificate/AuthCertificateBot.csproj

@@ -6,8 +6,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.Identity" Version="1.10.2" />
-    <PackageReference Include="Azure.Security.KeyVault.Certificates" Version="4.5.1" />
+    <PackageReference Include="Azure.Identity" Version="1.11.3" />
+    <PackageReference Include="Azure.Security.KeyVault.Certificates" Version="4.6.0" />
     <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="6.0.7" />
     <PackageReference Include="Microsoft.Bot.Builder.Dialogs" Version="4.22.0" />
     <PackageReference Include="Microsoft.Bot.Builder.Integration.AspNet.Core" Version="4.22.0" />

samples/csharp_dotnetcore/84.bot-authentication-certificate/README.md

@@ -2,7 +2,11 @@
 
 Bot Framework v4 bot authentication using Certificate
 
-This bot has been created using [Bot Framework](https://dev.botframework.com/), is shows how to use the bot authentication capabilities of Azure Bot Service. In this sample, we use a local or KeyVault certificate to create the Bot Framework Authentication.
+This bot has been created using [Bot Framework](https://dev.botframework.com/), it shows how to use the bot authentication capabilities of Azure Bot Service. In this sample, we use a local or KeyVault certificate to create the Bot Framework Authentication.
+
+## Interacting with the bot
+
+This sample uses the bot authentication capabilities of Azure Bot Service, providing features to make it easier to develop a bot that authenticates users using digital security certificates. You just need to provide the certificate data linked to the managed identity and run the bot, then communicate with it to validate its correct authentication.
 
 ## Prerequisites
 
@@ -13,99 +17,180 @@ This bot has been created using [Bot Framework](https://dev.botframework.com/),
   dotnet --version
   ```
 
+- [Ngrok](https://ngrok.com/) latest version.
+
+## SSL/TLS certificate
+
+An SSL/TLS certificate is a digital object that allows systems to verify identity and subsequently establish an encrypted network connection with another system using the Secure Sockets Layer/Transport Layer Security (SSL/TLS) protocol. Certificates are issued using a cryptographic system known as public key infrastructure (PKI). PKI allows one party to establish the identity of another through the use of certificates if they both trust a third party, known as a certificate authority. SSL/TLS certificates therefore function as digital identity documents that protect network communications and establish the identity of websites on the Internet as well as resources on private networks.
+
 ## To try this sample
 
+- Setup ngrok
+  1. Run ngrok - point to port 3978
+
+    ```bash
+    ngrok http --host-header=rewrite 3978
+    ```
+
+- Setup a Bot
+  1. Register a bot with Azure Bot Service, following the instructions [here](https://docs.microsoft.com/azure/bot-service/bot-service-quickstart-registration?view=azure-bot-service-3.0).
+
+  2. While registering the bot, use `https://<your_tunnel_domain>/api/messages` as the messaging endpoint.
+      > NOTE: When you create your bot you will create a Microsoft App ID - make sure you keep this for later.
+
 - Clone the repository
 
     ```bash
     git clone https://github.com/microsoft/botbuilder-samples.git
     ```
 
-- Set app settings variables
+- Create and configure the SSL/TSL certificate. In this sample we use two possible options to create and set an SSL/TSL certificate. Below is a step-by-step description of each one:
 
-  - MicrosoftAppType: Type of the App.
+  ### Using local environment
+  - This option requires the following app settings variables:
 
-  - MicrosoftAppId: App Id of your bot.
+    - MicrosoftAppId: App Id of your bot.
 
-  - MicrosoftAppTenantId: Tenant Id to which your bot belongs.
+    - MicrosoftAppType: Type of the App(optional).
 
-  - KeyVaultName: Name of the KeyVault containing the certificate.
+    - MicrosoftAppTenantId: Tenant Id to which your bot belongs(optional).
 
-  - CertificateName: Name of the certificate in the KeyVault.
+  1. Intall and configure [OpenSSL](https://www.openssl.org/source/) with the latest version
+    - Download the latest version source and add the folder to the [environment variables](https://www.java.com/en/download/help/path.html) path.
+      ```bash
+      setx path "%path%;<OpenSSL path here> 
+      i.e
+      setx path "%path%;C:\Program Files\openssl-3.3.0"
+      ```
 
+  2. Run the following command in PowerShell
+       - For global environment certificate(Use admin PowerShell) execute:
 
-- Run the bot from a terminal or from Visual Studio:
+      ```
+      $cert = New-SelfSignedCertificate -CertStoreLocation "." -Subject "CN=<certificate-name>" -KeySpec KeyExchange
+      ```
 
-  A) From a terminal, navigate to `samples/csharp_dotnetcore/84.bot-authentication-certificate`
+      ![Global Certificate Command](Images/Local/GlobalCertificateCommand.png)
 
-  ```bash
-  # run the bot
-  dotnet run
-  ```
+       - For current user certificate execute:
 
-  B) Or from Visual Studio
+      ```
+      $cert = New-SelfSignedCertificate -CertStoreLocation "Cert:\CurrentUser\My" -Subject "CN=<certificate-name>" -KeySpec KeyExchange
+      ```
 
-  - Launch Visual Studio
-  - File -> Open -> Project/Solution
-  - Navigate to `samples/csharp_dotnetcore/84.bot-authentication-certificate` folder
-  - Select `AuthCertificateBot.csproj` file
-  - Press `F5` to run the project
+      ![User Certificate Command](Images/Local/UserCertificateCommand.png)
 
-## Testing the bot using Bot Framework Emulator
+  3. Then, type _Manage computer certificates(global environment certificate)_ or _Manage User Certificates(current user certificate)_ in the Windows search bar and hit enter.
 
-[Bot Framework Emulator](https://github.com/microsoft/botframework-emulator) is a desktop application that allows bot developers to test and debug their bots on localhost or running remotely through a tunnel.
+      ![User Certificate Search](Images/Local/CertificateSearch.png)
 
-- Install the latest Bot Framework Emulator from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
+  4. The certificate will be located in the _user certificates_ folder, under _personal_ directory.
 
-### Connect to the bot using Bot Framework Emulator
+      ![Certificate Directory](Images/Local/CertificateDirectory.png)
 
-- Launch Bot Framework Emulator
-- File -> Open Bot
-- Enter a Bot URL of `http://localhost:3978/api/messages`
+  5. Export the certificate to _pfx_ format including the key.
 
-## Interacting with the bot
+      ![Certificate Export Steps](Images/Local/CertificateExportSteps1.png)
+      ![Certificate Export Steps](Images/Local/CertificateExportSteps2.png)
 
-This sample uses the bot authentication capabilities of Azure Bot Service, providing features to make it easier to develop a bot that authenticates users using digital security certificates. You just need to provide the certificate data linked to the managed identity and run the bot, then communicate with it to validate its correct authentication.
+  6. Go to the certificate location and run the following command to generate a _pem_ file (the command will ask for the password generated in the previous step):
 
-## SSL/TLS certificate
+      ```
+      OpenSSL pkcs12 -in .\<certificate-name>.pfx -out <certificate-name>.pem –nodes -nokeys
+      ```
 
-An SSL/TLS certificate is a digital object that allows systems to verify identity and subsequently establish an encrypted network connection with another system using the Secure Sockets Layer/Transport Layer Security (SSL/TLS) protocol. Certificates are issued using a cryptographic system known as public key infrastructure (PKI). PKI allows one party to establish the identity of another through the use of certificates if they both trust a third party, known as a certificate authority. SSL/TLS certificates therefore function as digital identity documents that protect network communications and establish the identity of websites on the Internet as well as resources on private networks.
+      ![Pem File Command No Key](Images/Local/PemCommandNoKey.png)
+
+  7. Upload the generated certificate to the Azure app registration.
+
+      ![Certificate Upload](Images/Local/CertificateUpload.png)
+
+  8. To read the certificate in the bot, the _pem_ file must include the key, then go to the certificate location and run the following command to generate a _pem_ file with key:
+      ```
+      OpenSSL pkcs12 -in .\<certificate-name>.pfx -out <certificate-with-key-name>.pem –nodes
+      ```
+
+      ![Pem Command With Key](Images/Local/PemCommandWithKey.png)
+
+  9. In the sample code, go to the [Startup](Startup.cs) class and uncomment the line of code that reads the local certificate and write the name of the certificate in _pem_ format inside the _CreateFromPemFile_ method.
+  Be sure to comment out or remove the lines of code that use Azure KeyVault to avoid errors.
+      > NOTE: Here the value of MicrosoftAppId and MicrosoftAppTenantId are needed to generate the credentials.
+
+      ![Certificate Reading](Images/Local/CertificateReading.png)
+
+  ### Using KeyVault
+  - This option requires the following app settings variables:
+
+    - MicrosoftAppId: App Id of your bot.
+
+    - KeyVaultName: Name of the KeyVault containing the certificate.
+
+    - CertificateName: Name of the certificate in the KeyVault.
+
+    - MicrosoftAppType: Type of the App(optional).
+
+    - MicrosoftAppTenantId: Tenant Id to which your bot belongs(optional).
+
+  1. Create a [KeyVault](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-portal) resource.
+
+  2. Assign KeyVault [permissions](https://learn.microsoft.com/en-us/azure/key-vault/general/rbac-guide?tabs=azure-cli) to the current user if needed to create a new certificate.
+
+  3. Under the Certificates section, hit on Generate/Import, complete the form, and create the certificate in _pem_ format.
 
-## How to create an SSL/TLS certificate
+      ![Generate Certificate](Images/KeyVault/GenerateCertificate.png)
+      ![Create Certificate](Images/KeyVault/CreateCertificate.png)
 
-There are two possible options to create SSL/TSL certificate. Below is a step-by-step description of each one:
+  4. Go to the details of the certificate and download it in _CER_ format to avoid the export of the private key.
 
-### Using local environment
+      ![Certificate Details](Images/KeyVault/CertificateDetails.png)
+      ![Download Certificate](Images/KeyVault/DownloadCertificate.png)
 
-1. Run the following command in a local PowerShell
+      >NOTE: If you downloaded it in _PEM_ format, it will be neccesary to remove the private key by executing the following command:
+      ```
+      OpenSSL pkcs12 -in .\<certificate-name>.pem -export -out .\<certificate-without-key-name>.pem -nokeys
+      ```
 
-```
-$cert = New-SelfSignedCertificate -CertStoreLocation "<directory-to-store-certificate>" -Subject "CN=<certificate-name>" -KeySpec KeyExchange
-```
+      ![Remove Keys](Images/KeyVault/RemoveKeys.png)
 
-1. Then, type _Manage User Certificates_ in the Windows search bar and hit enter
+      >NOTE: If you used _pkcs_ format in the creation step and downloaded it in _PFX_ format, install OpenSSL and follow the step 6 of the previous [section](#using-local-environment) to convert it to _pem_ format without keys.
 
-2. The certificate will be located in the _user certificates_ folder, under _personal_ directory.
+  5. Upload the certificate to the Azure app registration.
 
-3. Export the certificate to _pfx_ format including the key(The default location is _system32_ folder).
+      ![Upload Cer Certificate](Images/KeyVault/UploadCerCertificate.png)
 
-4. Go to the certificate location and run the following command to generate a _pem_ file:
+  6. In the sample code, go to the [Startup](Startup.cs) class and uncomment the line of code that reads the keyvault certificate and verify that the keyvault credentials are completed in the [appsettings](appsettings.json) file.
+  Be sure to comment out or remove the lines of code that use local certificate to avoid errors.
+      > NOTE: Here the value of MicrosoftAppId and MicrosoftAppTenantId are also needed to generate the credentials.
 
-```
-OpenSSL pkcs12 -in <certificate-name>.pfx -out c:\<certificate-name>.pem –nodes
-```
+      ![Certificate Reading](Images/KeyVault/CertificateReading.png)
 
-5. Upload the generated certificate to the Azure app registration.
+  7. In the current sample context, log into Azure to obtain the default credentials by executing the following command.
+      ```
+      az login
+      ```
 
-### Using KeyVault
+- Run the bot from a terminal or from Visual Studio:
+
+  A) From a terminal, navigate to `samples/csharp_dotnetcore/84.bot-authentication-certificate`
+
+  ```bash
+  # run the bot
+  dotnet run
+  ```
 
-1. Create a KeyVault resource and assign _the KeyVault Administrator_ role to have permission to create a new certificate.
+  B) Or from Visual Studio
+
+  - Launch Visual Studio
+  - File -> Open -> Project/Solution
+  - Navigate to `samples/csharp_dotnetcore/84.bot-authentication-certificate` folder
+  - Select `AuthCertificateBot.csproj` file
+  - Press `F5` to run the project
 
-2. Under the Certificates section, hit on Generate/Import, complete the form, and create the certificate in PEM format.
+## Testing the bot using Azure Bot
 
-3. Go to the details of the certificate that you created and enable it.
+Go to the Azure bot resource created previously, select the _Test in Web Chat_ option under the _Settings_ section and start talking to the bot.
 
-4. Download the certificate in CER format and then upload it to the Azure app registration.
+![Bot Conversation](Images/BotConversation.png)
 
 ## Deploy the bot to Azure
 

samples/csharp_dotnetcore/84.bot-authentication-certificate/Startup.cs

@@ -4,6 +4,7 @@
 using System;
 using Azure.Identity;
 using Azure.Security.KeyVault.Certificates;
+using System.Security.Cryptography.X509Certificates;
 using Microsoft.AspNetCore.Builder;
 using Microsoft.AspNetCore.Hosting;
 using Microsoft.Bot.Builder;
@@ -32,18 +33,18 @@ public void ConfigureServices(IServiceCollection services)
                 options.SerializerSettings.MaxDepth = HttpHelper.BotMessageSerializerSettings.MaxDepth;
             });
 
-            // Using KeyVault
+            //// Using KeyVault
             // Create a new certificate client using the default credential from Azure.Identity using environment variables previously set,
             // including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
             var keyVaultUri = $"https://{_configuration["KeyVaultName"]}.vault.azure.net";
             var credential = new DefaultAzureCredential();
             var client = new CertificateClient(new Uri(keyVaultUri), credential);
 
-            //Get certificate in X509Certificate format 
+            //Get certificate in X509Certificate format
             var certificateName = _configuration["CertificateName"];
-            var certificate =  client.DownloadCertificate(certificateName).Value;
+            var certificate = client.DownloadCertificate(certificateName).Value;
 
-            // Using a local certificate
+            //// Using a local certificate
             //var certificate = X509Certificate2.CreateFromPemFile(@"{Pem file path}");
 
             // Create the ClientCredentialsFactory to user certificate authentication

samples/csharp_dotnetcore/85.bot-authentication-sni/AuthSNIBot.csproj

@@ -6,8 +6,8 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="Azure.Identity" Version="1.10.2" />
-    <PackageReference Include="Azure.Security.KeyVault.Certificates" Version="4.5.1" />
+    <PackageReference Include="Azure.Identity" Version="1.11.3" />
+    <PackageReference Include="Azure.Security.KeyVault.Certificates" Version="4.6.0" />
     <PackageReference Include="Microsoft.AspNetCore.Mvc.NewtonsoftJson" Version="6.0.7" />
     <PackageReference Include="Microsoft.Bot.Builder.Dialogs" Version="4.22.0" />
     <PackageReference Include="Microsoft.Bot.Builder.Integration.AspNet.Core" Version="4.22.0" />