Skip to content

Commit a085945

Browse files
AnnaMHuffAnnaMHuff
authored
Merge pull request #277772 from HeidiSteen/heidst-june7
[azure search] security section cleanup
2 parents aeaf11c + ac0d2ec commit a085945

4 files changed

+80
-86
lines changed

‎articles/search/search-howto-managed-identities-cosmos-db.md

Lines changed: 58 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,83 +1,106 @@
11
---
2-
title: Set up an indexer connection to Azure Cosmos DB via a managed identity
2+
title: Set up an indexer connection to Azure Cosmos DB using a managed identity
33
titleSuffix: Azure AI Search
4-
description: Learn how to set up an indexer connection to an Azure Cosmos DB account via a managed identity.
4+
description: Learn how to set up an indexer connection to an Azure Cosmos DB account using a managed identity.
55
author: gmndrg
66
ms.author: gimondra
77

88
ms.service: cognitive-search
99
ms.topic: how-to
10-
ms.date: 02/22/2024
10+
ms.date: 06/10/2024
1111
ms.custom:
1212
- subject-rbac-steps
1313
- ignite-2023
1414
---
1515

16-
# Set up an indexer connection to Azure Cosmos DB via a managed identity
16+
# Connect to Azure Cosmos DB using a managed identity (Azure AI Search)
1717

1818
This article explains how to set up an indexer connection to an Azure Cosmos DB database using a managed identity instead of providing credentials in the connection string.'
1919

20-
You can use a system-assigned managed identity or a user-assigned managed identity (preview). Managed identities are Microsoft Entra logins and require Azure role assignments to access data in Azure Cosmos DB.
20+
You can use a system-assigned managed identity or a user-assigned managed identity. Managed identities are Microsoft Entra logins and require Azure role assignments to access data in Azure Cosmos DB.
2121

2222
## Prerequisites
2323

2424
* [Create a managed identity](search-howto-managed-identities-data-sources.md) for your search service.
2525

