Connettersi a Azure AI Search usando i ruoli

Note

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

Azure AI Search supporta il controllo degli accessi basato su role tramite Microsoft Entra ID. L'accesso in base al ruolo è facoltativo, ma consigliato. L'alternativa è l'autenticazione basata su chiave, ovvero l'impostazione predefinita.

Se si assegnano più ruoli a un principale di sicurezza, le autorizzazioni vengono combinate. Le assegnazioni di ruolo si applicano a tutti gli strumenti e alle librerie client.

Questo articolo illustra come assegnare ruoli integrati per l'amministrazione dei servizi, lo sviluppo e l'accesso di sola lettura alle query e al recupero. Vengono inoltre illustrati i passaggi per la creazione di ruoli personalizzati e il test delle assegnazioni di ruolo.

Suggerimento

Prerequisiti

Ruoli predefiniti

I ruoli sono una raccolta di autorizzazioni che influiscono sul piano di controllo o sul piano dati:

  • Piano di controllo: Operazioni per il provisioning, la configurazione e l'amministrazione del servizio. Le operazioni del piano di controllo includono la creazione o l'eliminazione di servizi di ricerca, l'elenco delle chiavi API e la gestione delle impostazioni di rete e autenticazione. Disponibile tramite le API REST Azure Resource Manager, Search Management REST API e librerie client Azure SDK equivalenti.

  • Piano dati: Operazioni sull'endpoint del servizio di ricerca. Le operazioni del piano dati rientrano in due categorie: gestione degli oggetti e accesso al contenuto. Disponibile tramite le API REST del servizio Search e le librerie client Azure SDK equivalenti.

Descrizioni dei ruoli

I ruoli predefiniti seguenti concedono le autorizzazioni per Azure AI Search. I ruoli del piano di controllo sono sempre disponibili, mentre i ruoli del piano dati richiedono l'abilitazione dell'accesso in base al ruolo nel servizio di ricerca. È possibile combinare ruoli predefiniti per un accesso più ampio o creare un ruolo personalizzato con le autorizzazioni specifiche necessarie.

Ruolo Aereo Descrizione
Proprietario Controllo
  • Accesso completo al piano di controllo, inclusa la possibilità di assegnare ruoli e modificare le impostazioni di autenticazione.
  • Per impostazione predefinita, gli amministratori delle sottoscrizioni hanno questo ruolo.
  • Può gestire le chiavi API.
  • Non è possibile creare oggetti di ricerca, caricare documenti, indici di query o recuperare da knowledge base.
Collaboratore Controllo
  • Stesso livello di accesso al piano di controllo concesso al Proprietario, tranne per la possibilità di assegnare ruoli.
Lettore Controllo
  • Accesso al piano di controllo di sola lettura.
  • Può visualizzare le metriche del servizio e le definizioni degli oggetti.
  • Non è possibile visualizzare o gestire chiavi API, caricare documenti, indici di query o recuperare dalle knowledge base.
Collaboratore servizi di ricerca Controllo e dati
  • Accesso completo al piano di controllo. L'accesso al piano dati è limitato alla gestione degli oggetti.
  • Può creare indici, indicizzatori, set di competenze, knowledge base e altri oggetti di ricerca.
  • Non è possibile caricare documenti, eseguire query sugli indici o recuperarli dalle knowledge base.
  • Per l'elenco completo delle autorizzazioni, vedere Microsoft.Search/searchServices/*.
Collaboratore ai dati dell'indice di ricerca Data
  • Accesso al contenuto in lettura/scrittura.
  • Può caricare documenti, eseguire query sugli indici e recuperarli dalle knowledge base.
  • Non è possibile modificare le definizioni degli oggetti o recuperare le chiavi di amministrazione.
Lettore di dati dell'indice di ricerca Data
  • Accesso al contenuto in modalità sola lettura.
  • Può eseguire query sugli indici e recuperare dalle knowledge base.
  • Non è possibile caricare documenti, modificare le definizioni degli oggetti o recuperare le chiavi di amministrazione.

