Enable Client Certificate Auth for Bot Framework App

Posted by

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Community Hub.

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 users (github.com)


Happy Bot Framework Development!


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.