You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Jan 5, 2026. It is now read-only.
Bot Framework v4 bot authentication using Certificate
4
8
5
-
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.
9
+
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.
10
+
11
+
In this guide, we'll explain how to create and consume a certificate in Bot Framework with the following options:
12
+
1.[Local environment][#LocalEnv]
13
+
2.[KeyVault][#KeyVaultEnv]
14
+
15
+
## Interacting with the bot
16
+
17
+
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.
18
+
19
+
## SSL/TLS certificate
20
+
21
+
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.
6
22
7
23
## Prerequisites
8
24
9
-
-[Node.js](https://nodejs.org) version 18 or higher
25
+
-[Ngrok](https://ngrok.com/) latest version.
26
+
-[Node.js](https://nodejs.org) version 16.16.0 or higher
10
27
11
28
```bash
12
29
# determine node version
@@ -15,49 +32,167 @@ node --version
15
32
16
33
## To try this sample
17
34
35
+
- Setup ngrok
36
+
1. Follow this [guide](https://ngrok.com/docs/getting-started/?os=windows) to install and configure ngrok in your environment.
37
+
2. Run ngrok with the following command.
38
+
```bash
39
+
ngrok http --host-header=rewrite 3978
40
+
```
41
+
42
+
- Setup a Bot
43
+
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).
44
+
45
+
2. After registering the bot, use `<NGROK_FORWARDING_DOMAIN>/api/messages` as the messaging endpoint.
46
+
> NOTE: make sure to take note of the Microsoft App Id as we'll need this for later.
- In a terminal, navigate to `samples/javascript_nodejs/84.bot-authentication-certificate`
54
+
- 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:
25
55
26
-
```bash
27
-
cd samples/javascript_nodejs/84.bot-authentication-certificate
28
-
```
56
+
### Using local environment
57
+
1. Configure the following app settings variables:
58
+
- MicrosoftAppId: App Id of your bot (gathered from the [Setup a Bot][#TrySample] step).
59
+
- CertificateThumbprint: Thumbprint of the certificate uploaded to the app registration.
60
+
- MicrosoftAppTenantId: Tenant Id to which your bot belongs (optional for MultiTenant apps).
61
+
- MicrosoftAppType: Type of the App (optional for MultiTenant apps).
29
62
30
-
- Install modules
63
+
2. Install and configure [OpenSSL](https://www.openssl.org/source/) with the latest version
64
+
- Download the latest version source and add the folder to the [environment variables](https://www.java.com/en/download/help/path.html) path.
65
+
```bash
66
+
setx path "%path%;<OpenSSL path here>
67
+
e.g
68
+
setx path "%path%;C:\Program Files\openssl-3.3.0"
69
+
```
31
70
32
-
```bash
33
-
npm install
34
-
```
71
+
3. Run the following command in PowerShell
72
+
- For **global environment certificate** execute the following command with **admin privileges**:
4. 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.
90
+
5. The certificate will be located in the _user certificates_ folder, under _personal_ directory.
45
91
46
-
- Install the latest Bot Framework Emulator from [here](https://github.com/Microsoft/BotFramework-Emulator/releases)
7. 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):
55
100
56
-
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.
57
106
58
-
## SSL/TLS certificate
107
+
8. Upload the generated certificate to the Azure app registration. Once uploaded, save the thumbprint value showed in the list of certificates.
59
108
60
-
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.
9. 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:
117
+
118
+
10. In the sample code, go to the [index](index.js) file 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.
119
+
Be sure to comment out or remove the lines of code that use Azure KeyVault to avoid errors.
120
+
> NOTE: Here the value of `MicrosoftAppId` and `CertificateThumbprint` are needed to generate the credentials.
1. This option requires the following app settings variables:
126
+
- KeyVaultName: Name of the KeyVault containing the certificate.
127
+
- CertificateName: Name of the certificate in the KeyVault.
128
+
- MicrosoftAppId: App Id of your bot (gathered from the [Setup a Bot][#TrySample] step).
129
+
- CertificateThumbprint: Thumbprint of the certificate uploaded to the app registration.
130
+
- MicrosoftAppTenantId: Tenant Id to which your bot belongs (optional for MultiTenant apps).
131
+
- MicrosoftAppType: Type of the App (optional for MultiTenant apps).
132
+
133
+
2. Create a [KeyVault](https://learn.microsoft.com/en-us/azure/key-vault/general/quick-create-portal) resource.
134
+
135
+
3. 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.
136
+
137
+
4. Under the Certificates section, hit on Generate/Import, complete the form, and create the certificate in _pem_ format.
>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.
155
+
156
+
6. Upload the certificate to the Azure app registration.
7. 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 [.env](.env) file.
161
+
Be sure to comment out or remove the lines of code that use local certificate to avoid errors.
162
+
> NOTE: Here the value of `MicrosoftAppId` and `CertificateThumbprint` are also needed to generate the credentials.
0 commit comments