Connessione a Ricerca di intelligenza artificiale di Azure usando i controlli di accesso in base al ruolo

Azure offre un sistema globale di autorizzazione di controllo degli accessi in base al ruolo per tutti i servizi in esecuzione nella piattaforma. In Ricerca di intelligenza artificiale di Azure è possibile assegnare ruoli di Azure per:

• Amministrazione del servizio
• Sviluppo o accesso in scrittura a un servizio di ricerca
• Accesso in sola lettura per le query
• Accesso con ambito a un singolo indice

L'accesso per utente ai risultati della ricerca (talvolta definito sicurezza a livello di riga o sicurezza a livello di documento) non è supportato tramite le assegnazioni di ruolo. Come soluzione alternativa, creare filtri di sicurezza che tagliano i risultati in base all'identità utente, rimuovendo i documenti per i quali il richiedente non deve avere accesso. Per una dimostrazione, vedere questo esempio di chat aziendale usando RAG .

Le assegnazioni di ruolo sono cumulative e diffuse in tutti gli strumenti e le librerie client. È possibile assegnare ruoli usando uno degli approcci supportati descritti nella documentazione sul controllo degli accessi in base al ruolo di Azure.

L'accesso basato sui ruoli è facoltativo, ma consigliato. L'alternativa è l'autenticazione basata su chiave, ovvero l'impostazione predefinita.

Prerequisiti

• Proprietario, Accesso utenti Amministrazione istrator o un ruolo con autorizzazioni Microsoft.Authorization/roleAssignments/write.

• Un servizio di ricerca in qualsiasi area, in qualsiasi livello.

Limiti

• Il controllo degli accessi in base al ruolo può aumentare la latenza di alcune richieste. Ogni combinazione univoca di risorsa del servizio (indice, indicizzatore e così via) e entità servizio attiva un controllo di autorizzazione. Questi controlli di autorizzazione possono aggiungere fino a 200 millisecondi di latenza per richiesta.

• In rari casi in cui le richieste provengono da un numero elevato di entità servizio diverse, tutte destinate a risorse del servizio diverse (indici, indicizzatori e così via), è possibile che i controlli di autorizzazione comportino una limitazione. La limitazione si verifica solo se vengono usate centinaia di combinazioni univoche di risorse del servizio di ricerca e entità servizio entro un secondo.

Abilitare l'accesso in base al ruolo per le operazioni del piano dati

I ruoli per l'amministrazione del servizio (piano di controllo) sono obbligatori. I ruoli per le operazioni del piano dati sono facoltativi. È necessario abilitare l'accesso in base al ruolo prima di poter assegnare ruoli collaboratore al servizio di ricerca, collaboratore ai dati dell'indice di ricerca o ruolo con autorizzazioni di lettura per l'indice di ricerca per le operazioni sui dati.

In questo passaggio configurare il servizio di ricerca per riconoscere un'intestazione di autorizzazione nelle richieste del piano dati che forniscono un token di accesso OAuth2.

Il piano dati fa riferimento a operazioni sull'endpoint del servizio di ricerca, ad esempio l'indicizzazione o le query, o qualsiasi altra operazione specificata nell'API REST di ricerca o nelle librerie client equivalenti.

Azure portal

1. Accedere al portale di Azure e aprire la pagina del servizio di ricerca.

2. Selezionare Chiavi nel riquadro di spostamento a sinistra.

   

3. Scegliere Controllo basato su ruoli o Entrambi se si vuole flessibilità.

   Opzione	Descrizione
   Chiave API	(impostazione predefinita). Richiede chiavi API nell'intestazione della richiesta per l'autorizzazione.
   Controllo degli accessi in base al ruolo	Richiede l'appartenenza a un'assegnazione di ruolo per completare l'attività. Richiede anche un'intestazione di autorizzazione nella richiesta.
   Entrambi	Le richieste sono valide usando una chiave API o un controllo degli accessi in base al ruolo, ma se si specificano entrambe nella stessa richiesta, viene usata la chiave API.

La modifica è effettiva immediatamente, ma attendere alcuni secondi prima di assegnare i ruoli.

Quando si abilita il controllo degli accessi in base al ruolo, la modalità di errore è "http401WithBearerChallenge" se l'autorizzazione non riesce.

REST API

Usare l'API REST di gestione Creare o aggiornare il servizio per il controllo degli accessi in base al ruolo.

Tutte le chiamate all'API REST di gestione vengono autenticate tramite Microsoft Entra ID. Per informazioni sulla configurazione delle richieste autenticate, vedere Gestire Ricerca di intelligenza artificiale di Azure con REST.

1. Ottenere le impostazioni del servizio in modo da poter esaminare la configurazione corrente.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Usare PATCH per aggiornare la configurazione del servizio. Le modifiche seguenti consentono sia le chiavi che l'accesso in base al ruolo. Se si vuole una configurazione solo ruoli, vedere Disabilitare le chiavi API.

   In "properties" impostare "authOptions" su "aadOrApiKey". La proprietà "disableLocalAuth" deve essere false per impostare "authOptions".

   Facoltativamente, impostare "aadAuthFailureMode" per specificare se 401 viene restituito anziché 403 quando l'autenticazione non riesce. I valori validi sono "http401WithBearerChallenge" o "http403".

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": false,
           "authOptions": {
               "aadOrApiKey": {
                   "aadAuthFailureMode": "http401WithBearerChallenge"
               }
           }
       }
   }
   

La modifica è effettiva immediatamente, ma attendere alcuni secondi prima di assegnare i ruoli.

Quando si abilita il controllo degli accessi in base al ruolo, la modalità di errore è "http401WithBearerChallenge" se l'autorizzazione non riesce.

Ruoli predefiniti usati in Ricerca di intelligenza artificiale di Azure

Vengono compilati i ruoli seguenti. Se questi ruoli non sono sufficienti, creare un ruolo personalizzato.

Ruolo	Plane	Descrizione
Proprietario	Controllo e dati	Accesso completo al piano di controllo della risorsa di ricerca, inclusa la possibilità di assegnare ruoli di Azure. Solo il ruolo Proprietario può abilitare o disabilitare le opzioni di autenticazione o gestire i ruoli per altri utenti. Gli amministratori delle sottoscrizioni sono membri per impostazione predefinita. Nel piano dati, questo ruolo ha lo stesso accesso del ruolo Collaboratore del servizio di ricerca. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query o indicizzare documenti.
Collaboratore	Controllo e dati	Stesso livello di accesso del piano di controllo a Proprietario, meno la possibilità di assegnare ruoli o modificare le opzioni di autenticazione. Nel piano dati, questo ruolo ha lo stesso accesso del ruolo Collaboratore del servizio di ricerca. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query o indicizzare documenti.
Lettore	Controllo e dati	Accesso in lettura nell'intero servizio, incluse le metriche di ricerca, le metriche del contenuto (archiviazione utilizzata, il numero di oggetti) e le definizioni degli oggetti delle risorse del piano dati (indici, indicizzatori e così via). Tuttavia, non può leggere le chiavi API o leggere il contenuto all'interno degli indici.
Collaboratore servizi di ricerca	Controllo e dati	Accesso in lettura/scrittura alle definizioni di oggetti (indici, alias, mappe sinonimi, indicizzatori, origini dati e set di competenze). Questo ruolo è destinato agli sviluppatori che creano oggetti e agli amministratori che gestiscono un servizio di ricerca e i relativi oggetti, ma senza accesso al contenuto dell'indice. Usare questo ruolo per creare, eliminare ed elencare indici, ottenere definizioni di indice, ottenere informazioni sul servizio (statistiche e quote), analizzatori di test, creare e gestire mappe sinonimiche, indicizzatori, origini dati e set di competenze. Vedere Microsoft.Search/searchServices/* per l'elenco delle autorizzazioni.
Collaboratore ai dati dell'indice di ricerca	Dati	Accesso in lettura/scrittura al contenuto negli indici. Questo ruolo è destinato agli sviluppatori o ai proprietari di indici che devono importare, aggiornare o eseguire query sulla raccolta documenti di un indice. Questo ruolo non supporta la creazione o la gestione degli indici. Per impostazione predefinita, questo ruolo è per tutti gli indici in un servizio di ricerca. Vedere Concedere l'accesso a un singolo indice per restringere l'ambito.
Lettore di dati dell'indice di ricerca	Dati	Accesso in sola lettura per l'esecuzione di query sugli indici di ricerca. Questo ruolo è destinato ad app e utenti che eseguono query. Questo ruolo non supporta l'accesso in lettura alle definizioni degli oggetti. Ad esempio, non è possibile leggere una definizione di indice di ricerca o ottenere statistiche del servizio di ricerca. Per impostazione predefinita, questo ruolo è per tutti gli indici in un servizio di ricerca. Vedere Concedere l'accesso a un singolo indice per restringere l'ambito.

Nota

Se si disabilita l'accesso in base al ruolo di Azure, i ruoli predefiniti per il piano di controllo (Proprietario, Collaboratore, Lettore) continuano a essere disponibili. La disabilitazione dell'accesso basato sui ruoli rimuove solo le autorizzazioni correlate ai dati associate a tali ruoli. Se i ruoli del piano dati sono disabilitati, collaboratore del servizio di ricerca equivale a Collaboratore piano di controllo.

Assegnazione di ruoli

In questa sezione assegnare ruoli per:

• Amministrazione del servizio
• Sviluppo o accesso in scrittura a un servizio di ricerca
• Accesso in sola lettura per le query

Assegnare ruoli per l'amministrazione del servizio

Gli amministratori del servizio possono creare e configurare un servizio di ricerca ed eseguire tutte le operazioni del piano di controllo descritte nell'API REST di gestione o nelle librerie client equivalenti. A seconda del ruolo, è anche possibile eseguire la maggior parte delle attività dell'API REST di ricerca del piano dati.

Azure portal

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

5. Selezionare un ruolo applicabile:

   • Proprietario (accesso completo a tutte le operazioni del piano dati e del piano di controllo, ad eccezione delle autorizzazioni di query)
   • Collaboratore (uguale a Proprietario, ad eccezione delle autorizzazioni per assegnare i ruoli)
   • Lettore (accettabile per il monitoraggio e la visualizzazione delle metriche)

6. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra.

7. Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.

PowerShell

Quando si usa PowerShell per assegnare ruoli, chiamare New-AzRoleAssignment, specificando il nome utente o il gruppo di Azure e l'ambito dell'assegnazione.

Questo esempio crea un'assegnazione di ruolo con ambito a un servizio di ricerca:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Reader" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Assegnare ruoli per lo sviluppo

Le assegnazioni di ruolo sono globali nel servizio di ricerca. Per definire l'ambito delle autorizzazioni per un singolo indice, usare PowerShell o l'interfaccia della riga di comando di Azure per creare un ruolo personalizzato.

Importante

Se si configura l'accesso in base al ruolo per un servizio o un indice e si fornisce anche una chiave API nella richiesta, il servizio di ricerca usa la chiave API per l'autenticazione.

Azure portal

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

   

5. Selezionare un ruolo:

   • Collaboratore al servizio di ricerca (operazioni create-read-update-delete su indici, indicizzatori, set di competenze e altri oggetti di primo livello)
   • Collaboratore ai dati dell'indice di ricerca (caricare documenti ed eseguire processi di indicizzazione)
   • Lettore di dati dell'indice di ricerca (eseguire query su un indice)

   Un'altra combinazione di ruoli che fornisce l'accesso completo è Collaboratore o Proprietario, oltre a Lettore dati indice di ricerca.

6. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra.

7. Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.

8. Ripetere per gli altri ruoli. La maggior parte degli sviluppatori ha bisogno di tutti e tre.

PowerShell

Quando si usa PowerShell per assegnare ruoli, chiamare New-AzRoleAssignment, specificando il nome utente o il gruppo di Azure e l'ambito dell'assegnazione.

Questo esempio crea un'assegnazione di ruolo con ambito a un servizio di ricerca:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>"

Questo esempio crea un'assegnazione di ruolo con ambito a un indice specifico:

New-AzRoleAssignment -SignInName <email> `
    -RoleDefinitionName "Search Index Data Contributor" `
    -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"

Assegnare ruoli per le query di sola lettura

Usare il ruolo Lettore dati dell'indice di ricerca per app e processi che richiedono solo l'accesso in lettura a un indice. Questo è un ruolo molto specifico. Concede l'accessoGET o POST alla raccolta di documenti di un indice di ricerca per la ricerca, il completamento automatico e i suggerimenti.

Non supporta operazioni GET o LIST su un indice o su altri oggetti di primo livello o statistiche del servizio GET.

Azure portal

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Selezionare Controllo di accesso (IAM) nel riquadro di spostamento a sinistra.

4. Selezionare Aggiungi>Aggiungi assegnazione di ruolo.

5. Selezionare il ruolo Lettore dati indice di ricerca.

