Filtri di sicurezza per tagliare i risultati di Ricerca di Intelligenza artificiale di Azure con MAzure Active Directory
Questo articolo illustra come usare le identità di sicurezza insieme ai filtri in Ricerca di intelligenza artificiale di Azure per ridurre i risultati della ricerca in base all'appartenenza ai gruppi di utenti.
Questo articolo illustra le attività seguenti:
- Creare gruppi e utenti
- Associare l'utente al gruppo creato
- Memorizzare i nuovi gruppi nella cache
- Indicizzare i documenti con i gruppi associati
- Emettere una richiesta di ricerca con il filtro degli identificatori di gruppo
Prerequisiti
L'indice in Ricerca di intelligenza artificiale di Azure deve avere un campo di sicurezza per archiviare l'elenco delle identità di gruppo che hanno accesso in lettura al documento. Questo caso d'uso presuppone una corrispondenza uno a uno tra un elemento a protezione diretta (come la domanda di iscrizione all'università di un candidato) e un campo di sicurezza che specifica chi ha accesso a tale elemento (ad esempio, il personale dell'ufficio ammissioni).
È necessario disporre delle autorizzazioni di amministratore tenant (proprietario o amministratore) per creare utenti, gruppi e associazioni.
L'applicazione deve anche essere registrata con come app multi-tenant, come descritto nella procedura seguente.
Registrare l'applicazione con Azure Active Directory
Questo passaggio integra l'applicazione con Azure Active Directory allo scopo di accettare gli accessi degli account utente e di gruppo. Se non si è un amministratore tenant nell'organizzazione, potrebbe essere necessario creare un nuovo tenant per eseguire la procedura seguente.
In portale di Azure trovare il tenant di Azure Active Directory.
A sinistra, in Gestisci selezionare Registrazioni app e quindi selezionare Nuova registrazione.
Assegnare un nome alla registrazione, ad esempio un nome simile al nome dell'applicazione di ricerca. Per informazioni su altre proprietà facoltative, vedere questo articolo.
Selezionare Registra.
Dopo aver creato la registrazione dell'app, copiare l'ID applicazione (client). Sarà necessario fornire questa stringa all'applicazione.
Se si esegue un'istruzione dettagliata di DotNetHowToSecurityTrimming, incollare questo valore nel file app.config .
Copiare l'ID directory (tenant).
A sinistra selezionare Autorizzazioni API e quindi selezionare Aggiungi un'autorizzazione.
Selezionare Microsoft Graph e quindi autorizzazioni delegate.
Cercare e quindi aggiungere le autorizzazioni delegate seguenti:
- Directory.ReadWrite.All
- Group.ReadWrite.All
- User.ReadWrite.All
Microsoft Graph fornisce un'API che consente l'accesso a livello di codice ad Azure Active Directory tramite un'API REST. Il codice di esempio per questa procedura dettagliata usa le autorizzazioni per chiamare l'API Microsoft Graph per la creazione di gruppi, utenti e associazioni. Le API vengono usate anche per memorizzare nella cache gli identificatori di gruppo per un filtraggio più rapido.
Selezionare Concedi consenso amministratore per il tenant per completare il processo di consenso.
Creare utenti e gruppi
Se si aggiunge la ricerca a un'applicazione stabilita, potrebbero essere presenti identificatori di utente e gruppo esistenti in Azure Active Directory. In questo caso è possibile ignorare i tre passaggi successivi.
Invece, se non ci sono utenti esistenti, è possibile usare le API Microsoft Graph per creare le entità di sicurezza. I frammenti di codice seguenti illustrano come generare identificatori, che diventano valori di dati per il campo di sicurezza nell'indice di Ricerca di intelligenza artificiale di Azure. Nell'ipotetica domanda di iscrizione all'università si tratterebbe degli identificatori di sicurezza per il personale dell'ufficio ammissioni.
L'appartenenza di utenti e gruppi potrebbe essere molto fluida, soprattutto nelle organizzazioni di grandi dimensioni. Il codice per la creazione delle identità di utenti e gruppi dovrebbe essere eseguito abbastanza spesso per individuare i cambiamenti intervenuti nell'appartenenza dell'organizzazione. Analogamente, l'indice di Ricerca intelligenza artificiale di Azure richiede una pianificazione di aggiornamento simile per riflettere lo stato corrente di utenti e risorse consentiti.
Passaggio 1: Creare un gruppo
private static Dictionary<Group, List<User>> CreateGroupsWithUsers(string tenant)
{
Group group = new Group()
{
DisplayName = "My First Prog Group",
SecurityEnabled = true,
MailEnabled = false,
MailNickname = "group1"
};
Passaggio 2: Creare un utente
User user1 = new User()
{
GivenName = "First User",
Surname = "User1",
MailNickname = "User1",
DisplayName = "First User",
UserPrincipalName = String.Format("user1@{0}", tenant),
PasswordProfile = new PasswordProfile() { Password = "********" },
AccountEnabled = true
};
Passaggio 3: associare utente e gruppo
List<User> users = new List<User>() { user1, user2 };
Dictionary<Group, List<User>> groups = new Dictionary<Group, List<User>>() { { group, users } };
Passaggio 4: memorizzare nella cache gli identificatori di gruppo
Facoltativamente, per ridurre la latenza di rete, è possibile memorizzare nella cache le associazioni di gruppi di utenti in modo che, quando viene eseguita una richiesta di ricerca, i gruppi vengano restituiti dalla cache, salvando un round trip. È possibile usare l'API Batch per inviare una singola richiesta HTTP con più utenti e compilare la cache.
Microsoft Graph è progettato per gestire un volume elevato di richieste. Se si verifica un numero eccessivo di richieste, la richiesta con codice di stato HTTP 429 non verrà eseguita. Per altre informazioni, vedere Microsoft Graph throttling (Limitazione delle richieste di Microsoft Graph).
Indicizzare un documento con i relativi gruppi consentiti
Le operazioni di query in Ricerca di intelligenza artificiale di Azure vengono eseguite su un indice di Ricerca di intelligenza artificiale di Azure. In questo passaggio un'operazione di indicizzazione importa i dati ricercabili in un indice, includendo gli identificatori usati come filtri di sicurezza.
Ricerca di intelligenza artificiale di Azure non autentica le identità utente o fornisce logica per stabilire il contenuto che un utente ha l'autorizzazione per visualizzare. Il caso d'uso per la limitazione per motivi di sicurezza presuppone che venga fornita l'associazione tra un documento riservato e l'identificatore di gruppo che ha accesso a tale documento, importata intatta in un indice di ricerca.
Nell'esempio ipotetico, il corpo della richiesta PUT in un indice di Ricerca di intelligenza artificiale di Azure includerà il saggio o la trascrizione di un richiedente insieme all'identificatore del gruppo che dispone dell'autorizzazione per visualizzare il contenuto.
Nell'esempio generico usato nel codice di esempio per questa procedura dettagliata l'operazione relativa all'indice potrebbe avere l'aspetto seguente:
private static void IndexDocuments(string indexName, List<string> groups)
{
IndexDocumentsBatch<SecuredFiles> batch = IndexDocumentsBatch.Create(
IndexDocumentsAction.Upload(
new SecuredFiles()
{
FileId = "1",
Name = "secured_file_a",
GroupIds = new[] { groups[0] }
}),
...
};
IndexDocumentsResult result = searchClient.IndexDocuments(batch);
Emettere una richiesta di ricerca
A scopo di limitazione per motivi di sicurezza, i valori nel campo di sicurezza nell'indice sono valori statici, usati per includere o escludere i documenti nei risultati della ricerca. Ad esempio, se l'identificatore di gruppo per le ammissione è "A11B22C33D44-E55F66G77-H88I99JKK", tutti i documenti in un indice di Ricerca intelligenza artificiale di Azure con tale identificatore nel campo di sicurezza vengono inclusi (o esclusi) nei risultati della ricerca inviati al chiamante.
Per filtrare i documenti restituiti nei risultati della ricerca in base ai gruppi dell'utente che ha emesso la richiesta, esaminare i passaggi seguenti.
Passaggio 1: recuperare gli identificatori di gruppo dell'utente
Se i gruppi dell'utente non sono già stati memorizzati nella cache o la cache è scaduta, eseguire la richiesta dei gruppi .
private static async void RefreshCache(IEnumerable<User> users)
{
HttpClient client = new HttpClient();
var userGroups = await _microsoftGraphHelper.GetGroupsForUsers(client, users);
_groupsCache = new ConcurrentDictionary<string, List<string>>(userGroups);
}
Passaggio 2: comporre la richiesta di ricerca
Presupponendo che si disponga dell'appartenenza ai gruppi dell'utente, è possibile emettere la richiesta di ricerca con i valori di filtro appropriati.
private static void SearchQueryWithFilter(string user)
{
// Using the filter below, the search result will contain all documents that their GroupIds field
// contain any one of the Ids in the groups list
string filter = String.Format("groupIds/any(p:search.in(p, '{0}'))", string.Join(",", String.Join(",", _groupsCache[user])));
SearchOptions searchOptions =
new SearchOptions()
{
Filter = filter
};
searchOptions.Select.Add("name");
SearchResults<SecuredFiles> results = searchClient.Search<SecuredFiles>("*", searchOptions);
Console.WriteLine("Results for groups '{0}' : {1}", _groupsCache[user], results.GetResults().Select(r => r.Document.Name));
}
Passaggio 3: gestire i risultati
La risposta include un elenco filtrato dei documenti, costituito da quelli che l'utente è autorizzato a visualizzare. A seconda di come viene creata la pagina dei risultati della ricerca, potrebbero essere inclusi segnali visivi per riflettere il set di risultati filtrato.
Risultati
In questa procedura dettagliata si è appreso un modello per l'uso degli accessi utente per filtrare i documenti nei risultati di Ricerca di intelligenza artificiale di Azure, tagliando i risultati dei documenti che non corrispondono al filtro fornito nella richiesta.