Usare i controlli degli accessi in base al ruolo di Azure in Ricerca cognitiva di Azure

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

  • Usare i ruoli disponibili a livello generale per l'amministrazione del servizio.

  • Usare nuovi ruoli di anteprima per le richieste di dati, tra cui la creazione, il caricamento e l'esecuzione di query sugli indici.

L'accesso per utente ai risultati della ricerca (talvolta definito sicurezza a livello di riga o sicurezza a livello di documento) non è supportato. 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.

I ruoli predefiniti includono ruoli disponibili a livello generale e di anteprima. Se questi ruoli non sono sufficienti, creare invece un ruolo personalizzato .

Ruolo Descrizione e disponibilità
Proprietario (disponibile a livello generale) Accesso completo alla risorsa di ricerca, inclusa la possibilità di assegnare ruoli di Azure. Gli amministratori delle sottoscrizioni sono membri per impostazione predefinita.

(Anteprima) Questo ruolo ha lo stesso accesso del ruolo Collaboratore servizio di ricerca nel piano dati. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query nell'indice di ricerca o nei documenti di indice.
Collaboratore (disponibile a livello generale) Stesso livello di accesso del proprietario, meno la possibilità di assegnare ruoli o modificare le opzioni di autorizzazione.

(Anteprima) Questo ruolo ha lo stesso accesso del ruolo Collaboratore servizio di ricerca nel piano dati. Include l'accesso a tutte le azioni del piano dati, ad eccezione della possibilità di eseguire query nell'indice di ricerca o nei documenti di indice.
Lettore (disponibile a livello generale) Accesso limitato alle informazioni parziali del servizio. Nel portale il ruolo Lettore può accedere alle informazioni nella pagina Panoramica del servizio, nella sezione Informazioni di base e nella scheda Monitoraggio. Tutte le altre schede e pagine non sono limitate.

Questo ruolo ha accesso alle informazioni sul servizio: nome del servizio, gruppo di risorse, stato del servizio, posizione, nome sottoscrizione e ID, tag, URL, piano tariffario, repliche, partizioni e unità di ricerca. Questo ruolo ha anche accesso alle metriche del servizio: latenza di ricerca, percentuale di richieste limitate, query medie al secondo.

Questo ruolo non consente l'accesso a chiavi API, assegnazioni di ruolo, contenuto (indici o mappe sinonimi) o metriche del contenuto (spazio di archiviazione utilizzato, numero di oggetti).
Collaboratore servizi di ricerca (disponibile a livello generale) Questo ruolo è identico al ruolo Collaboratore e si applica alle operazioni del piano di controllo.