6. Nella scheda Membri selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio, è possibile usare un'identità gestita dal sistema o dall'utente. Scegliere questa opzione se l'assegnazione di ruolo è per un'identità del servizio.

7. Nella scheda Rivedi e assegna selezionare Rivedi e assegna per assegnare il ruolo.

PowerShell

Quando si usa PowerShell per assegnare ruoli, chiamare New-AzRoleAssignment, specificando il nome utente o il gruppo di Azure e l'ambito dell'assegnazione.

1. Ottenere l'ID sottoscrizione, il gruppo di risorse del servizio di ricerca e il nome del servizio di ricerca.

2. Ottenere l'identificatore dell'oggetto del servizio di Azure, ad esempio Azure OpenAI.

    Get-AzADServicePrincipal -SearchString <YOUR AZURE OPENAI RESOURCE NAME>
   

3. Ottenere la definizione del ruolo ed esaminare le autorizzazioni per assicurarsi che si tratta del ruolo desiderato.

   Get-AzRoleDefinition -Name "Search Index Data Reader"
   

4. Creare l'assegnazione di ruolo sostituendo i valori validi per i segnaposto.

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID -RoleDefinitionName "Search Index Data Reader" -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME
   

5. Di seguito è riportato un esempio di assegnazione di ruolo con ambito di un indice specifico:

   New-AzRoleAssignment -ObjectId YOUR-AZURE-OPENAI-OBJECT-ID `
       -RoleDefinitionName "Search Index Data Reader" `
       -Scope /subscriptions/YOUR-SUBSCRIPTION-ID/resourcegroups/YOUR-RESOURCE-GROUP/providers/Microsoft.Search/searchServices/YOUR-SEARCH-SERVICE-NAME/indexes/YOUR-INDEX-NAME
   

Testare le assegnazioni di ruolo

Usare un client per testare le assegnazioni di ruolo. Tenere presente che i ruoli sono ruoli cumulativi e ereditati con ambito a livello di sottoscrizione o gruppo di risorse non possono essere eliminati o negati a livello di risorsa (servizio di ricerca).

Assicurarsi di registrare l'applicazione client con l'ID Microsoft Entra e di disporre di assegnazioni di ruolo prima di testare l'accesso.

Azure portal

1. Accedere al portale di Azure.

2. Passare al servizio di ricerca.

3. Nella pagina Panoramica selezionare la scheda Indici :

   • I collaboratori del servizio di ricerca possono visualizzare e creare qualsiasi oggetto, ma non è possibile caricare documenti o eseguire query su un indice. Per verificare le autorizzazioni, creare un indice di ricerca.

   • I collaboratori ai dati dell'indice di ricerca possono caricare documenti. Non è disponibile alcuna opzione carica documenti nel portale all'esterno della procedura guidata Importa dati, ma è possibile reimpostare ed eseguire un indicizzatore per confermare le autorizzazioni di caricamento dei documenti.

   • I lettori di dati dell'indice di ricerca possono eseguire query sull'indice. Per verificare le autorizzazioni, usare Esplora ricerche. Dovrebbe essere possibile inviare query e visualizzare i risultati, ma non è consigliabile visualizzare la definizione dell'indice o crearne una.

REST API

Questo approccio presuppone Visual Studio Code con un'estensione client REST.

1. Aprire una shell dei comandi per l'interfaccia della riga di comando di Azure e accedere alla sottoscrizione di Azure.

   az login
   

2. Ottenere l'ID tenant e l'ID sottoscrizione. L'ID viene usato come variabile in un passaggio futuro.

   az account show
   

3. Ottenere un token di accesso.

   az account get-access-token --query accessToken --output tsv
   

4. In un nuovo file di testo in Visual Studio Code incollare queste variabili:

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

5. Incollare e quindi inviare una richiesta che usa le variabili specificate. Per il ruolo "Lettore dati indice di ricerca", è possibile inviare una query. È possibile usare qualsiasi versione dell'API supportata.

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Per altre informazioni su come acquisire un token per un ambiente specifico, vedere Gestire un servizio di ricerca di intelligenza artificiale di Azure con le API REST e le librerie di autenticazione di Microsoft Identity Platform.

.NET

1. Usare il pacchetto Azure.Search.Documents .

2. Usare Azure.Identity per .NET per l'autenticazione del token. Microsoft consiglia DefaultAzureCredential() per la maggior parte degli scenari.

3. Di seguito è riportato un esempio di connessione client tramite DefaultAzureCredential().

   // Create a SearchIndexClient to send create/delete index commands
   SearchIndexClient adminClient = new SearchIndexClient(serviceEndpoint, new DefaultAzureCredential());
   
   // Create a SearchClient to load and query documents
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, new DefaultAzureCredential());
   

4. Ecco un altro esempio di uso delle credenziali dei segreti client:

   var tokenCredential =  new ClientSecretCredential(aadTenantId, aadClientId, aadSecret);
   SearchClient srchclient = new SearchClient(serviceEndpoint, indexName, tokenCredential);
   

Python

1. Usare azure.search.documents (Azure SDK per Python).

2. Usare Azure.Identity per Python per l'autenticazione del token.

3. Usare DefaultAzureCredential se il client Python è un'applicazione che esegue il lato server. Abilitare l'autenticazione interattiva se l'app viene eseguita in un browser.

4. Ecco un esempio:

   from azure.search.documents import SearchClient
   from azure.identity import DefaultAzureCredential
   
   credential = DefaultAzureCredential()
   endpoint = "https://<mysearch>.search.windows.net"
   index_name = "myindex"
   client = SearchClient(endpoint=endpoint, index_name=index_name, credential=credential)
   

JavaScript

1. Usare @azure/search-documents (Azure SDK per JavaScript), versione 11.3.

2. Usare Azure.Identity per JavaScript per l'autenticazione del token.

3. Se si usa React, usare per l'autenticazione InteractiveBrowserCredential di Microsoft Entra per la ricerca. Per informazioni dettagliate, vedere Quando usare @azure/identity .

Java

1. Usare azure-search-documents (Azure SDK per Java).

2. Usare Azure.Identity per Java per l'autenticazione del token.

3. Microsoft consiglia DefaultAzureCredential per le app eseguite in Azure.

Testare come utente corrente

Se si è già un collaboratore o proprietario del servizio di ricerca, è possibile presentare un token di connessione per l'identità utente per l'autenticazione in Ricerca di intelligenza artificiale di Azure.

1. Ottenere un token di connessione per l'utente corrente usando l'interfaccia della riga di comando di Azure:

   az account get-access-token --scope https://search.azure.com/.default
   

   In alternativa, usando PowerShell:

   Get-AzAccessToken -ResourceUrl https://search.azure.com
   

2. In un nuovo file di testo in Visual Studio Code incollare queste variabili:

   @baseUrl = PASTE-YOUR-SEARCH-SERVICE-URL-HERE
   @index-name = PASTE-YOUR-INDEX-NAME-HERE
   @token = PASTE-YOUR-TOKEN-HERE
   

3. Incollare e quindi inviare una richiesta per confermare l'accesso. Ecco uno che esegue una query sull'indice hotels-quickstart

   POST https://{{baseUrl}}/indexes/{{index-name}}/docs/search?api-version=2023-11-01 HTTP/1.1
     Content-type: application/json
     Authorization: Bearer {{token}}
   
       {
            "queryType": "simple",
            "search": "motel",
            "filter": "",
            "select": "HotelName,Description,Category,Tags",
            "count": true
        }
   

Concedere l'accesso a un singolo indice

In alcuni scenari, è possibile limitare l'accesso di un'applicazione a una singola risorsa, ad esempio un indice.

Il portale attualmente non supporta le assegnazioni di ruolo a questo livello di granularità, ma può essere eseguita con PowerShell o l'interfaccia della riga di comando di Azure.

In PowerShell usare New-AzRoleAssignment, specificando il nome dell'utente o del gruppo di Azure e l'ambito dell'assegnazione.

1. Caricare i Azure moduli e e AzureAD connettersi all'account Azure:

   Import-Module -Name Az
   Import-Module -Name AzureAD
   Connect-AzAccount
   

2. Aggiungere un'assegnazione di ruolo con ambito a un singolo indice:

   New-AzRoleAssignment -ObjectId <objectId> `
       -RoleDefinitionName "Search Index Data Contributor" `
       -Scope  "/subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.Search/searchServices/<search-service>/indexes/<index-name>"
   

Creare un ruolo personalizzato

Se i ruoli predefiniti non forniscono la combinazione corretta di autorizzazioni, è possibile creare un ruolo personalizzato per supportare le operazioni necessarie.

