Enable Client Certificate Auth for Bot Framework App
Published Nov 02 2022 06:14 AM 6,017 Views

In most cases, Bot Framework Apps use Client ID + Client Secret Key to implement Bot Auth against on the registered Azure AD App. If any direct line request sent to this Bot but cannot provide correct Client ID + Client Secret Key (matched, or another correct pair), the Bot app will return unauthorized failure as well.


A typical Javascript Bot Framework project, if you set MicrosoftAppPassword and MicrosoftAppId in the .env file, run this bot app, and then use Bot Framework Emulator to access the bot. If Emulator cannot provide the correct secure info, the request will fail with unauthorized errors:


message:"The bot's Microsoft App ID or Microsoft App Password is incorrect."





However, some customers have more secure requirements, wonder if the Bot Auth can use Client Certificate instead of secret key, so that they don’t need to put secret key info in the .env file on the bot app side.


It is possible on Bot App side with current Bot framework. I used Node JS bot project as a sample.


To implement this feature, firstly need to have a certificate. The test certificate can be self-signed. To create self-signed certificate:




$cert=New-SelfSignedCertificate -Subject "CN=flbutauth" -CertStoreLocation "Cert:\CurrentUser\My"  -KeyExportPolicy Exportable -KeySpec Signature
Export-Certificate -Cert $cert -FilePath "C:\temp\selfsign.cer" 
$mypwd = ConvertTo-SecureString -String "<your password>" -Force -AsPlainText
Export-PfxCertificate -Cert $cert -FilePath "C:\temp\selfsign.pfx" -Password $mypwd




And then follow this good  article to get private key file “selfsign.key“, with the thumbprint, to use them in https://github.com/freistli/CertAuthJSBot/blob/main/MyServiceClientCredentialsFactory.js.


In the js file, I extend the ServiceClientCredentialsFactory, and generate CertificateAppCredentials.  Replace the default ServiceClientCredentialsFactory here:



You may notice the BotFrameworkAuthentication class is also extended in this sample project, it is optional for Client Cert Bot Auth, I modified it because want to check client claims. 


With above steps, now in .env file we only need to set MicrosoftAppId.


Of course, when you use Bot Framework Emulator, still need to provide AppID and AppPassword as it cannot use certificate so far. On Bot Service, we don’t need to change settings to make it work as Bot Connector is trusted by the AAD registered app.


For more information, feel free to check this git repository:

freistli/CertAuthJSBot: Node.JS Bot App supports Certificate Auth on Bot App side, and SSO OAuth for...


Happy Bot Framework Development!


Version history
Last update:
‎Nov 02 2022 06:58 AM
Updated by: