connections security and terminology

Author: eric-urban

articles/ai-studio/concepts/rbac-ai-studio.md

@@ -8,7 +8,7 @@ ms.custom:
   - ignite-2023
   - build-2024
 ms.topic: conceptual
-ms.date: 5/21/2024
+ms.date: 9/12/2024
 ms.reviewer: deeikele
 ms.author: larryfr
 author: Blackmist
@@ -220,20 +220,20 @@ When you create a connection that uses Microsoft Entra ID authentication, you mu
 
 | Resource connection | Role | Description |
 |----------|------|-------------|
-| Azure AI Search | Contributor | List API-Keys to list indexes from Azure OpenAI Studio. |
+| Azure AI Search | Contributor | List API-Keys to list indexes from Azure AI Studio. |
 | Azure AI Search | Search Index Data Contributor | Required for indexing scenarios |
-| Azure AI services/Azure OpenAI | Cognitive Services OpenAI Contributor | Call public ingestion API from Azure OpenAI Studio. |
-| Azure AI services/OpenAI | Cognitive Services User | List API-Keys from Azure OpenAI Studio. |
-| Azure AI services/OpenAI | Contributor | Allows for calls to the control plane. |
+| Azure AI services / Azure OpenAI | Cognitive Services OpenAI Contributor | Call public ingestion API from Azure AI Studio. |
+| Azure AI services / Azure OpenAI | Cognitive Services User | List API-Keys from Azure AI Studio. |
+| Azure AI services / Azure OpenAI | Contributor | Allows for calls to the control plane. |
 
 When using Microsoft Entra ID authenticated connections in the chat playground, the services need to authorize each other to access the required resources. The admin performing the configuration needs to have the __Owner__ role on these resources to add role assignments. The following table lists the required role assignments for each resource. The __Assignee__ column refers to the system-assigned managed identity of the listed resource. The __Resource__ column refers to the resource that the assignee needs to access. For example, Azure OpenAI has a system-assigned managed identity that needs to be assigned the __Search Index Data Reader__ role for the Azure AI Search resource.
 
 | Role | Assignee | Resource | Description |
 |------|----------|----------|-------------|
-| Search Index Data Reader | Azure AI services/OpenAI | Azure AI Search | Inference service queries the data from the index. Only used for inference scenarios. |
-| Search Index Data Contributor | Azure AI services/OpenAI | Azure AI Search | Read-write access to content in indexes. Import, refresh, or query the documents collection of an index. Only used for ingestion and inference scenarios. |
-| Search Service Contributor | Azure AI services/OpenAI | Azure AI Search | Read-write access to object definitions (indexes, aliases, synonym maps, indexers, data sources, and skillsets). Inference service queries the index schema for auto fields mapping. Data ingestion service creates index, data sources, skill set, indexer, and queries the indexer status. |
-| Cognitive Services OpenAI Contributor | Azure AI Search | Azure AI services/OpenAI | Custom skill |
+| Search Index Data Reader | Azure AI services / Azure OpenAI | Azure AI Search | Inference service queries the data from the index. Only used for inference scenarios. |
+| Search Index Data Contributor | Azure AI services / Azure OpenAI | Azure AI Search | Read-write access to content in indexes. Import, refresh, or query the documents collection of an index. Only used for ingestion and inference scenarios. |
+| Search Service Contributor | Azure AI services / Azure OpenAI | Azure AI Search | Read-write access to object definitions (indexes, aliases, synonym maps, indexers, data sources, and skillsets). Inference service queries the index schema for auto fields mapping. Data ingestion service creates index, data sources, skill set, indexer, and queries the indexer status. |
+| Cognitive Services OpenAI Contributor | Azure AI Search | Azure AI services / Azure OpenAI | Custom skill |
 | Cognitive Services OpenAI User | Azure OpenAI Resource for chat model | Azure OpenAI resource for embedding model | Required only if using two Azure OpenAI resources to communicate. |
 
 > [!NOTE]
@@ -316,8 +316,8 @@ The following example defines a role for a developer using [Azure OpenAI Assista
 {
     "id": "",
     "properties": {
-        "roleName": "CognitiveServices OpenAI Assistants API Developer",
-        "description": "Custom role to work with AOAI Assistants API",
+        "roleName": "Azure OpenAI Assistants API Developer",
+        "description": "Custom role to work with Azure OpenAI Assistants API",
         "assignableScopes": [
             "<your-scope>"
         ],

articles/ai-studio/how-to/develop/connections-add-sdk.md

@@ -2,12 +2,12 @@
 title: How to add a new connection in AI Studio using the Azure Machine Learning SDK
 titleSuffix: Azure AI Studio
 description: This article provides instructions on how to add connections to other resources using the Azure Machine Learning SDK.
-manager: nitinme
+manager: scottpolly
 ms.service: azure-ai-studio
 ms.custom:
   - build-2024
 ms.topic: how-to
-ms.date: 08/29/2024
+ms.date: 9/12/2024
 ms.reviewer: dantaylo
 ms.author: larryfr
 author: Blackmist
@@ -35,6 +35,12 @@ Connections are a way to authenticate and consume both Microsoft and other resou
 
 There are various authentication methods for the different connection types. When you use Microsoft Entra ID, in addition to creating the connection you might also need to grant Azure role-based access control permissions before the connection can be used. For more information, visit [Role-based access control](../../concepts/rbac-ai-studio.md#scenario-connections-using-microsoft-entra-id-authentication).
 
+> [!IMPORTANT]
+> We recommend Microsoft Entra ID authentication with [managed identities for Azure resources](/azure/active-directory/managed-identities-azure-resources/overview) to avoid storing credentials with your applications that run in the cloud.
+>
+> If you use an API key, store it securely somewhere else, such as in [Azure Key Vault](/azure/key-vault/general/overview). Don't include the API key directly in your code, and never post it publicly.
+
+
 ## Azure OpenAI Service
 
 The following example creates an Azure OpenAI Service connection.
@@ -54,7 +60,7 @@ resource_id= "Azure-resource-id"
 
 # Microsoft Entra ID
 credentials = None
-# Uncomment the following to use API key instead
+# Uncomment the following if you need to use API key instead
 # api_key= "my-key"
 # credentials = ApiKeyConfiguration(key=api_key)
 
@@ -83,7 +89,7 @@ resource_id=""
 
 # Microsoft Entra ID
 credentials = None
-# Uncomment the following to use API key instead
+# Uncomment the following if you need to use API key instead
 # api_key= "my-key"
 # credentials = ApiKeyConfiguration(key=api_key)
 
@@ -109,7 +115,7 @@ target = "https://XXXXXXXXX.search.windows.net"
 
 # Microsoft Entra ID
 credentials = None
-# Uncomment the following to use API key instead
+# Uncomment the following if you need to use API key instead
 # api_key= "my-key"
 # credentials = ApiKeyConfiguration(key=api_key)