26-
* Assign the **Cosmos DB Account Reader** role to the search service managed identity. This role grants the ability to read Azure Cosmos DB account data. For more information about role assignments in Cosmos DB, see [Configure role-based access control to data](search-howto-managed-identities-data-sources.md#assign-a-role).
26+
* Azure Cosmos DB for NoSQL. You can optionally [enforce role-based access as the only authentication method](../cosmos-db/how-to-setup-rbac.md#disable-local-auth) for data connections by setting `disableLocalAuth` to `true` for your Cosmos DB account.
2727

28-
* Data Plane Role assignment: Follow [Data plane Role assignment](../cosmos-db/how-to-setup-rbac.md) to know more.
28+
## Limitations
29+
30+
Indexer support for Azure Cosmos DB for Gremlin and MongoDB Collections is currently in preview. At this time, a preview limitation requires Azure AI Search to connect using keys. You can still set up a managed identity and role assignment, but Azure AI Search will only use the role assignment to get keys for the connection. This limitation means that you can't configure a [role-based approach](../cosmos-db/how-to-setup-rbac.md#disable-local-auth) if your indexers are connecting to Gremlin or MongoDB.
31+
32+
## Create a role assignment in Azure Cosmos DB
33+
34+
### [**Azure portal**](#tab/portal)
35+
36+
1. Sign in to Azure portal and find your Cosmos DB for NoSQL account.
37+
38+
1. Select **Access control (IAM)**.
39+
40+
1. Select **Add** and then select **Role assignment**.
41+
42+
1. From the list of job function roles, select **Cosmos DB Account Reader**.
43+
44+
1. Select **Next**.
45+
46+
1. Select **Managed identity** and then select **Members**.
47+
48+
1. Filter by system-assigned managed identities or user-assigned managed identities. You should see the managed identity that you previously created for your search service. If you don't have one, see [Configure search to use a managed identity](search-howto-managed-identities-data-sources.md). If you already set one up but it's not available, give it a few minutes.
49+
50+
1. Select the identity and save the role assignment.
51+
52+
For more information, see [Configure role-based access control with Microsoft Entra ID for your Azure Cosmos DB account](../cosmos-db/how-to-setup-rbac.md).
53+
54+
### [**PowerShell**](#tab/powershell)
55+
56+
Set variables:
2957

30-
* Example for a read-only data plane role assignment:
3158
```azurepowershell
3259
$cosmosdb_acc_name = <cosmos db account name>
3360
$resource_group = <resource group name>
34-
$subsciption = <subscription id>
35-
$system_assigned_principal = <principal id for system assigned identity>
36-
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-000000000001"
61+
$subsciption = <subscription ID>
62+
$system_assigned_principal = <principal ID for the search service's system assigned identity>
63+
$readOnlyRoleDefinitionId = "00000000-0000-0000-0000-00000000000"
3764
$scope=$(az cosmosdb show --name $cosmosdbname --resource-group $resourcegroup --query id --output tsv)
3865
```
3966

40-
Role assignment for system-assigned identity:
67+
Define a role assignment for the system-assigned identity:
4168

4269
```azurepowershell
4370
az cosmosdb sql role assignment create --account-name $cosmosdbname --resource-group $resourcegroup --role-definition-id $readOnlyRoleDefinitionId --principal-id $sys_principal --scope $scope
4471
```
4572

46-
* For Cosmos DB for NoSQL, you can optionally [enforce role-based access as the only authentication method](../cosmos-db/how-to-setup-rbac.md#disable-local-auth)
47-
for data connections by setting `disableLocalAuth` to `true` for your Cosmos DB account.
73+
---
4874

49-
* *For Gremlin and MongoDB Collections*:
50-
Indexer support is currently in preview. At this time, a preview limitation exists that requires Azure AI Search to connect using keys. You can still set up a managed identity and role assignment, but Azure AI Search will only use the role assignment to get keys for the connection. This limitation means that you can't configure a [role-based approach](../cosmos-db/how-to-setup-rbac.md#disable-local-auth) if your indexers are connecting to Gremlin or MongoDB using Search with managed identities to connect to Azure Cosmos DB.
75+
## Specify a managed identity in a connection string
5176

52-
* You should be familiar with [indexer concepts](search-indexer-overview.md) and [configuration](search-howto-index-cosmosdb.md).
77+
Once you have a role assignment, you can set up a connection to Azure Cosmos DB for NoSQL that operates under that role.
5378

54-
## Create the data source
79+
Indexers use a data source object for connections to an external data source. This section explains how to specify a system-assigned managed identity or a user-assigned managed identity on a data source connection string. You can find more [connection string examples](search-howto-managed-identities-data-sources.md#connection-string-examples) in the managed identity article.
5580

56-
Create the data source and provide either a system-assigned managed identity or a user-assigned managed identity (preview) in the connection string.
81+
> [!TIP]
82+
> You can create a data source connection to CosmosDB in the Azure portal, specifying either a system or user-assigned managed identity, and then view the JSON definition to see how the connection string is formulated.
5783
5884
### System-assigned managed identity
5985

6086
The [REST API](/rest/api/searchservice/create-data-source), Azure portal, and the [.NET SDK](/dotnet/api/azure.search.documents.indexes.models.searchindexerdatasourceconnection) support using a system-assigned managed identity.
6187

62-
When you're connecting with a system-assigned managed identity, the only change to the data source definition is the format of the "credentials" property. You'll provide the database name and a ResourceId that has no account key or password. The ResourceId must include the subscription ID of Azure Cosmos DB, the resource group, and the Azure Cosmos DB account name.
88+
When you're connecting with a system-assigned managed identity, the only change to the data source definition is the format of the "credentials" property. Provide a database name and a ResourceId that has no account key or password. The ResourceId must include the subscription ID of Azure Cosmos DB, the resource group, and the Azure Cosmos DB account name.
6389

6490
* For SQL collections, the connection string doesn't require "ApiKind".
6591
* For SQL collections, add "IdentityAuthType=AccessToken" if role-based access is enforced as the only authentication method. It isn't applicable for MongoDB and Gremlin collections.
6692
* For MongoDB collections, add "ApiKind=MongoDb" to the connection string and use a preview REST API.
6793
* For Gremlin graphs, add "ApiKind=Gremlin" to the connection string and use a preview REST API.
6894

69-
Here's an example of how to create a data source to index data from a storage account using the [Create Data Source](/rest/api/searchservice/create-data-source) REST API and a managed identity connection string. The managed identity connection string format is the same for the REST API, .NET SDK, and the Azure portal.
95+
Here's an example of how to create a data source to index data from a Cosmos DB account using the [Create Data Source](/rest/api/searchservice/create-data-source) REST API and a managed identity connection string. The managed identity connection string format is the same for the REST API, .NET SDK, and the Azure portal.
7096

7197
```http
72-
POST https://[service name].search.windows.net/datasources?api-version=2020-06-30
73-
Content-Type: application/json
74-
api-key: [Search service admin key]
75-
98+
POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
7699
{
77-
"name": "[my-cosmosdb-ds]",
100+
"name": "my-cosmosdb-ds",
78101
"type": "cosmosdb",
79102
"credentials": {
80-
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=[SQL | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
103+
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
81104
},
82105
"container": { "name": "[my-cosmos-collection]", "query": null },
83106
"dataChangeDetectionPolicy": null
@@ -86,9 +109,9 @@ api-key: [Search service admin key]
86109
}
87110
```
88111

89-
### User-assigned managed identity (preview)
112+
### User-assigned managed identity
90113

91-
The 2021-04-30-preview REST API supports connections based on a user-assigned managed identity. When you're connecting with a user-assigned managed identity, there are two changes to the data source definition:
114+
When you're connecting with a user-assigned managed identity, there are two changes to the data source definition:
92115

93116
* First, the format of the "credentials" property is the database name and a ResourceId that has no account key or password. The ResourceId must include the subscription ID of Azure Cosmos DB, the resource group, and the Azure Cosmos DB account name.
94117

@@ -99,19 +122,16 @@ The 2021-04-30-preview REST API supports connections based on a user-assigned ma
99122

100123
* Second, you add an "identity" property that contains the collection of user-assigned managed identities. Only one user-assigned managed identity should be provided when creating the data source. Set it to type "userAssignedIdentities".
101124

102-
Here's an example of how to create an indexer data source object using the [preview Create or Update Data Source](/rest/api/searchservice/preview-api/create-or-update-data-source) REST API:
103-
125+
Here's an example of how to create an indexer data source object using the REST API.
104126

105127
```http
106-
POST https://[service name].search.windows.net/datasources?api-version=2021-04-30-preview
107-
Content-Type: application/json
108-
api-key: [Search service admin key]
128+
POST https://[service name].search.windows.net/datasources?api-version=2023-11-01
109129
110130
{
111131
"name": "[my-cosmosdb-ds]",
112132
"type": "cosmosdb",
113133
"credentials": {
114-
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=[SQL | Gremlin | MongoDB];IdentityAuthType=[AccessToken | AccountKey]"
134+
"connectionString": "ResourceId=/subscriptions/[subscription-id]/resourceGroups/[rg-name]/providers/Microsoft.DocumentDB/databaseAccounts/[cosmos-account-name];Database=[cosmos-database];ApiKind=SQL;IdentityAuthType=[AccessToken | AccountKey]"
115135
},
116136
"container": {
117137
"name": "[my-cosmos-collection]", "query": null
@@ -124,49 +144,13 @@ api-key: [Search service admin key]
124144
}
125145
```
126146

127-
## Create the index
128-
129-
The index specifies the fields in a document, attributes, and other constructs that shape the search experience.
130-
131-
Here's a [Create Index](/rest/api/searchservice/create-index) REST API call with a searchable `booktitle` field:
132-
133-
```http
134-
POST https://[service name].search.windows.net/indexes?api-version=2020-06-30
135-
Content-Type: application/json
136-
api-key: [admin key]
137-
138-
{
139-
"name" : "my-target-index",
140-
"fields": [
141-
{ "name": "id", "type": "Edm.String", "key": true, "searchable": false },
142-
{ "name": "booktitle", "type": "Edm.String", "searchable": true, "filterable": false, "sortable": false, "facetable": false }
143-
]
144-
}
145-
```
146-
147-
## Create the indexer
148-
149-
An indexer connects a data source with a target search index and provides a schedule to automate the data refresh. Once the index and data source have been created, you're ready to create and run the indexer. If the indexer is successful, the connection syntax and role assignments are valid.
150-
151-
Here's a [Create Indexer](/rest/api/searchservice/create-indexer) REST API call with an Azure Cosmos DB for NoSQL indexer definition. The indexer runs when you submit the request.
152-
153-
```http
154-
POST https://[service name].search.windows.net/indexers?api-version=2020-06-30
155-
Content-Type: application/json
156-
api-key: [admin key]
157-
158-
{
159-
"name" : "cosmos-db-indexer",
160-
"dataSourceName" : "cosmos-db-datasource",
161-
"targetIndexName" : "my-target-index"
162-
}
163-
```
147+
Connection information and permissions on the remote service are validated at run time during indexer execution. If the indexer is successful, the connection syntax and role assignments are valid. For more information, see [Run or reset indexers, skills, or documents](search-howto-run-reset-indexers.md).
164148

165149
## Troubleshooting
166150

167-
If you recently rotated your Azure Cosmos DB account keys, you need to wait up to 15 minutes for the managed identity connection string to work.
151+
For Azure Cosmos DB for NoSQL, check whether the account has its access restricted to select networks. You can rule out any firewall issues by trying the connection without restrictions in place.
168152

169-
Check to see if the Azure Cosmos DB account has its access restricted to select networks. You can rule out any firewall issues by trying the connection without restrictions in place.
153+
For Gremlin or MongoDB, if you recently rotated your Azure Cosmos DB account keys, you need to wait up to 15 minutes for the managed identity connection string to work.
170154

171155
## See also
172156

‎articles/search/search-howto-managed-identities-data-sources.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,12 +11,14 @@ ms.custom:
1111
- ignite-2023
1212
- build-2024
1313
ms.topic: how-to
14-
ms.date: 06/03/2024
14+
ms.date: 06/10/2024
1515
---
1616

17-
# Configure a search service to connect using a managed identity
17+
# Configure a search service to connect using a managed identity in Azure AI Search
1818

19-
You can configure an Azure AI Search service to make outbound connections to other Azure resources using a [system-assigned or user-assigned managed identity](../active-directory/managed-identities-azure-resources/overview.md) and an Azure role assignment. Managed identities and role assignments eliminate the need for passing secrets and credentials in a connection string or code.
19+
You can use Microsoft Entra ID and role assignments for outbound connections from Azure AI Search to resources providing data, applied AI, or vectorization during indexing or queries.
20+
21+
To use roles on an outbound connection, first configure your search service to use either a [system-assigned or user-assigned managed identity](../active-directory/managed-identities-azure-resources/overview.md) as the security principle for your search service in a Microsoft Entra tenant. Once you have a managed identity, you can assign roles for authorized access. Managed identities and role assignments eliminate the need for passing secrets and credentials in a connection string or code.
2022

2123
## Prerequisites
2224

‎articles/search/search-howto-managed-identities-storage.md

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,8 +30,11 @@ You can use a system-assigned managed identity or a user-assigned managed identi
3030
## Create a role assignment in Azure Storage
3131

3232
1. Sign in to Azure portal and find your storage account.
33+
3334
1. Select **Access control (IAM)**.
35+
3436
1. Select **Add** and then select **Role assignment**.
37+
3538
1. From the list of job function roles, select the roles needed for your search service:
3639

3740
| Task | Role assignment |
@@ -45,8 +48,11 @@ You can use a system-assigned managed identity or a user-assigned managed identi
4548
| Save debug session state | Add **Storage Blob Data Contributor** |
4649

4750
1. Select **Next**.
51+
4852
1. Select **Managed identity** and then select **Members**.
49-
1. Filter by system-assigned managed identities or user-assigned managed identities. If you don't have a managed identity, see [Configure search to use a managed identity](search-howto-managed-identities-data-sources.md). If you already set one up but it's not available, give it a few minutes.
53+
54+
1. Filter by system-assigned managed identities or user-assigned managed identities. You should see the managed identity that you previously created for your search service. If you don't have one, see [Configure search to use a managed identity](search-howto-managed-identities-data-sources.md). If you already set one up but it's not available, give it a few minutes.
55+
5056
1. Select the identity and save the role assignment.
5157

5258
## Specify a managed identity in a connection string
@@ -85,7 +91,7 @@ POST https://[service name].search.windows.net/datasources?api-version=2023-11-0
8591

8692
You must have a [user-assigned managed identity already configured](search-howto-managed-identities-data-sources.md) and associated with your search service, and the identity must have a role-assignment on Azure Storage.
8793

88-
Connections made through user-assigned managed identities use the same credentials as a system-assigned managed identity, plus an extra identity property that contains the collection of user-assigned managed identities. Only one user-assigned managed identity should be provided when creating the data source. Set `userAssignedIdentity` to the user-assigned managed identity..
94+
Connections made through user-assigned managed identities use the same credentials as a system-assigned managed identity, plus an extra identity property that contains the collection of user-assigned managed identities. Only one user-assigned managed identity should be provided when creating the data source. Set `userAssignedIdentity` to the user-assigned managed identity.
8995

9096
Provide a `ResourceId` that has no account key or password. The `ResourceId` must include the subscription ID of the storage account, the resource group of the storage account, and the storage account name.
9197

0 commit comments

Comments
 (0)