Importante

  • Proprietario, Collaboratore e Collaboratore del Servizio di Ricerca possono recuperare le chiavi di amministratore, che forniscono l'accesso completo in lettura/scrittura al piano dati. Concedere questi ruoli solo agli utenti attendibili.
  • Per impostazione predefinita, i ruoli del piano dati si applicano a tutti gli indici nel servizio di ricerca. Per limitare l'ambito del Contributore di dati dell'indice di ricerca o del Lettore di dati dell'indice di ricerca a un singolo indice, consultare Concedere l'accesso a un singolo indice.

Riepilogo delle autorizzazioni

Usare la tabella seguente per trovare rapidamente il ruolo che fornisce le autorizzazioni necessarie.

Autorizzazioni Proprietario/Collaboratore Reader Collaboratore servizi di ricerca Collaboratore ai dati dell'indice di ricerca Lettore di dati dell'indice di ricerca
Creare e configurare servizi Azure AI Search ✅ ❌ ✅ ❌ ❌
Accedere al servizio nel portale di Azure ✅ ✅ ✅ ❌ ❌
Visualizzare le proprietà, le metriche e l'endpoint del servizio ✅ ✅ ✅ ❌ ❌
Elencare tutti gli oggetti nel servizio ✅ ✅ ✅ ❌ ❌
Quote di accesso e statistiche del servizio ✅ ❌ ✅ ❌ ❌
Visualizzare, copiare e rigenerare le chiavi ✅ ❌ ✅ ❌ ❌
Impostare le opzioni di autenticazione ✅ ❌ ✅ ❌ ❌
Visualizzare ruoli, criteri e definizioni ✅ ✅ ✅ ❌ ❌
Configurare la sicurezza di rete e le connessioni private ✅ ❌ ✅ ❌ ❌
Creare, eseguire e gestire gli oggetti di ricerca 1 ❌ ❌ ✅ ❌ ❌
Caricare i dati per l'indicizzazione 2 ❌ ❌ ❌ ✅ ❌
Eseguire una query su un indice ❌ ❌ ❌ ✅ ✅
Estrarre da una base di conoscenza ❌ ❌ ❌ ✅ ✅
Ignorare i filtri di autorizzazione con lettura con privilegi elevati ❌ ❌ ❌ ✅ ❌

1 Include indici, indicizzatori, origini dati, insiemi di competenze, alias, mappe sinonimiche, sessioni di debug, knowledge base e fonti di conoscenza. Gli indicizzatori supportano anche operazioni di esecuzione e reimpostazione.

