Merge pull request #18 from Blackmist/300714-entra-id

documenting entra id option

Author: AnnaMHuff

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

@@ -214,6 +214,31 @@ If your AI Studio hub is configured with a **user-assigned managed identity**, t
 
 Within the key vault, the user or service principal must have the create, get, delete, and purge access to the key through a key vault access policy. For more information, see [Azure Key Vault security](/azure/key-vault/general/security-features#controlling-access-to-key-vault-data).
 
+## Scenario: Connections using Microsoft Entra ID authentication
+
+When you create a connection that uses Microsoft Entra ID authentication, you must assign roles to your developers so they can access the resource.
+
+| Resource connection | Role | Description |
+|----------|------|-------------|
+| Azure AI Search | Contributor | List API-Keys to list indexes from Azure OpenAI 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. |
+
+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 |
+| 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]
+> The __Cognitive Services OpenAI User__ role is only required if you are using two Azure OpenAI resources: one for your chat model and one for your embedding model. If this applies, enable Trusted Services AND ensure the connection for your embedding model Azure OpenAI resource has Microsoft Entra ID enabled.  
+
 ## Scenario: Use an existing Azure OpenAI resource
 
 When you create a connection to an existing Azure OpenAI resource, you must also assign roles to your users so they can access the resource. You should assign either the **Cognitive Services OpenAI User** or **Cognitive Services OpenAI Contributor** role, depending on the tasks they need to perform. For information on these roles and the tasks they enable, see [Azure OpenAI roles](/azure/ai-services/openai/how-to/role-based-access-control#azure-openai-roles).

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

@@ -52,7 +52,12 @@ Follow these steps to create a new connection that's only available for the curr
 
     :::image type="content" source="../media/data-connections/connection-add-browse-azure-ai-search.png" alt-text="Screenshot of the page to select Azure AI Search from a list of other resources." lightbox="../media/data-connections/connection-add-browse-azure-ai-search.png":::
 
-1. Browse for and select your Azure AI Search service from the list of available services. Select **Add connection**.
+1. Browse for and select your Azure AI Search service from the list of available services and then select the type of __Authentication__ to use for the resource. Select **Add connection**.
+
+    > [!TIP]
+    > Different connection types support different authentication methods. Using Microsoft Entra ID may require specific Azure role-based access permissions for your developers. For more information, visit [Role-based access control](../concepts/rbac-ai-studio.md#scenario-connections-using-microsoft-entra-id-authentication).
+    >
+    > Microsoft Entra ID support with the Azure AI Search connection is currently in preview.
 
     :::image type="content" source="../media/data-connections/connection-add-azure-ai-search-connect.png" alt-text="Screenshot of the page to select the Azure AI Search service that you want to connect to." lightbox="../media/data-connections/connection-add-azure-ai-search-connect.png":::
 

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

@@ -7,7 +7,7 @@ ms.service: azure-ai-studio
 ms.custom:
   - build-2024
 ms.topic: how-to
-ms.date: 5/21/2024
+ms.date: 08/29/2024
 ms.reviewer: dantaylo
 ms.author: larryfr
 author: Blackmist
@@ -31,6 +31,10 @@ Connections are a way to authenticate and consume both Microsoft and other resou
 
 [!INCLUDE [SDK setup](../../includes/development-environment-config.md)]
 
+## Authenticating with Microsoft Entra ID
+
+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).
+
 ## Azure OpenAI Service
 
 The following example creates an Azure OpenAI Service connection.
@@ -44,14 +48,20 @@ from azure.ai.ml.entities import UsernamePasswordConfiguration
 
 name = "XXXXXXXXX"
 
-target = "https://XXXXXXXXX.cognitiveservices.azure"
-api_key= "my-key"
+target = "https://XXXXXXXXX.cognitiveservices.azure.com/"
+
 resource_id= "Azure-resource-id"
 
+# Microsoft Entra ID
+credentials = None
+# Uncomment the following to use API key instead
+# api_key= "my-key"
+# credentials = ApiKeyConfiguration(key=api_key)
+
 wps_connection = AzureOpenAIConnection(
     name=name,
     azure_endpoint=target,
-    credentials=ApiKeyConfiguration(key=api_key),
+    credentials=credentials,
     resource_id = resource_id,
     is_shared=False
 )
@@ -70,12 +80,17 @@ name = "my-ai-services"
 
 target = "https://XXXXXXXXX.cognitiveservices.azure.com/"
 resource_id=""
-api_key="XXXXXXXXX"
+
+# Microsoft Entra ID
+credentials = None
+# Uncomment the following to use API key instead
+# api_key= "my-key"
+# credentials = ApiKeyConfiguration(key=api_key)
 
 wps_connection = AzureAIServicesConnection(
     name=name,
     endpoint=target,
-    credentials=ApiKeyConfiguration(key=api_key),
+    credentials=credentials,
     ai_services_resource_id=resource_id,
 )
 ml_client.connections.create_or_update(wps_connection)
@@ -90,13 +105,18 @@ from azure.ai.ml.entities import AzureAISearchConnection, ApiKeyConfiguration
 from azure.ai.ml.entities import UsernamePasswordConfiguration
 
 name = "my_aisearch_demo_connection"
-
 target = "https://XXXXXXXXX.search.windows.net"
-api_key="XXXXXXXXX"
+
+# Microsoft Entra ID
+credentials = None
+# Uncomment the following to use API key instead
+# api_key= "my-key"
+# credentials = ApiKeyConfiguration(key=api_key)
+
 wps_connection = AzureAISearchConnection(
     name=name,
     endpoint=target,
-    credentials=ApiKeyConfiguration(key=api_key),
+    credentials=credentials,
 )
 ml_client.connections.create_or_update(wps_connection)
 ```
@@ -132,7 +152,7 @@ from azure.ai.ml.entities import ServerlessConnection
 
 name = "my_maas_apk"
 
-endpoint = "https://XXXXXXXXX.eastus2.inference.ai.azure.com"
+endpoint = "https://XXXXXXXXX.eastus2.inference.ai.azure.com/"
 api_key = "XXXXXXXXX"
 wps_connection = ServerlessConnection(
     name=name,

articles/ai-studio/media/data-connections/connection-add-azure-ai-search-connect.png

@@ -11,7 +11,7 @@ ms.topic: reference
 
 author: Blackmist
 ms.author: larryfr
-ms.date: 05/09/2024
+ms.date: 08/29/2024
 ms.reviewer: ambadal
 ---
 
@@ -32,7 +32,7 @@ ms.reviewer: ambadal
 | `type` | string | **Required.** The connection type. | `azure_ai_search` | `azure_ai_search` |
 | `is_shared` | boolean | `true` if the connection is shared across other projects in the hub; otherwise, `false`. | | `true` |
 | `endpoint` | string | **Required.** The URL of the endpoint. | | |
-| `api_key` | string | **Required.** The API key used to authenticate the connection. If not provided, a Microsoft Entra ID (credential-less authentication) connection is created. | | |
+| `api_key` | string | The API key used to authenticate the connection. If not provided, the connection is authenticated via Microsoft Entra ID (credential-less authentication). | | |
 
 ## Remarks
 
@@ -54,7 +54,7 @@ endpoint: https://contoso.search.windows.net/
 api_key: XXXXXXXXXXXXXXX
 ```
 
-### YAML: credential-less
+### YAML: Microsoft Entra ID (preview)
 
 ```yml
 #AzureContentSafetyConnection.yml

articles/ai-studio/media/data-connections/connections-all-refreshed.png

@@ -11,7 +11,7 @@ ms.topic: reference
 
 author: Blackmist
 ms.author: larryfr
-ms.date: 08/21/2024
+ms.date: 08/29/2024
 ms.reviewer: ambadal
 ---
 
@@ -32,7 +32,7 @@ ms.reviewer: ambadal
 | `type` | string | **Required.** The connection type. | `azure_ai_services` | `azure_ai_services` |
 | `is_shared` | boolean | `true` if the connection is shared across other projects in the hub; otherwise, `false`. | | `true` |
 | `endpoint` | string | **Required.** The URL of the endpoint. | | |
-| `api_key` | string | **Required.** The API key used to authenticate the connection. If not provided, a Microsoft Entra ID (credential-less authentication) connection is created. | | |
+| `api_key` | string | The API key used to authenticate the connection. If not provided, the connection is authenticated via Microsoft Entra ID (credential-less authentication). | | |
 | `ai_services_resource_id` | string | **Required.** The fully qualified Azure resource ID of the Azure AI Services resource. | | |
 
 
@@ -63,7 +63,7 @@ api_key: XXXXXXXXXXXXXXX
 ```
 
 
-### YAML: credential-less
+### YAML: Microsoft Entra ID
 
 ```yml
 #AzureAIServiceConnection.yml

articles/machine-learning/reference-yaml-connection-ai-search.md

@@ -11,7 +11,7 @@ ms.topic: reference
 
 author: Blackmist
 ms.author: larryfr
-ms.date: 05/09/2024
+ms.date: 08/29/2024
 ms.reviewer: ambadal
 ---
 
@@ -32,7 +32,7 @@ ms.reviewer: ambadal
 | `type` | string | **Required.** The connection type. | `azure_open_ai` | `azure_open_ai` |
 | `is_shared` | boolean | `true` if the connection is shared across other projects in the hub; otherwise, `false`. | | `true` |
 | `endpoint` | string | **Required.** The URL of the endpoint. | | |
-| `api_key` | string | **Required.** The API key used to authenticate the connection. If not provided, a Microsoft Entra ID (credential-less authentication) connection is created. | | |
+| `api_key` | string | The API key used to authenticate the connection. If not provided, the connection is authenticated via Microsoft Entra ID (credential-less authentication). | | |
 | `open_ai_resource_id` | string | **Required.** The fully qualified Azure resource ID of the Azure OpenAI resource. | | |
 
 
@@ -58,7 +58,7 @@ api_key: XXXXXXXXXXXXXXX
 ```
 
 
-### YAML: credential-less
+### YAML: Microsoft Entra ID
 
 ```yml
 #AzureOpenAIConnection.yml