This sample demonstrates how to integrate Web Chat in a way that 1) does not expose your Direct Line secret to the browser, and 2) mitigates user impersonation by not allowing the client to set its own user ID.

See the Motivation section below for more background on these issues.

There is no hosted demo for this sample yet.

This demo includes a bot that you will run locally, so before running the code, you will have to set up an Azure Bot Service resource.

1. Clone the code
2. Setup Azure Bot Services
3. Prepare and run the code

To host this demo, you will need to clone the code and run locally.

We prefer to use Bot Channel Registration during development. This will help you diagnose problems locally without deploying to the server and speed up development.

You can follow our instructions on how to setup a new Bot Channel Registration. Then save the resulting IDs/secrets into the appropriate local environment files, depending on your language:

During development, you will run your bot locally. Azure Bot Services will send activities to your bot thru a public URL. You can use ngrok to expose your bot server on a public URL.

1. Run ngrok http -host-header=localhost:3978 3978
2. Update your Bot Channel Registration. You can use Azure CLI or Azure Portal
   
   • Via Azure CLI
     
     • Run az bot update --resource-group <your-bot-rg> --name <your-bot-name> --subscription <your-subscription-id> --endpoint "https://a1b2c3d4.ngrok.io/api/messages"
   • Via Azure Portal
     
     • Browse to your Bot Channel Registration
     • Select "Settings"
     • In "Configuration" section, set "Messaging Endpoint" to https://a1b2c3d4.ngrok.io/api/messages

1. Under each of bot, and web folder, run the following commands, depending on your language:

   JavaScript

   1.  
   2.  
   C#

   1.  
   2.  

2. Browse to http://localhost:5000/ to start the demo

• Type anything to the bot. It should reply with your user ID, which will stay the same for the duration of the session.
• Open a new browser tab to http://localhost:5000 and type anything to the bot. It should reply with a different user ID since it has generated a different Direct Line token.

The code is organized into two separate folders:

• /bot/ is the bot server
• /web/ is the REST API for generating Direct Line tokens
  
  • GET /api/directline/token will generate a new Direct Line token for the app. The token will be bound to a random user ID.
  • During development-time, it will also serve the bot server via /api/messages/
    
    • To enable this feature, add PROXY_BOT_URL=http://localhost:3978 to /web/.env

In this sample, the user is anonymous, so the API randomly generates a user ID:

The user ID is prefixed with "dl_" as required by the Direct Line token API.

The backend API calls the Direct Line API to retrieve a Direct Line token. Notice that we pass the user ID in the body of the request:

The resulting Direct Line token will be bound to the passed user ID.

The client-side page calls the API and uses the resulting Direct Line token to render Web Chat:

// public/index.html

const { token } = await fetchJSON('/api/directline/token');

WebChat.renderWebChat(
    {
        directLine: WebChat.createDirectLine({ token }),
        styleOptions: {
            backgroundColor: 'rgba(255, 255, 255, .8)'
        }
    },
    document.getElementById('webchat')
);

Note that we do not specify a user ID when initiating Web Chat. Direct Line will handle sending the user ID to the bot based on the token.

This sample includes multiple parts:

• The UI is a static HTML/JS web page with Web Chat integrated via JavaScript bundle. It makes a POST request to the backend API and uses the resulting Direct Line token to render Web Chat.
• The backend API generates Direct Line tokens. Each generated token is bound to a new, randomly-generated user ID.
• The bot is a bare-bones bot that responds to every message by sending the user's ID.

When embedding Web Chat into a site, you must provide either your Direct Line secret or a Direct Line token so that Web Chat can communicate with the bot. The Direct Line secret can be used to access all of the bot's conversations, and it doesn't expire. A Direct Line token can only be used to access a single conversation, and it does expire. See the Direct Line Authentication documentation for more information.

Therefore, embedding Web Chat using the Direct Line secret directly is strongly discouraged because it would expose your secret on the client-side. Instead, the recommended approach is to exchange the secret for a Direct Line token on the server-side. This sample shows how to obtain and use the token.

Web Chat allows you to specify a user ID on the client-side, which will be sent in activities to the bot. However, this is susceptible to user impersonation because a malicious user could modify their user ID. Since the user ID typically isn't verified, this is a security risk if the bot stores sensitive data keyed on the user ID. For example, the built-in user authentication support in Azure Bot Service associates access tokens with user IDs.

To avoid impersonation, the recommended approach is for the server to bind a user ID to the Direct Line token. Then any conversation using that token will send the bound user ID to the bot. However, if the client is going to provide the user ID to the server, it is important for the server to validate the ID somehow (see below). Otherwise, a malicious user could still modify the user ID being sent by the client.

To keep things simple, this sample generates a random user ID on the server-side and binds it to the Direct Line token. While this mitigates impersonation concerns, the downside is that users will have a different ID every time they talk to the bot.

The .env / appsettings.json files hold the environment variable critical to run the service. These are usually security-sensitive information and must not be committed to version control. Although we recommend to keep them in Azure Key Vault, for simplicity of this sample, we would keep them in local environment files.

To ease the setup of this sample, here is the template of the local environment files for each language.

Instead of randomly generating user IDs, the backend API could leverage a user's existing identity from a true identity provider. The user would first sign in to the site before talking to the bot. That way, if the user signed in using the same identity on a different browser or device, the user ID would be the same. This would also prevent user impersonation because we could verify the user's identity with the identity provider before issuing a Direct Line token.

The flow could be:

1. The user signs in to the web app.
2. The web app calls the backend API for generating Direct Line tokens, providing a verifiable user token.
3. The backend API verifies the user token with the identity provider.
4. The backend API uses the token to get an ID for the user. (The specifics will vary based on the identity provider and type of token.)
5. The backend API generates a Direct Line token bound to the user ID (just as this sample does) and returns it to the web app.

• Setting up a new Bot Channel Registration
• Generating a Direct Line token
• Enhanced Direct Line Authentication feature