2 Un proprietario o un collaboratore può eseguire la procedura guidata Importa dati per creare e caricare indici, anche se non possono caricare documenti in altri client. Analogamente, gli indicizzatori possono scrivere in qualsiasi indice nel servizio di ricerca, indipendentemente dalle assegnazioni di ruolo per indice. In entrambi i casi, il servizio di ricerca (non l'utente) esegue le azioni del piano dati usando le autorizzazioni Microsoft.Search/searchServices/indexes/documents/*.

Assegnare ruoli predefiniti

In questa sezione si assegnano ruoli per:

Assegnare ruoli per l'amministrazione del servizio

I ruoli seguenti consentono di creare, configurare e gestire un servizio di ricerca. Questi ruoli sono gerarchici, quindi selezionare uno in base al livello di accesso necessario.

Ruolo Documento d'identità
Proprietario 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Collaboratore b24988ac-6180-42a0-ab88-20f7382dd24c
Lettore acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Passare al servizio di ricerca nel portale Azure.

  2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

  3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.

    Screenshot della pagina Controllo di accesso (IAM) per l'assegnazione dei ruoli di amministrazione del servizio.

  4. Selezionare un ruolo: Proprietario, Collaboratore o Lettore.

  5. Nella scheda Members selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio Azure, selezionare un'identità gestita assegnata dal sistema o assegnata dall'utente.

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

Assegnare ruoli per lo sviluppo

I ruoli seguenti consentono di creare oggetti di ricerca, caricare documenti, indici di query e recuperare dalle knowledge base. Assegnare tutti e tre i ruoli per coprire l'intera gamma di attività di sviluppo.

Ruolo Documento d'identità
Collaboratore servizi di ricerca 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Collaboratore ai dati dell'indice di ricerca 8ebe5a00-799e-43f5-93ac-243d3dce84a7
Lettore di dati dell'indice di ricerca 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Passare al servizio di ricerca nel portale Azure.

  2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

  3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.

    Screenshot della pagina di Controllo di Accesso (IAM) per l'assegnazione dei ruoli di sviluppo.

  4. Selezionare Collaboratore servizio di ricerca.

  5. Nella scheda Members selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio Azure, selezionare un'identità gestita assegnata dal sistema o assegnata dall'utente.

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

  7. Ripeti questi passaggi per assegnare Search Index Data Contributor e Search Index Data Reader.

Assegnare ruoli per l'accesso in sola lettura

Usare il ruolo seguente per le app e i processi che richiedono solo l'accesso in lettura agli indici e alle knowledge base. Le operazioni supportate includono la ricerca, la ricerca, il completamento automatico e i suggerimenti per gli indici e il recupero per le knowledge base.

Ruolo Documento d'identità
Lettore di dati dell'indice di ricerca 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Passare al servizio di ricerca nel portale Azure.

  2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

  3. Selezionare + Aggiungi>Aggiungi assegnazione di ruolo.

    Screenshot della pagina Controllo degli accessi (IAM) per l'assegnazione di ruoli di accesso ai dati in sola lettura.

  4. Selezionare il ruolo Lettore dati indice di ricerca .

  5. Nella scheda Members selezionare l'identità dell'utente o del gruppo Microsoft Entra. Se si configurano le autorizzazioni per un altro servizio Azure, selezionare un'identità gestita assegnata dal sistema o assegnata dall'utente.

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

Testare le assegnazioni di ruolo

Usare un client per testare le assegnazioni di ruolo. Tenere presente che i ruoli sono cumulativi. Non è possibile eliminare o negare ruoli ereditati con ambito a livello di sottoscrizione o di gruppo di risorse a livello di risorsa (servizio di ricerca).

Prima di procedere, configurare l'applicazione per le connessioni senza chiave e disporre di assegnazioni di ruolo.

  1. Passare al servizio di ricerca nel portale Azure.

  2. Nel riquadro sinistro selezionareIndici> per testare le autorizzazioni correlate all'indice:

    • I collaboratori del servizio di ricerca possono creare, modificare ed eliminare oggetti di ricerca, ma non possono caricare documenti o eseguire query. Per verificare le autorizzazioni, creare un indice di ricerca.

    • I collaboratori ai dati dell'indice di ricerca possono caricare documenti. Nel portale di Azure non esiste un'opzione per caricare i documenti tranne la procedura guidata Importa dati, ma è possibile reimpostare ed eseguire un indicizzatore per confermare le autorizzazioni al caricamento dei documenti.

    • I lettori di dati dell'indice di ricerca possono eseguire query sugli indici. Per verificare le autorizzazioni, usare Esplora ricerche. Dovrebbe essere possibile inviare query e visualizzare i risultati, ma non è consigliabile visualizzare le definizioni di indice o creare indici.

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.

Attualmente, il portale di Azure non supporta le assegnazioni di ruolo a livello di indice. Usare il interfaccia della riga di comando di Azure, PowerShell o l'API REST per assegnare ruoli con ambito a un singolo indice.

Ambito per indice e operazioni dell'indicizzatore

Le assegnazioni di ruolo per indice si applicano solo alle operazioni API dirette, ad esempio query o caricamenti di documenti da utenti o applicazioni. Gli indicizzatori non sono limitati dalle autorizzazioni per indice perché operano con credenziali a livello di servizio.

Un utente con il ruolo Collaboratore servizio di ricerca può creare indicizzatori che scrivono in qualsiasi indice nel servizio di ricerca, anche indici in cui tale utente non ha alcuna assegnazione di ruolo per indice.

Per un isolamento rigoroso dei dati tra gli indici, considerare questi approcci:

  • Usare servizi di ricerca separati per team o utenti che richiedono l'isolamento a livello di indice.
  • Assegnare collaboratore al servizio di ricerca solo agli amministratori che gestiscono gli indicizzatori.
  • Usare il controllo di accesso a livello di documento con filtri di sicurezza per limitare i risultati delle query all'interno di un indice condiviso.

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.

Gli esempi seguenti clonano il lettore dati dell'indice di ricerca e quindi aggiungono la possibilità di elencare gli indici in base al nome. In genere, elencare gli indici in un servizio di ricerca è considerato un diritto amministrativo.

  1. Accedere al portale di Azure e passare al servizio di ricerca.

  2. Nel riquadro sinistro selezionare Controllo di accesso (IAM).

  3. Nella scheda Ruoli, trova Lettore dati indice di ricerca o un altro ruolo, seleziona i tre puntini (...), quindi seleziona Clona.

  4. Nella scheda Basics immettere un nome per il ruolo personalizzato, ad esempio "Cerca indice Esplora dati", quindi selezionare Next.

  5. Nella scheda Autorizzazioni selezionare Aggiungi autorizzazioni.

  6. Nel riquadro Aggiungi autorizzazioni selezionare il riquadro Microsoft Search.

  7. Con Actions selezionata nella parte superiore, impostare le autorizzazioni seguenti:

    • In Microsoft.Search/operations selezionare Read : Elenca tutte le operazioni disponibili.
    • In Microsoft.Search/searchServices/indexes selezionare Read : Read Index.

  8. Passare a Data Actions nella parte superiore e in Microsoft.Search/searchServices/indexes/documents selezionare Read : Read Documents.

    La definizione JSON è simile all'esempio seguente:

    {
    "properties": {
        "roleName": "Search Index Data Explorer",
        "description": "List all indexes on the service and query them.",
        "assignableScopes": [
            "/subscriptions/<subscription>/resourceGroups/<resource-group>"
        ],
        "permissions": [
            {
                "actions": [
                    "Microsoft.Search/operations/read",
                    "Microsoft.Search/searchServices/indexes/read"
                ],
                "notActions": [],
                "dataActions": [
                    "Microsoft.Search/searchServices/indexes/documents/read"
                ],
                "notDataActions": []
            }
        ]
    }
}

  9. Selezionare Aggiungi per chiudere il riquadro.

  10. Selezionare Rivedi e crea per creare il ruolo.

    È ora possibile assegnare utenti e gruppi al ruolo. Per altre informazioni su questi passaggi, vedere Creare o aggiornare Azure ruoli personalizzati usando il portale di Azure.

Creare criteri di accesso condizionale

Se è necessario applicare criteri dell'organizzazione, ad esempio l'autenticazione a più fattori, usare Accesso condizionale di Microsoft Entra.

Per creare criteri di accesso condizionale per Azure AI Search:

  1. Accedere al portale Azure.

  2. Cerca Accesso condizionale di Microsoft Entra.

  3. Nella pagina Panoramica selezionare Crea nuovo criterio.

  4. In App o azioni cloud aggiungere Azure AI Search come app cloud, a seconda della modalità di configurazione dei criteri.

  5. Aggiorna i parametri rimanenti della tua politica. Ad esempio, specificare a quali utenti e gruppi si applicano i criteri.

  6. Salvare il criterio.

Importante

Se al servizio di ricerca è assegnata un'identità gestita, il servizio di ricerca specifico viene visualizzato come app cloud. Tuttavia, la selezione di tale servizio di ricerca specifico non applica la politica. Selezionare invece l'app cloud Azure AI Search generale per applicare i criteri di accesso condizionale al servizio di ricerca.

Risoluzione dei problemi

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

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

  • Se la richiesta include una chiave API insieme alle credenziali basate sui ruoli, il servizio esegue l'autenticazione usando la chiave. Rimuovere la chiave API dalle intestazioni della richiesta per usare l'autenticazione basata su ruoli.

  • Se il token di autorizzazione proviene da un'identità gestita e di recente sono state assegnate le autorizzazioni appropriate, l'applicazione delle assegnazioni delle autorizzazioni potrebbe richiedere diverse ore .

  • Se le query con autorizzazioni a livello di documento non restituiscono i risultati previsti, utilizzare il ruolo di Collaboratore dei dati dell'indice di ricerca o creare un ruolo personalizzato con autorizzazioni elevate per analizzare.

Passo successivo

Questo articolo illustra come assegnare ruoli per le operazioni del piano dati e di controllo su Azure AI Search. Per istruzioni complete sull'aggiunta dell'accesso basato sui ruoli al codice dell'applicazione:

Connettere l'app a Azure AI Search usando le identità

  • Last updated on