In questo esempio viene clonato il lettore dati dell'indice di ricerca e quindi viene aggiunta la possibilità di elencare gli indici in base al nome. In genere, elencare gli indici in un servizio di ricerca è considerato un diritto amministrativo.

Azure portal

Questi passaggi sono derivati da Creare o aggiornare i ruoli personalizzati di Azure usando il portale di Azure. La clonazione da un ruolo esistente è supportata in una pagina del servizio di ricerca.

Questi passaggi creano un ruolo personalizzato che aumenta i diritti di query di ricerca per includere l'elenco degli indici in base al nome. In genere, l'elenco degli indici è considerato una funzione di amministrazione.

1. Nella portale di Azure passare al servizio di ricerca.

2. Nel riquadro di spostamento a sinistra selezionare Controllo di accesso (IAM).

3. Nella barra delle azioni selezionare Ruoli.

4. Fare clic con il pulsante destro del mouse su Search Index Data Reader (o su un altro ruolo) e selezionare Clona per aprire la procedura guidata Crea un ruolo personalizzato.

5. Nella scheda Informazioni di base specificare un nome per il ruolo personalizzato, ad esempio "Cerca indice Esplora dati" e quindi selezionare Avanti.

6. Nella scheda Autorizzazioni selezionare Aggiungi autorizzazione.

7. Nella scheda Aggiungi autorizzazioni cercare e quindi selezionare il riquadro Microsoft Search .

8. Impostare le autorizzazioni per il ruolo personalizzato. Nella parte superiore della pagina, usando la selezione predefinita Azioni :

   • In Microsoft.Search/operations selezionare Leggi : elenca tutte le operazioni disponibili.
   • In Microsoft.Search/searchServices/indexes selezionare Lettura: Indice di lettura.

