Skip to content

Latest commit

 

History

History

85.bot-authentication-sni

README.md

Authentication Bot using Subject Name/Issuer

Bot Framework v4 bot authentication using Subject Name/Issuer

This bot has been created using Bot Framework, it shows how to use the bot authentication capabilities of Azure Bot Service. In this sample, we use a local or KeyVault certificate and the MSAL Subject Name/Issuer configuration to create the Bot Framework Authentication.

Important

Microsoft's first-party resources are required to test this sample.

In this guide, we'll explain how to consume a certificate in Bot Framework with the following options:

  1. Local environment
  2. KeyVault

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.

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.

Subject Name and Issuer (SNI) Authentication

Certificate Subject Name and Issuer (SNI) based authentication is currently available only for Microsoft internal (first-party) applications. External (third-party) apps cannot use SNI because SNI is based on the assumption that the certificate issuer is the same as the tenant owner. This can be guaranteed for some first-party tenants, but not for third-party. So there are no plans to bring SNI to third-party apps. For more details about this feature and code examples see this SNI issue and a wiki page.

Prerequisites

# determine node version
node --version

To try this sample

  • Setup ngrok

    1. Follow this guide to install and configure ngrok in your environment.
    2. Run ngrok with the following command. 
      ngrok http --host-header=rewrite 3978

  • Setup a Bot

Note

The app registration used here can be Single or Multi tenant.

  1. Register a bot with Azure Bot Service, following the instructions here.
  2. After registering the bot, use <NGROK_FORWARDING_DOMAIN>/api/messages as the messaging endpoint.

    NOTE: make sure to take note of the Microsoft App Id as we'll need this for later.

  • Clone the repository

    git clone https://github.com/microsoft/botbuilder-samples.git

  • Setup the app registration

    Go to the app registration used by the azure bot and add the following configuration to the manifest:

    "trustedCertificateSubjects": [
    {
        "authorityId": "00000000-0000-0000-0000-000000000001",

        "subjectName": "certificate_subject_name",

        "revokedCertificateIdentifiers": []
    }
]

  • Configure the SSL/TSL certificate. This sample requires an existing certificate issued by an integrated CA(Microsoft). We have two options to configure it in the bot. Below is a step-by-step description of each one:

    Using local environment

    1. Configure the following app settings variables:
    • MicrosoftAppId: App Id of your bot (gathered from the Setup a Bot step).
    • CertificateThumbprint: Thumbprint of the certificate uploaded to the app registration.
    • MicrosoftAppTenantId: Tenant Id to which your bot belongs (optional for MultiTenant apps).
    1. Install and configure OpenSSL with the latest version
    • Download the latest version source and add the folder to the environment variables path. 
      setx path "%path%;<OpenSSL path here> 
e.g:
setx path "%path%;C:\Program Files\openssl-3.3.0"

    1. Generate a pem file without key:

      • If your certificate is in pfx format execute the following command:
      OpenSSL pkcs12 -in .\<certificate-name>.pfx -out <certificate-name>.pem –nodes -nokeys

      e.g: Pem File Command No Key

      • If your certificate is in pem format and includes the key, execute the following command to remove the key:
      OpenSSL pkcs12 -in .\<certificate-name>.pem -export -out .\<certificate-without-key-name>.pem -nokeys

      e.g: Pem Export No Key

    2. Upload the generated certificate to the Azure app registration.

      Certificate Upload

    3. To read the certificate in the bot, the pem file must include the key, then if your certificate is in pfx format 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

      e.g: Pem Command With Key

    4. In the sample code, go to the index 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. Be sure to comment out or remove the lines of code that use Azure KeyVault to avoid errors.

      NOTE: Here the value of MicrosoftAppId is needed to generate the credentials.

      Certificate Reading

    Using KeyVault

    1. This option requires the following app settings variables:

      • KeyVaultName: Name of the KeyVault containing the certificate.
      • CertificateName: Name of the certificate in the KeyVault.
      • MicrosoftAppId: App Id of your bot (gathered from the Setup a Bot step).
      • MicrosoftAppTenantId: Tenant Id to which your bot belongs (optional for MultiTenant apps).

    2. Import the certificate under the Certificates section, hit on Generate/Import, complete the form, and upload the certificate.

      Generate Import Certificate Import Certificate

    3. Go to the details of the certificate and download it in CER format to avoid the export of the private key.

      Certificate Details Download Certificate

      NOTE: If you downloaded it in PFX/PEM format, it will be neccesary to remove the private key by executing one the following commands:

      OpenSSL pkcs12 -in .\<certificate-name>.pfx -out <certificate-name>.pem –nodes -nokeys
OpenSSL pkcs12 -in .\<certificate-name>.pem -export -out .\<certificate-without-key-name>.pem -nokeys

      e.g: Pem File Command No Key Pem Export No Key

    4. Upload the certificate to the Azure app registration.

      Upload Cer Certificate

    5. In the sample code, go to the index file and uncomment the line of code that reads the keyvault certificate and verify that the keyvault credentials are completed in the .env 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 is also needed to generate the credentials.

      Certificate Reading

    6. In the current sample context, log into Azure to obtain the default credentials by executing the following command:

      az login

Run the bot from a terminal or from Visual Studio:

  • In a terminal, navigate to samples/javascript_nodejs/85.bot-authentication-sni

    cd samples/javascript_nodejs/85.bot-authentication-sni
    • Install modules
    npm install
    • Start the bot
    npm start

Testing the bot using Azure Bot

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.

Bot Conversation

Deploy the bot to Azure

To learn more about deploying a bot to Azure, see Deploy your bot to Azure for a complete list of deployment instructions.

Further reading