(Anteprima) Quando si abilita l'anteprima del controllo degli accessi in base al ruolo per il piano dati, questo ruolo fornisce anche l'accesso completo a tutte le azioni del piano dati su indici, mappe sinonimiche, indicizzatori, origini dati e set di competenze definiti da Microsoft.Search/searchServices/*. Questo ruolo non consente di accedere agli indici di ricerca di query o ai documenti di indice. Questo ruolo è destinato agli amministratori del servizio di ricerca che devono gestire il servizio di ricerca e i relativi oggetti, ma senza la possibilità di visualizzare o accedere ai dati degli oggetti.

Come Collaboratore, i membri di questo ruolo non possono effettuare o gestire assegnazioni di ruolo o modificare le opzioni di autorizzazione. Per usare le funzionalità di anteprima di questo ruolo, il servizio deve avere la funzionalità di anteprima abilitata, come descritto in questo articolo.
Collaboratore ai dati dell'indice di ricerca (Anteprima) Fornisce l'accesso completo al piano dati al contenuto in tutti gli indici nel servizio di ricerca. Questo ruolo è destinato agli sviluppatori o ai proprietari di indici che devono importare, aggiornare o eseguire query sulla raccolta documenti di un indice.
Lettore di dati dell'indice di ricerca (Anteprima) Fornisce l'accesso al piano dati di sola lettura per gli indici di ricerca nel servizio di ricerca. Questo ruolo è destinato ad app e utenti che eseguono query.

Nota

Le risorse di Azure hanno il concetto di piano di controllo e categorie di operazioni del piano dati. In Ricerca cognitiva "piano di controllo" si riferisce a qualsiasi operazione supportata nell'API REST di gestione o nelle librerie client equivalenti. Il "piano dati" fa riferimento alle 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.

Funzionalità e limitazioni in anteprima

  • Il controllo degli accessi in base al ruolo per le operazioni del piano dati, ad esempio la creazione di un indice o l'esecuzione di query su un indice, è attualmente disponibile in anteprima pubblica e disponibile in condizioni supplementari per l'utilizzo.

  • Non esistono restrizioni a livello di area, piano o prezzi per l'uso dell'anteprima del controllo degli accessi in base al ruolo di Azure, ma il servizio di ricerca deve trovarsi nel cloud pubblico di Azure. L'anteprima non è disponibile in Azure per enti pubblici, Azure Germania o Azure China 21Vianet.

  • Se si esegue la migrazione della sottoscrizione di Azure a un nuovo tenant, sarà necessario riabilitare l'anteprima del controllo degli accessi in base al ruolo.

  • L'adozione del controllo degli accessi in base al ruolo di Azure potrebbe aumentare la latenza di alcune richieste. Ogni combinazione univoca di risorsa del servizio (indice, indicizzatore e così via) e l'entità servizio usata in una richiesta attiverà un controllo di autorizzazione. Questi controlli di autorizzazione possono aggiungere fino a 200 millisecondi di latenza a una 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 la limitazione delle richieste. La limitazione si verifica solo se centinaia di combinazioni univoche di risorse del servizio di ricerca e entità servizio sono state usate entro un secondo.

Iscriversi per l'anteprima

Si applica a: Collaboratore ai dati dell'indice di ricerca, Lettore dati indice di ricerca, Collaboratore servizio di ricerca

I nuovi ruoli di anteprima predefiniti concedono autorizzazioni sul contenuto nel servizio di ricerca. Anche se i ruoli predefiniti sono sempre visibili nella portale di Azure, è necessaria la registrazione in anteprima per renderli operativi.

  1. Aprire portale di Azure e trovare il servizio di ricerca.

  2. Nel riquadro di spostamento a sinistra selezionare Chiavi.

  3. Nel banner blu che indica l'anteprima selezionare Registra per aggiungere la funzionalità alla sottoscrizione.

    screenshot di come iscriversi all'anteprima del controllo degli accessi in base al ruolo nel portale

È anche possibile iscriversi all'anteprima usando Il controllo dell'esposizione delle funzionalità di Azure (AFEC) e cercare i Controllo di accesso basati sui ruoli per il servizio di ricerca (anteprima). Per altre informazioni sull'aggiunta di funzionalità di anteprima, vedere Configurare le funzionalità di anteprima nella sottoscrizione di Azure.

Nota

Dopo aver aggiunto l'anteprima alla sottoscrizione, tutti i servizi nella sottoscrizione verranno registrati in modo permanente nell'anteprima. Se non si vuole il controllo degli accessi in base al ruolo in un determinato servizio, è possibile disabilitare il controllo degli accessi in base al ruolo per le operazioni del piano dati, come descritto in una sezione successiva.

Abilitare l'anteprima del controllo degli accessi in base al ruolo per le operazioni del piano dati

Si applica a: Collaboratore ai dati dell'indice di ricerca, Lettore dati indice di ricerca, Collaboratore servizio di ricerca

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

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

  2. Selezionare Chiavi nel riquadro di spostamento a sinistra.

  3. Scegliere un meccanismo di controllo di accesso api .

    Opzione Stato Descrizione
    Chiave API Disponibile a livello generale (impostazione predefinita) Richiede un amministratore o eseguire query sulle chiavi API nell'intestazione della richiesta per l'autorizzazione. Non vengono usati ruoli.
    Controllo degli accessi in base al ruolo Anteprima Richiede l'appartenenza a un'assegnazione di ruolo per completare l'attività, descritta nel passaggio successivo. Richiede anche un'intestazione di autorizzazione. La scelta di questa opzione limita i client che supportano l'API REST 2021-04-30-preview.
    Entrambi Anteprima Le richieste sono valide usando una chiave API o un token di autorizzazione.

Se non è possibile salvare la selezione o se viene visualizzato il messaggio "Controllo di accesso ALL'API non è riuscito ad aggiornare per il servizio <name>di ricerca . DisableLocalAuth è in anteprima e non è abilitato per questa sottoscrizione", la registrazione della sottoscrizione non è stata avviata o non è stata elaborata.

Assegnare ruoli

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

È necessario essere proprietario o disporre di autorizzazioni Microsoft.Authorization/roleAssignments/write per gestire le assegnazioni di ruolo.

Le assegnazioni di ruolo nel portale sono a livello di servizio. Se si desidera concedere le autorizzazioni a un singolo indice, usare PowerShell o l'interfaccia della riga di comando di Azure.

  1. Aprire il 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.

    Pagina Controllo di accesso (IAM) con Il menu Aggiungi assegnazione ruolo aperto.

  5. Selezionare un ruolo applicabile:

    • Proprietario
    • Collaboratore
    • Reader
    • Collaboratore del servizio di ricerca (anteprima per le richieste del piano dati)
    • Collaboratore ai dati dell'indice di ricerca (anteprima)
    • Lettore dati indice di ricerca (anteprima)
  6. Nella scheda Membri selezionare l'identità utente o gruppo di Azure AD.

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

Testare le assegnazioni di ruolo

  1. Aprire il portale di Azure.

  2. Passare al servizio di ricerca.

  3. Nella pagina Panoramica selezionare la scheda Indici :

    • I membri di Search Index Data Reader possono usare Esplora ricerche per eseguire query sull'indice. È possibile usare qualsiasi versione dell'API per verificare l'accesso. È consigliabile eseguire query e visualizzare i risultati, ma non è consigliabile visualizzare la definizione dell'indice.

    • I membri del collaboratore dei dati dell'indice di ricerca possono selezionare Nuovo indice per creare un nuovo indice. Il salvataggio di un nuovo indice verificherà l'accesso in scrittura nel servizio.

Concedere l'accesso a un singolo indice

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

Il portale non supporta attualmente 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, fornendo il nome utente o il gruppo di Azure e l'ambito dell'assegnazione.

  1. Caricare i moduli Azure e AzureAD e 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 Search Index Data Reader 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.

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 gli indici di elenco in base al nome. In genere, gli indici di elenco sono considerati 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 un altro ruolo) e selezionare Clona per aprire la creazione guidata di un ruolo personalizzato .

  5. Nella scheda Nozioni di base specificare un nome per il ruolo personalizzato, ad esempio "Indice di ricerca Esplora dati" e quindi fare clic su Avanti.

  6. Nella scheda Autorizzazioni selezionare Aggiungi autorizzazione.

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

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

    • In Microsoft.Search/operations selezionare Lettura: elencare tutte le operazioni disponibili.
    • In Microsoft.Search/searchServices/indexes selezionare Lettura : Lettura indice.
  9. Nella stessa pagina passare a Azioni dati e in Microsoft.Search/searchServices/indexes/documents selezionare Leggi : Leggi documenti.

    La definizione JSON è simile all'esempio seguente:

    {
     "properties": {
         "roleName": "search index data explorer",
         "description": "",
         "assignableScopes": [
             "/subscriptions/a5b1ca8b-bab3-4c26-aebe-4cf7ec4791a0/resourceGroups/heidist-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.

Disabilitare l'autenticazione della chiave API

Le chiavi API non possono essere eliminate, ma possono essere disabilitate nel servizio. Se si usano i ruoli di anteprima Collaboratore del servizio di ricerca, Collaboratore ai dati dell'indice di ricerca e Lettore di dati dell'indice di ricerca e autenticazione di Azure AD, è possibile disabilitare le chiavi API, in modo che il servizio di ricerca rifiuti tutte le richieste correlate ai dati che passano una chiave API nell'intestazione per le richieste correlate al contenuto.

Per disabilitare l'autenticazione basata su chiave, usare l'API REST di gestione versione 2021-04-01-Preview e inviare due richieste consecutive per il servizio di aggiornamento.

Le autorizzazioni di proprietario o collaboratore sono necessarie per disabilitare le funzionalità. Usare Postman o un altro strumento di test Web per completare i passaggi seguenti (vedere suggerimento di seguito):

  1. Nella prima richiesta impostare "AuthOptions" su "aadOrApiKey" per abilitare l'autenticazione di Azure AD. Si noti che l'opzione indica la disponibilità di un approccio: Azure AD o le chiavi API native.

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
    {
      "location": "{{region}}",
      "sku": {
        "name": "standard"
      },
      "properties": {
        "authOptions": {
          "aadOrApiKey": {
            "aadAuthFailureMode": "http401WithBearerChallenge"
          }
        }
      }
    }
    
  2. Nella seconda richiesta impostare "disableLocalAuth" su true. Questo passaggio disattiva la parte della chiave API dell'opzione "aadOrApiKey", lasciando solo l'autenticazione di Azure AD.

    PUT https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2021-04-01-Preview
    {
      "location": "{{region}}",
      "sku": {
        "name": "standard"
      },
      "properties": {
        "disableLocalAuth": true
      }
    }
    

Non è possibile combinare i passaggi uno e due. Nel passaggio 1, "disableLocalAuth" deve essere false per soddisfare i requisiti per l'impostazione di "AuthOptions", mentre il passaggio due modifica tale valore su true.

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

Suggerimento

Le chiamate API REST di gestione vengono autenticate tramite Azure Active Directory. Per indicazioni sulla configurazione di un'entità di sicurezza e una richiesta, vedere questo post di blog sulle API REST di Azure con Postman (2021). L'esempio precedente è stato testato usando le istruzioni e la raccolta Postman fornita nel post di blog.

Accesso condizionale

L'accesso condizionale è uno strumento in Azure Active Directory usato per applicare i criteri dell'organizzazione. Usando i criteri di accesso condizionale, è possibile applicare i controlli di accesso corretti quando necessario per proteggere l'organizzazione. Quando si accede a un servizio di Ricerca cognitiva di Azure tramite il controllo degli accessi in base al ruolo, l'accesso condizionale può applicare i criteri dell'organizzazione.

Per abilitare i criteri di accesso condizionale per Ricerca cognitiva di Azure, seguire questa procedura:

  1. Accedere al portale di Azure.

  2. Cercare l'accesso condizionale di Azure AD.

  3. Selezionare Criteri.

  4. Selezionare + Nuovi criteri.

  5. Nella sezione App cloud o azioni dei criteri aggiungere Ricerca cognitiva 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 Ricerca cognitiva di Azure cloud generale.