MicrosoftDocs · openpublishbuild · Nov 24, 2020 · Nov 24, 2020 · Nov 25, 2020 · Nov 25, 2020
diff --git a/articles/TOC.yml b/articles/TOC.yml
@@ -44,6 +44,8 @@
     href: v4sdk/bot-builder-concept-identity-providers.md
   - name: Single sign on
     href: v4sdk/bot-builder-concept-sso.md
+  - name: Enhanced authentication
+    href: v4sdk/bot-builder-security-enhanced.md
   - name: Security guidelines
     href: v4sdk/bot-builder-security-guidelines.md
   - name: Bot Authentication

diff --git a/articles/bot-service-channel-connect-directline.md b/articles/bot-service-channel-connect-directline.md
@@ -7,7 +7,7 @@ ms.author: v-mimiel
 manager: kamrani
 ms.topic: article
 ms.service: bot-service
-ms.date: 10/21/2020
+ms.date: 12/04/2020
 ---
 
 # Connect a bot to Direct Line
@@ -67,10 +67,19 @@ When you add the Direct Channel, the Bot Framework generates secret keys. Your c
 
 1. When finished, click **Done** to save the site configuration. You can repeat this process, beginning with [Add new site](#add-new-site), for each client application that you want to connect to your bot.
 
-When you have the **enhanced authentication enabled**, you will see the following behavior for which trusted origins are used:
+### Configure enhanced authentication
 
-- If you configure trusted origins as part of the configuration UI page, then these will **always** be used as the only set. Sending no or additional trusted origins when generating a token or starting a conversation will be ignored (i.e. they are **not appended** to the list or cross validated).
-- If you have not configured trusted origins as part of the configuration UI, then any value you send as part of the API calls will be used.
+When you enable **enhanced authentication**, you are asked to select a list of **trusted origin URLs**, also known as trusted origins or trusted domains, for the generation of the authentication token. If you enable the enhanced authentication, you must specify at least one trusted origin.
+
+![Add trusted origins](media/bot-service-channel-connect-directline/add-trusted-origin-urls.png "Copy Direct Line key")
+
+A trusted domain is a domain that the system trusts to authenticate users. In our case, is a domain that Direct Line can trust for the generation of a token.
+
+- If you configure trusted origins as part of the configuration UI page, then these will **always** be used as the only set for the generation of a token. Sending none or additional trusted origins when generating a token or starting a conversation, they will be ignored (i.e. they are **not appended** to the list or cross validated).
+
+- If you did not enable enhanced authentication, any origin URL you send as part of the API calls will be used.
+
+Enhanced authentication allows you to mitigate security risks when connecting to a bot (using the Web Chat control, for example). For more information, see [Direct Line enhanced authentication](v4sdk/bot-builder-security-enhanced.md).
 
 ## Example
 

diff --git a/articles/bot-service-channel-connect-webchat.md b/articles/bot-service-channel-connect-webchat.md
@@ -16,7 +16,7 @@ ms.date: 08/22/2019
 
 When you [create a bot](bot-service-quickstart.md) with the Framework Bot Service, the Web Chat channel is automatically configured for you. The Web Chat channel includes the [Web Chat control](https://github.com/microsoft/BotFramework-WebChat), which provides the ability for users to interact with the bot directly in a web page.
 
-![Web chat sample](~/media/bot-service-channel-webchat/create-a-bot.png)
+![Web chat sample](./media/bot-service-channel-webchat/create-a-bot.png)
 
 The Web Chat channel in the Bot Framework Portal contains everything you need to embed the Web Chat control in a web page. All you have to do to use the web chat control is get your bot's secret key and embed the control in a web page.
 
@@ -28,22 +28,22 @@ When you use Azure Bot Service authentication with Web Chat there are some impor
 
 The following picture shows the components involved when embedding the Web Chat control in a web page.
 
-  ![bot embed components](~/media/bot-service-channel-webchat/webchat-control.png)
+  ![bot embed components](./media/bot-service-channel-webchat/webchat-control.png)
 
-> [!NOTE]
-> This article assumes that you already have a bot deployed in Azure. For information about deployment, see [Deploy your bot](bot-builder-deploy-az-cli.md).
+> [!IMPORTANT]
+> As the previous picture implies, you need to use Direct Line (with enhanced authentication) to mitigate security risks when connecting to a bot using the Web Chat control. For more information, see [Direct Line enhanced authentication](v4sdk\bot-builder-security-enhanced.md).
 
 ### Get your bot secret key
 
 1. Open your bot in the [Azure Portal](https://portal.azure.com) and click **Channels** blade.
 
 2. Click **Edit** for the **Web Chat** channel.
 
-    ![Web chat channel](~/media/bot-service-channel-webchat/bot-service-channel-list.png)
+    ![Web chat channel](./media/bot-service-channel-webchat/bot-service-channel-list.png)
 
 3. Under **Secret keys**, click **Show** for the first key.
 
-    ![Secret key](~/media/bot-service-channel-webchat/secret-key.png)
+    ![Secret key](./media/bot-service-channel-webchat/secret-key.png)
 
 4. Copy the **Secret key** and the **Embed code**.
 

diff --git a/articles/bot-service-resources-bot-framework-faq.md b/articles/bot-service-resources-bot-framework-faq.md
@@ -75,6 +75,7 @@ In case you don't find the answer you're looking for, you can post your question
 - [Can I block all traffic to my bot except traffic from the Bot Framework Service?](bot-service-resources-faq-security.md#can-i-block-all-traffic-to-my-bot-except-traffic-from-the-bot-framework-service)
 - [Which RBAC role is required to create and deploy a bot?](bot-service-resources-faq-security.md#which-rbac-role-is-required-to-create-and-deploy-a-bot)
 - [What keeps my bot secure from clients impersonating the Bot Framework Service?](bot-service-resources-faq-security.md#what-keeps-my-bot-secure-from-clients-impersonating-the-bot-framework-service)
+- [What is the purpose of the magic code during authentication?](bot-service-resources-faq-security.md#what-is-the-purpose-of-the-magic-code-during-authentication)
 
 ## Azure
 

diff --git a/articles/bot-service-resources-faq-security.md b/articles/bot-service-resources-faq-security.md
@@ -19,7 +19,7 @@ ms.date: 06/09/2020
 
 ## Do the bots registered with the Bot Framework collect personal information? If yes, how can I be sure the data is safe and secure? What about privacy?
 
-Each bot is its own service, and developers of these services are required to provide Terms of Service and Privacy Statements per their Developer Code of Conduct. For more information, see [bot review guidelines](https://docs.microsoft.com/azure/bot-service/bot-service-review-guidelines?view=azure-bot-service-4.0).
+Each bot is its own service, and developers of these services are required to provide Terms of Service and Privacy Statements per their Developer Code of Conduct. For more information, see [bot review guidelines](bot-service-review-guidelines.md).
 
 ## Can I host my bot on my own servers?
 Yes. Your bot can be hosted anywhere on the Internet. On your own servers, in Azure, or in any other datacenter. The only requirement is that the bot must expose a publicly-accessible HTTPS endpoint.
@@ -48,6 +48,7 @@ If you have an outbound firewall blocking traffic from your bot to the Internet,
 > You may use `<channel>.botframework.com` if you'd prefer not to allow-list a URL with an asterisk. `<channel>` is equal to every channel your bot uses such as `directline.botframework.com`, `webchat.botframework.com`, and `slack.botframework.com`. It is also worthwhile to watch traffic over your firewall while testing the bot to make sure nothing else is getting blocked.
 
 ## Can I block all traffic to my bot except traffic from the Bot Framework Service?
+
 Bot Framework Services are hosted in Azure datacenters world-wide and the list of Azure IPs is constantly changing. allow-listing certain IP addresses may work one day and break the next as the Azure IP Addresses change.
 
 ## Which RBAC role is required to create and deploy a bot?
@@ -69,9 +70,21 @@ LUIS and QnA Maker require Cognitive Services permissions. QnA Maker also requir
 
 ## What keeps my bot secure from clients impersonating the Bot Framework Service?
 
-1. All authentic Bot Framework requests are accompanied by a JWT token whoes cryptographic signature can be verified by following the [authentication](https://docs.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-connector-authentication?view=azure-bot-service-3.0#bot-to-connector) guide. The token is designed so attackers cannot impersonate trusted services.
-2. The security token accompanying every request to your bot has the ServiceUrl encoded within it, which means that even if an attacker gains access to the token, they cannot redirect the conversation to a new ServiceUrl. This is enforced by all implementations of the SDK and documented in our authentication [reference](https://docs.microsoft.com/azure/bot-service/rest-api/bot-framework-rest-connector-authentication?view=azure-bot-service-3.0#bot-to-connector) materials.
+1. All authentic Bot Framework requests are accompanied by a JWT token whoes cryptographic signature can be verified by following the [authentication](rest-api/bot-framework-rest-connector-authentication.md) guide. The token is designed so attackers cannot impersonate trusted services.
+2. The security token accompanying every request to your bot has the ServiceUrl encoded within it, which means that even if an attacker gains access to the token, they cannot redirect the conversation to a new ServiceUrl. This is enforced by all implementations of the SDK and documented in our authentication [reference](rest-api/bot-framework-rest-connector-authentication.md#bot-to-connector&preserve-view=true) materials.
 3. If the incoming token is missing or malformed, the Bot Framework SDK will not generate a token in response. This limits how much damage can be done if the bot is incorrectly configured.
 4. Inside the bot, you can manually check the ServiceUrl provided in the token. This makes the bot more fragile in the event of service topology changes so this is possible but not recommended.
 
 Note that these are outbound connections from the bot to the Internet. There is not a list of IP Addresses or DNS names that the Bot Framework Connector Service will use to talk to the bot. Inbound IP Address allow-listing is not supported.
+
+## What is the purpose of the magic code during authentication?
+
+In the Web Chat control, there are two mechanisms to assure that the proper user is signed in.
+
+1. **Magic code**. At the end of the sign-in process, the user is presented with a randomly generated 6-digit code (*magic code*). The user must type this code in the conversation to complete the sign-in process. This tends to result in a bad user's experience. Additionally, it is still susceptible to phishing attacks. A malicious user can trick another user to sign-in and obtain the magic code through phishing.
+
+    >[!WARNING]
+    > The use of the magic code is deprecated. Instead, you should use **Direct Line enhanced authentication**, described below.
+
+1. **Direct Line enhanced authentication**. Because of the issues with the *magic code* approach, Azure Bot Service removed its need. Azure Bot Service guarantees that the sign-in process can only be completed in the **same browser session** as the Web Chat itself.
+To enable this protection, you must start Web Chat with a **Direct Line token** that contains a list of **trusted origins**, also know as trusted domains, that can host the bot's Web Chat client. With enhanced authentication options, you can statically specify the list of trusted origins in the Direct Line configuration page. For more information, see [Direct Line enhanced authentication](v4sdk/bot-builder-security-enhanced.md).
diff --git a/articles/dotnet/bot-builder-dotnet-sdk-quickstart.md b/articles/dotnet/bot-builder-dotnet-sdk-quickstart.md
@@ -7,7 +7,7 @@ ms.author: kamrani
 manager: kamrani
 ms.topic: conceptual
 ms.service: bot-service
-ms.date: 10/29/2020
+ms.date: 12/02/2020
 ---
 
 
@@ -23,24 +23,24 @@ This article shows you how to build a bot by using the C# template, and then how
 
 ## Prerequisites
 
-[!INCLUDE [dotnet prerequisites](~/includes/quickstart/dotnet/quickstart-dotnet-prerequisites.md)]
+[!INCLUDE [dotnet prerequisites](../includes/quickstart/dotnet/quickstart-dotnet-prerequisites.md)]
 
 ## Create a bot
 
-[!INCLUDE [dotnet quickstart create bot](~/includes/quickstart/dotnet/quickstart-dotnet-create-bot.md)]
+[!INCLUDE [dotnet quickstart create bot](../includes/quickstart/dotnet/quickstart-dotnet-create-bot.md)]
 
 ## Start your bot
 
-[!INCLUDE [dotnet quickstart start bot](~/includes/quickstart/dotnet/quickstart-dotnet-start-bot.md)]
+[!INCLUDE [dotnet quickstart start bot](../includes/quickstart/dotnet/quickstart-dotnet-start-bot.md)]
 
 ## Start the Emulator and connect your bot
 
-[!INCLUDE [dotnet quickstart start Emulator](~/includes/quickstart/common/quickstart-start-emulator.md)]
+[!INCLUDE [dotnet quickstart start Emulator](../includes/quickstart/common/quickstart-start-emulator.md)]
 
 ## Additional resources
 
-- See the [.NET Core SDK Templates](https://github.com/microsoft/BotBuilder-Samples/tree/master/generators/dotnet-templates#net-core-sdk-templates) README for moreinformation about the .NET Core templates.
-- See how to [debug a bot](~/bot-service-debug-channel-ngrok.md) for how to debug using Visual Studio or Visual Studio Code and the Bot Framework Emulator.
+- See the [.NET Core SDK Templates](https://github.com/microsoft/BotBuilder-Samples/tree/main/generators/dotnet-templates#readme) README for more information about the .NET Core templates.
+- See how to [debug a bot](../bot-service-debug-channel-ngrok.md) for how to debug using Visual Studio or Visual Studio Code and the Bot Framework Emulator.
 - See [Tunneling (ngrok)](https://github.com/Microsoft/BotFramework-Emulator/wiki/Tunneling-(ngrok)) for information on how to install ngrok.
 
 ## Next steps

diff --git a/articles/includes/deploy/snippet-additional-resources.md b/articles/includes/deploy/snippet-additional-resources.md
@@ -3,11 +3,11 @@ When you deploy a bot, typically these resources are created in the Azure portal
 | Resources      | Description |
 |----------------|-------------|
 | Web App Bot | An Azure Bot Service bot that is deployed to an Azure App Service.|
-| [App Service](https://docs.microsoft.com/azure/app-service/)| Enables you to build and host web applications.|
-| [App Service plan](https://docs.microsoft.com/azure/app-service/azure-web-sites-web-hosting-plans-in-depth-overview)| Defines a set of compute resources for a web app to run.|
+| [App Service](/azure/app-service/)| Enables you to build and host web applications.|
+| [App Service plan](/azure/app-service/azure-web-sites-web-hosting-plans-in-depth-overview)| Defines a set of compute resources for a web app to run.|
 
-If you create your bot through the Azure portal, you are able to provision additional resources, like [Application Insights for telemetry](~/v4sdk/bot-builder-telemetry.md).
+If you create your bot through the Azure portal, you are able to provision additional resources, like [Application Insights for telemetry](../../v4sdk/bot-builder-telemetry.md).
 
-To see documentation on `az bot` commands, see the [reference](https://docs.microsoft.com/cli/azure/bot?view=azure-cli-latest) topic.
+To see documentation on `az bot` commands, see the [reference](/cli/azure/bot) topic.
 
-If you are unfamiliar with Azure resource group, see this [terminology](https://docs.microsoft.com/azure/azure-resource-manager/resource-group-overview#terminology) topic.
+If you are unfamiliar with Azure resource group, see this [terminology](/azure/azure-resource-manager/resource-group-overview#terminology) topic.