edits

Author: diberry

articles/cognitive-services/QnAMaker/Concepts/role-based-access-control.md

@@ -14,7 +14,7 @@ Collaborate with other authors and editors using role-based access control (RBAC
 All permissions are controlled by the permissions placed on the QnA Maker resource. These permissions align to read, write, publish, and full access.
 
 This RBAC feature includes:
-* AAD is 100% backward compatible with key-based authentication for owners and contributors. Customers can use either key or RBAC-based authentication in their requests.
+* Azure Active Directory (AAD) is 100% backward compatible with key-based authentication for owners and contributors. Customers can use either key-based authentication or RBAC-based authentication in their requests.
 * Quickly add authors and editors to all knowledge bases in the resource because control is at the resource level, not at the knowledge base level.
 
 ## Access is provided by a defined role
@@ -26,17 +26,23 @@ This RBAC feature includes:
 The following diagram shows the flow, from the author's perspective, for signing into the QnA Maker portal and using the authoring APIs.
 
 > [!div class="mx-imgBorder"]
-> ![The following diagram shows the flow, from the author's perspective, for signing into the QnA Maker portal and using the authoring APIs.](../media/qnamaker-how-to-collborate-knowledge-base/rbac-flow-from-portal-to-service.png)
+> ![The following diagram shows the flow, from the author's perspective, for signing into the QnA Maker portal and using the authoring APIs.](../media/qnamaker-how-to-collaborate-knowledge-base/rbac-flow-from-portal-to-service.png)
 
 |Steps|Description|
 |--|--|
-|1|Portal Acquires token for cognitive services resource.|
-|2|Portal Calls the appropriate API passing the tokens instead of keys.|
-|3|APIM validated the tokens.|
-|4 |APIM calls QnAMaker Service like any regular service.|
+|1|Portal Acquires token for QnA Maker resource.|
+|2|Portal Calls the appropriate QnA Maker authoring API (APIM) passing the token instead of keys.|
+|3|QnA Maker API validates the token.|
+|4 |QnA Maker API calls QnAMaker Service.|
 
 Learn more about how to [set up authentication if you intend to call the authoring APIs](../How-To/collaborate-knowledge-base.md).
 
+## Authenticate by QnA Maker portal or API
+
+If you author and collaborate using the QnA Maker portal, after you [add the appropriate role to the resource for a collaborator](../How-To/collaborate-knowledge-base.md), the QnA Maker portal manages all the access permissions.
+
+If you author and collaborate using the APIs, either through REST or the SDKs, you need to [create a service principal](../../authentication.md#assign-a-role-to-a-service-principal) to manage the authentication.
+
 ## Next step
 
 * Design a knowledge base for [languages](design-language-culture.md) and for [client applications](integration-with-other-applications.md)

articles/cognitive-services/QnAMaker/How-To/collaborate-knowledge-base.md

@@ -7,21 +7,17 @@ ms.date: 03/17/2020
 
 # Collaboration with authors and editors
 
-Collaboration is provided at the QnA Maker resource level in two different ways:
-
-* **Authentication key** for owner and contributor roles. This is the original method of providing access. at subscription level 
-
-* Authentication via **bearer tokens** for other roles. This is a newer method of providing access.
+Collaboration is provided at the QnA Maker resource level to allow you to restrict collaborator access based on the collaborator's role. Learn more about QnA Maker collaborator authentication [concepts](../Concepts/role-based-access-control.md).
 
 # Add role-based access (RBAC) to your QnA Maker resource
 
-QnA Maker allows multiple people to collaborate on all knowledge bases in the same QnA Maker resource. This feature is provided with the Azure [Role-Based Access Control](https://docs.microsoft.com/azure/active-directory/role-based-access-control-configure).
+QnA Maker allows multiple people to collaborate on all knowledge bases in the same QnA Maker resource. This feature is provided with the Azure [Role-Based Access Control](../../../active-directory/role-based-access-control-configure.md).
 
 ## Access at the QnA Maker resource level
 
-You cannot share a particular knowledge base in a QnA Maker service. If you want more granular access control, consider distributing your knowledge bases across different QnA Maker services.
+You cannot share a particular knowledge base in a QnA Maker service. If you want more granular access control, consider distributing your knowledge bases across different QnA Maker resources, then add roles to each resource.
 
-## Use authentication key for owner and contributor
+## Add role to resource
 
 ### Add a user account to the QnA Maker resource
 
@@ -57,11 +53,11 @@ The following steps use the collaborator role but any of the [roles](../referenc
 
 When the person you shared your QnA Maker service with logs into the [QnA Maker portal](https://qnamaker.ai), they can see all the knowledge bases in that service based on their role.
 
-## Use bearer token for other roles
-
-Bearer
-
 ## Next steps
 
 > [!div class="nextstepaction"]
 > [Test a knowledge base](./test-knowledge-base.md)
+
+Learn more about collaboration:
+* [Azure](../../../active-directory/role-based-access-control-configure.md) role-based access control
+* QnA Maker role-based access control [concepts](../Concepts/role-based-access-control.md)

articles/cognitive-services/QnAMaker/includes/role-based-access-control.md

@@ -6,18 +6,12 @@ ms.custom: include file
 ms.date: 03/11/2020
 ---
 
-The following roles are managed with the QnA Maker authentication key:
+The following roles are provided for collaboration:
 
-|Role|Type|Functionalities|API permissions|
+|Role|Functionalities|API Access|API permissions|
 |--|--|--|--|
-|Owner|Authentication Key|All||
-|Contributor|Authentication Key|All except ability to add new members to roles||
-
-
-The following roles are managed with role-based access control:
-
-|Role|Type|Functionalities|API permissions|
-|--|--|--|--|
-|QnA Maker Read<br>(read)|Active Directory|Export/Download<br>Test|1. Download KB API<br>2. List KBs for user API<br>3. Get Knowledge base details<br>4. Download Alterations<br>Generate Answer |
-|QnA Maker Editor<br>(read/write)|Active Directory|Export/Download<br>Test<br>Update KB<br>Export KB<br>Import KB<br>Replace KB<br>Create KB|1. Create KB API<br>2. Update KB API<br>3. Replace KB API<br>4. Replace Alterations<br>5. "Train API" [in new service model v5]|
-|Cognitive Service User<br>(read/write/publish)|Active Directory||All|
+|Owner|All|Authentication Key|All|
+|Contributor|All except ability to add new members to roles|Authentication Key|All except ability to add new members to roles|
+|QnA Maker Read<br>(read)|Export/Download<br>Test|Bearer token|1. Download KB API<br>2. List KBs for user API<br>3. Get Knowledge base details<br>4. Download Alterations<br>Generate Answer |
+|QnA Maker Editor<br>(read/write)|Export/Download<br>Test<br>Update KB<br>Export KB<br>Import KB<br>Replace KB<br>Create KB|Bearer token|1. Create KB API<br>2. Update KB API<br>3. Replace KB API<br>4. Replace Alterations<br>5. "Train API" [in new service model v5]|
+|Cognitive Service User<br>(read/write/publish)|All|Bearer token|All|