documenting entra id option

Author: Blackmist

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

@@ -123,7 +123,7 @@ The following table is an example of how to set up role-based access control for
 | --- | --- | ---|
 | IT admin | Owner of the hub | The IT admin can ensure the hub is set up to their enterprise standards. They can assign managers the Contributor role on the resource if they want to enable managers to make new hubs. Or they can assign managers the Azure AI Developer role on the resource to not allow for new hub creation. |
 | Managers | Contributor or Azure AI Developer on the hub | Managers can manage the hub, audit compute resources, audit connections, and create shared connections. |
-| Team lead/Lead developer | Azure AI Developer on the hub | Lead developers can create projects for their team and create shared resources (ex: compute and connections) at the hub level. After project creation, project owners can invite other members. |
+| Team lead/Lead developer | Azure AI Developer on the hub | Lead developers can create projects for their team and create shared resources (such as compute and connections) at the hub level. After project creation, project owners can invite other members. |
 | Team members/developers | Contributor or Azure AI Developer on the project | Developers can build and deploy AI models within a project and create assets that enable development such as computes and connections. |
 
 ## Access to resources created outside of the hub
@@ -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 | 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/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 AI 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 EntraID 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,10 @@ 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).
 
     :::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

@@ -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 a variety of authentication methods for the different connection types. When using 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

@@ -3,7 +3,7 @@ title: 'CLI (v2) AI Search connection YAML schema'
 titleSuffix: Azure Machine Learning
 description: Reference documentation for the CLI (v2) AI Search connections YAML schema.
 services: machine-learning
-ms.service: machine-learning
+ms.service: azure-machine-learning
 ms.subservice: core
 ms.custom:
   - build-2024
@@ -32,15 +32,15 @@ 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, a Microsoft Entra ID (credential-less authentication) connection is created. | | |
 
 ## Remarks
 
 While the `az ml connection` commands can be used to manage both Azure Machine Learning and Azure AI Studio connections, the Azure AI Search connection is specific to Azure AI Studio.
 
 ## Examples
 
-Visit [this GitHub resource]() for examples. Several are shown here. These examples would be in the form of YAML files and used from the CLI. For example, `az ml connection create -f <file-name>.yaml`. 
+These examples would be in the form of YAML files and used from the CLI. For example, `az ml connection create -f <file-name>.yaml`. 
 
 ### YAML: API key
 
@@ -54,7 +54,7 @@ endpoint: https://contoso.search.windows.net/
 api_key: XXXXXXXXXXXXXXX
 ```
 
-### YAML: credential-less
+### YAML: Microsoft Entra ID
 
 ```yml
 #AzureContentSafetyConnection.yml

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

@@ -3,15 +3,15 @@ title: 'CLI (v2) AI Services connection YAML schema'
 titleSuffix: Azure Machine Learning
 description: Reference documentation for the CLI (v2) Azure AI Services connections YAML schema.
 services: machine-learning
-ms.service: machine-learning
+ms.service: azure-machine-learning
 ms.subservice: core
 ms.custom:
   - build-2024
 ms.topic: reference
 
 author: Blackmist
 ms.author: larryfr
-ms.date: 05/09/2024
+ms.date: 08/21/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, a Microsoft Entra ID (credential-less authentication) connection is created. | | |
 | `ai_services_resource_id` | string | **Required.** The fully qualified Azure resource ID of the Azure AI Services resource. | | |
 
 
@@ -49,7 +49,7 @@ While the `az ml connection` commands can be used to manage both Azure Machine L
 
 ## Examples
 
-Visit [this GitHub resource]() for examples. Several are shown here. These examples would be in the form of YAML files and used from the CLI. For example, `az ml connection create -f <file-name>.yaml`. 
+These examples would be in the form of YAML files and used from the CLI. For example, `az ml connection create -f <file-name>.yaml`. 
 
 ### YAML: API key
 
@@ -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

@@ -3,7 +3,7 @@ title: 'CLI (v2) OpenAI connection YAML schema'
 titleSuffix: Azure Machine Learning
 description: Reference documentation for the CLI (v2) OpenAI connections YAML schema.
 services: machine-learning
-ms.service: machine-learning
+ms.service: azure-machine-learning
 ms.subservice: core
 ms.custom:
   - build-2024
@@ -41,7 +41,7 @@ While the `az ml connection` commands can be used to manage both Azure Machine L
 
 ## Examples
 
-Visit [this GitHub resource]() for examples. Several are shown here. These examples would be in the form of YAML files and used from the CLI. For example, `az ml connection create -f <file-name>.yaml`. 
+These examples would be in the form of YAML files and used from the CLI. For example, `az ml connection create -f <file-name>.yaml`. 
 
 ### YAML: API key