Skip to content

Commit 30b6856

Browse files
corinagumcorinagum
authored
#2151 Enhance docs on Authentication (#2238)
* #2151 Enhance docs on Authentication * Apply suggestions from code review Co-Authored-By: William Wong <[email protected]> * minor suggested fix
1 parent 607ba96 commit 30b6856

31 files changed

Lines changed: 108 additions & 92 deletions

File tree

‎README.md‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
[![Build Status](https://fuselabs.visualstudio.com/BotFramework-WebChat/_apis/build/status/BotFramework-WebChat-daily?branchName=master)](https://fuselabs.visualstudio.com/BotFramework-WebChat/_build/latest?definitionId=498&branchName=master)
99
[![Coverage Status](https://coveralls.io/repos/github/microsoft/BotFramework-WebChat/badge.svg?branch=master)](https://coveralls.io/github/microsoft/BotFramework-WebChat?branch=master)
1010

11-
This repository contains code for the Bot Framework Web Chat component. The Bot Framework Web Chat component is a highly-customizable web-based client for the Bot Framework V4 SDK. The Bot Framework SDK v4 enable developers to model conversation and build sophisticated bot applications.
11+
This repository contains code for the Bot Framework Web Chat component. The Bot Framework Web Chat component is a highly-customizable web-based client for the Bot Framework V4 SDK. The Bot Framework SDK v4 enables developers to model conversation and build sophisticated bot applications.
1212

1313
This repo is part of the [Microsoft Bot Framework](https://github.com/microsoft/botframework) - a comprehensive framework for building enterprise-grade conversational AI experiences.
1414

@@ -220,7 +220,7 @@ There are several properties that you might pass into your Web Chat React Compon
220220
| `cardActionMiddleware` | A chain of middleware that allows the developer to modify card actions, like Adaptive Cards or suggested actions. The middleware signature is the following: `cardActionMiddleware: () => next => ({ cardAction, getSignInUrl }) => next(cardAction)` |
221221
| `createDirectLine` | A factory method for instantiating the Direct Line object. Azure Government users should use `createDirectLine({ domain: 'https://directline.botframework.azure.us/v3/directline', token });` to change the endpoint. The full list of parameters are: `conversationId`, `domain`, `fetch`, `pollingInterval`, `secret`, `streamUrl`, `token`, `watermark` `webSocket`. |
222222
| `createStore` | A chain of middleware that allows the developer to modify the store actions. The middleware signature is the following: `createStore: ({}, ({ dispatch }) => next => action => next(cardAction)` |
223-
| `directLine` | Specify the DirectLine object with DirectLine token. |
223+
| `directLine` | Specify the DirectLine object with DirectLine token. We strongly recommend using the token API for authentication instead of providing the app with your secret. To learn more about why, see the [authentication documentation](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0) or [connecting client app to bot](#how-to-connect-client-app-to-bot) |
224224
| `disabled` | Disable the UI (i.e. for presentation mode) of Web Chat. |
225225
| `grammars` | Specify a grammar list for Speech (Bing Speech or Cognitive Services Speech Services). |
226226
| `groupTimeStamp` | Change default settings for timestamp groupings. |
@@ -246,6 +246,22 @@ Please note, however:
246246
- Web Chat has no plan to support samples for IE11 (ES5).
247247
- For customers who wish to manually rewrite our other samples to work in IE11, we recommend looking into converting code from ES6+ to ES5 using polyfills and transpilers like [`babel`](https://babeljs.io/docs/en/next/babel-standalone.html).
248248

249+
250+
# How to connect client app to bot
251+
252+
Web Chat provides UI on top of the Direct Line Channel. There are two ways to connect to your bot through HTTP calls from the client: by sending the Bot secret or generating a token via the secret.
253+
254+
<!-- TODO: https://github.com/microsoft/BotFramework-WebChat/issues/2151 -->
255+
<!-- Update the following paragraph and the API table (`directline`) with new documentation when updated docs are published -->
256+
257+
We strongly recommend using the token API instead of providing the app with your secret. To learn more about why, see the [authentication documentation](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0) on the [token API](https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-api-reference?view=azure-bot-service-4.0) and client security.
258+
259+
For further reading, please see the following links:
260+
261+
- [Using Web Chat with Azure Bot Services authentication](https://blog.botframework.com/2018/09/01/using-webchat-with-azure-bot-services-authentication/)
262+
263+
- [Enhanced Direct Line authentication features](https://blog.botframework.com/2018/09/25/enhanced-direct-line-authentication-features/)
264+
249265
# How to test with Web Chat's latest bits
250266

251267
_Testing unreleased features is only available via MyGet packaging at this time._

‎samples/01.a.getting-started-full-bundle/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
<script>
2424
(async function () {
2525
// In this demo, we are using Direct Line token from MockBot.
26-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
27-
// You should never put the Direct Line secret in the browser or client app.
28-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
26+
// Your client code must provide either a secret or a token to talk to your bot.
27+
// Tokens are more secure. To learn about the differences between secrets and tokens
28+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
2929

3030
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3131
const { token } = await res.json();

‎samples/01.c.getting-started-migration/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
<script>
2424
(async function () {
2525
// In this demo, we are using Direct Line token from MockBot.
26-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
27-
// You should never put the Direct Line secret in the browser or client app.
28-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
26+
// Your client code must provide either a secret or a token to talk to your bot.
27+
// Tokens are more secure. To learn about the differences between secrets and tokens
28+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
2929

3030
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3131
const { token } = await res.json();

‎samples/02.a.getting-started-minimal-bundle/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@
3333
<script>
3434
(async function () {
3535
// In this demo, we are using Direct Line token from MockBot.
36-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
37-
// You should never put the Direct Line secret in the browser or client app.
38-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
36+
// Your client code must provide either a secret or a token to talk to your bot.
37+
// Tokens are more secure. To learn about the differences between secrets and tokens
38+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
3939

4040
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
4141
const { token } = await res.json();

‎samples/02.b.getting-started-minimal-markdown/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -33,9 +33,9 @@
3333
<script>
3434
(async function () {
3535
// In this demo, we are using Direct Line token from MockBot.
36-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
37-
// You should never put the Direct Line secret in the browser or client app.
38-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
36+
// Your client code must provide either a secret or a token to talk to your bot.
37+
// Tokens are more secure. To learn about the differences between secrets and tokens
38+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
3939

4040
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
4141
const { token } = await res.json();

‎samples/03.a.host-with-react/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,9 @@
2929
<script type="text/babel">
3030
(async function () {
3131
// In this demo, we are using Direct Line token from MockBot.
32-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
33-
// You should never put the Direct Line secret in the browser or client app.
34-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
32+
// Your client code must provide either a secret or a token to talk to your bot.
33+
// Tokens are more secure. To learn about the differences between secrets and tokens
34+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
3535

3636
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3737
const { token } = await res.json();

‎samples/04.a.display-user-bot-initials-styling/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
<script>
2424
(async function () {
2525
// In this demo, we are using Direct Line token from MockBot.
26-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
27-
// You should never put the Direct Line secret in the browser or client app.
28-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
26+
// Your client code must provide either a secret or a token to talk to your bot.
27+
// Tokens are more secure. To learn about the differences between secrets and tokens
28+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
2929

3030
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3131
const { token } = await res.json();

‎samples/04.b.display-user-bot-images-styling/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
<script>
2424
(async function () {
2525
// In this demo, we are using Direct Line token from MockBot.
26-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
27-
// You should never put the Direct Line secret in the browser or client app.
28-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
26+
// Your client code must provide either a secret or a token to talk to your bot.
27+
// Tokens are more secure. To learn about the differences between secrets and tokens
28+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
2929

3030
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3131
const { token } = await res.json();

‎samples/05.a.branding-webchat-styling/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
<script>
2424
(async function () {
2525
// In this demo, we are using Direct Line token from MockBot.
26-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
27-
// You should never put the Direct Line secret in the browser or client app.
28-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
26+
// Your client code must provide either a secret or a token to talk to your bot.
27+
// Tokens are more secure. To learn about the differences between secrets and tokens
28+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
2929

3030
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3131
const { token } = await res.json();

‎samples/05.b.idiosyncratic-manual-styling/index.html‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,9 +23,9 @@
2323
<script>
2424
(async function () {
2525
// In this demo, we are using Direct Line token from MockBot.
26-
// To talk to your bot, you should use the token exchanged using your Direct Line secret.
27-
// You should never put the Direct Line secret in the browser or client app.
28-
// https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication
26+
// Your client code must provide either a secret or a token to talk to your bot.
27+
// Tokens are more secure. To learn about the differences between secrets and tokens
28+
// and to understand the risks associated with using secrets, visit https://docs.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-direct-line-3-0-authentication?view=azure-bot-service-4.0
2929

3030
const res = await fetch('https://webchat-mockbot.azurewebsites.net/directline/token', { method: 'POST' });
3131
const { token } = await res.json();

0 commit comments

Comments
 (0)