9. Nella stessa pagina passare a Azioni dati e in Microsoft.Search/searchServices/indexes/documents selezionare Lettura : Lettura documenti.

   La definizione JSON è simile all'esempio seguente:

   {
    "properties": {
        "roleName": "search index data explorer",
        "description": "",
        "assignableScopes": [
            "/subscriptions/0000000000000000000000000000000/resourceGroups/free-search-svc/providers/Microsoft.Search/searchServices/demo-search-svc"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
      }
    }
   

10. Selezionare Rivedi e crea per creare il ruolo. È ora possibile assegnare utenti e gruppi al ruolo.

Azure PowerShell

L'esempio di PowerShell mostra la sintassi JSON per la creazione di un ruolo personalizzato che è un clone del lettore di dati dell'indice di ricerca, ma con la possibilità di elencare tutti gli indici in base al nome.

1. Esaminare l'elenco delle autorizzazioni atomica per determinare quali autorizzazioni sono necessarie. Per questo esempio, è necessario quanto segue:

   "Microsoft.Search/operations/read",
   "Microsoft.Search/searchServices/read",
   "Microsoft.Search/searchServices/indexes/read"
   

2. Configurare una sessione di PowerShell per creare il ruolo personalizzato. Per istruzioni dettagliate, vedere Azure PowerShell

3. Specificare la definizione del ruolo come documento JSON. L'esempio seguente illustra la sintassi per la creazione di un ruolo personalizzato con PowerShell.

{
  "Name": "Search Index Data Explorer",
  "Id": "88888888-8888-8888-8888-888888888888",
  "IsCustom": true,
  "Description": "List all indexes on the service and query them.",
  "Actions": [
      "Microsoft.Search/operations/read",
      "Microsoft.Search/searchServices/read"
  ],
  "NotActions": [],
  "DataActions": [
      "Microsoft.Search/searchServices/indexes/read"
  ],
  "NotDataActions": [],
  "AssignableScopes": [
    "/subscriptions/{subscriptionId1}"
  ]
}

Nota

Se l'ambito assegnabile è a livello di indice, l'azione dei dati deve essere "Microsoft.Search/searchServices/indexes/documents/read".

REST API

1. Esaminare l'elenco delle autorizzazioni atomica per determinare quali autorizzazioni sono necessarie.

2. Per la procedura, vedere Creare o aggiornare ruoli personalizzati di Azure usando l'API REST.

3. Clonare o creare un ruolo oppure usare JSON per specificare il ruolo personalizzato (vedere la scheda PowerShell per la sintassi JSON).

Interfaccia della riga di comando di Azure

1. Esaminare l'elenco delle autorizzazioni atomica per determinare quali autorizzazioni sono necessarie.

2. Per la procedura, vedere Creare o aggiornare ruoli personalizzati di Azure usando l'interfaccia della riga di comando di Azure.

3. Clonare o creare un ruolo oppure usare JSON per specificare il ruolo personalizzato (vedere la scheda PowerShell per la sintassi JSON).

Disabilitare l'autenticazione con chiave API

L'accesso alla chiave o l'autenticazione locale può essere disabilitato nel servizio se si usano i ruoli predefiniti e l'autenticazione di Microsoft Entra. La disabilitazione delle chiavi API fa sì che il servizio di ricerca rifiuti tutte le richieste correlate ai dati che passano una chiave API nell'intestazione.

Nota

Amministrazione le chiavi API possono essere disabilitate solo, non eliminate. Le chiavi API di query possono essere eliminate.

Per disabilitare le funzionalità sono necessarie autorizzazioni proprietario o collaboratore.

Per disabilitare l'autenticazione basata su chiave, usare portale di Azure o l'API REST di gestione.

Portale

1. Nella portale di Azure passare al servizio di ricerca.

2. Nel riquadro di spostamento a sinistra selezionare Chiavi.

3. Selezionare Controllo degli accessi in base al ruolo.

La modifica è effettiva immediatamente, ma attendere alcuni secondi prima del test. Supponendo di disporre dell'autorizzazione per assegnare ruoli come membro del proprietario, dell'amministratore del servizio o del coamministratore, è possibile usare le funzionalità del portale per testare l'accesso in base al ruolo.

REST API

Per disabilitare l'autenticazione basata su chiave, impostare "disableLocalAuth" su true.

1. Ottenere le impostazioni del servizio in modo da poter esaminare la configurazione corrente.

   GET https://management.azure.com/subscriptions/{{subscriptionId}}/providers/Microsoft.Search/searchServices?api-version=2023-11-01
   

2. Usare PATCH per aggiornare la configurazione del servizio. La modifica seguente imposta "authOptions" su null.

   PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
   {
       "properties": {
           "disableLocalAuth": true
       }
   }
   

Le richieste che includono solo una chiave API, senza token di connessione, hanno esito negativo con HTTP 401.

Per riabilitare l'autenticazione della chiave, eseguire di nuovo l'ultima richiesta, impostando "disableLocalAuth" su false. Il servizio di ricerca riprende automaticamente l'accettazione delle chiavi API nella richiesta (presupponendo che siano specificate).

Accesso condizionale

È consigliabile usare l'accesso condizionale Microsoft Entra se è necessario applicare criteri aziendali, ad esempio l'autenticazione a più fattori.

Per abilitare un criterio di accesso condizionale per Ricerca di intelligenza artificiale di Azure, seguire questa procedura:

1. Accedere al portale di Azure.

2. Cercare l'accesso condizionale Microsoft Entra.

3. Selezionare Criteri.

4. Selezionare Nuovi criteri.

5. Nella sezione App cloud o azioni dei criteri aggiungere Ricerca di intelligenza artificiale di Azure come app cloud a seconda di come si vuole configurare i criteri.

6. Aggiornare i parametri rimanenti dei criteri. Ad esempio, specificare a quali utenti e gruppi si applica questo criterio.

7. Salvare il criterio.

Importante

Se al servizio di ricerca è assegnata un'identità gestita, il servizio di ricerca specifico verrà visualizzato come app cloud che può essere inclusa o esclusa come parte dei criteri di accesso condizionale. I criteri di accesso condizionale non possono essere applicati a un servizio di ricerca specifico. Assicurarsi invece di selezionare l'app cloud di Ricerca di intelligenza artificiale di Azure generale.

Risoluzione dei problemi di controllo degli accessi in base al ruolo

Quando si sviluppano applicazioni che usano il controllo degli accessi in base al ruolo per l'autenticazione, possono verificarsi alcuni problemi comuni:

• Se il token di autorizzazione proviene da un'identità gestita e le autorizzazioni appropriate sono state assegnate di recente, potrebbero essere necessarie diverse ore per rendere effettive queste assegnazioni di autorizzazioni.

• La configurazione predefinita per un servizio di ricerca è l'autenticazione basata su chiave. Se l'impostazione della chiave predefinita non è stata modificata su Entrambi o Controllo degli accessi in base al ruolo, tutte le richieste che usano l'autenticazione basata su ruoli vengono negate automaticamente indipendentemente dalle autorizzazioni sottostanti.