Toegang tot een zoek-app autoriseren met behulp van Microsoft Entra-id

Artikel
04/27/2024

Zoektoepassingen die zijn gebouwd op Azure AI Search kunnen nu gebruikmaken van het Microsoft Identity Platform voor geverifieerde en geautoriseerde toegang. In Azure is de id-provider Microsoft Entra-id. Een belangrijk voordeel van het gebruik van Microsoft Entra-id is dat uw referenties en API-sleutels niet meer hoeven te worden opgeslagen in uw code. Microsoft Entra verifieert de beveiligingsprincipaal (een gebruiker, groep of service) die de toepassing uitvoert. Als de verificatie slaagt, retourneert Microsoft Entra ID het toegangstoken voor de toepassing en kan de toepassing vervolgens het toegangstoken gebruiken om aanvragen voor Azure AI Search te autoriseren.

In dit artikel leest u hoe u uw client configureert voor Microsoft Entra-id:

Maak voor verificatie een beheerde identiteit voor uw toepassing. U kunt een ander type beveiligingsprincipaalobject gebruiken, maar in dit artikel worden beheerde identiteiten gebruikt, omdat er geen referenties meer nodig zijn.
Wijs voor autorisatie een Azure-rol toe aan de beheerde identiteit die machtigingen verleent voor het uitvoeren van query's of het beheren van indexeringstaken.
Werk uw clientcode bij om aan te roepen TokenCredential(). U kunt bijvoorbeeld aan de slag met nieuwe SearchClient(eindpunt, nieuw DefaultAzureCredential()) om te verifiëren via een Microsoft Entra-id met behulp van Azure.Identity.

Op rollen gebaseerde toegang configureren voor het gegevensvlak

Van toepassing op: Inzender voor zoekindexgegevens, Zoekindexgegevenslezer, Inzender voor zoekservice

In deze stap configureert u uw zoekservice voor het herkennen van een autorisatieheader voor gegevensaanvragen die een OAuth2-toegangstoken bieden.

Azure-portal
REST API

Meld u aan bij Azure Portal en open de zoekservicepagina.
Selecteer Sleutels in het linkernavigatiedeelvenster.

Kies een optie voor API-toegangsbeheer . We raden beide aan als u flexibiliteit wilt of apps wilt migreren.

Optie	Omschrijving
API-sleutel	(standaard) Vereist een beheerder of query-API-sleutels in de aanvraagheader voor autorisatie. Er worden geen rollen gebruikt.
Op rollen gebaseerd toegangsbeheer	Vereist dat u lid bent van een roltoewijzing om de taak te voltooien, zoals beschreven in de volgende stap. Er is ook een autorisatieheader vereist.
Beide	Aanvragen zijn geldig met behulp van een API-sleutel of op rollen gebaseerd toegangsbeheer.

De wijziging is onmiddellijk van kracht, maar wacht enkele seconden voordat u gaat testen.

Alle netwerkoproepen voor zoekservicebewerkingen en -inhoud respecteren de optie die u selecteert: API-sleutels, bearer-token of een van beide als u Beide selecteert.

Wanneer u op rollen gebaseerd toegangsbeheer inschakelt in de portal, is de foutmodus http401WithBearerChallenge als de autorisatie mislukt.

Gebruik de Beheer REST API Create of Update Service om uw service te configureren.

Alle aanroepen naar de REST API van Management worden geverifieerd via Microsoft Entra-id, met machtigingen voor inzender of eigenaar. Zie Azure AI Search beheren met REST voor hulp bij het instellen van geverifieerde aanvragen in een REST-client.

Service-instellingen ophalen zodat u de huidige configuratie kunt controleren.

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

Gebruik PATCH om de serviceconfiguratie bij te werken. Met de volgende wijzigingen zijn zowel sleutels als op rollen gebaseerd toegang mogelijk. Zie API-sleutels uitschakelen als u een configuratie met alleen rollen wilt.

Stel onder 'properties' 'authOptions' in op aadOrApiKey. De eigenschap disableLocalAuth moet onwaar zijn om 'authOptions' in te stellen.

Stel desgewenst 'aadAuthFailureMode' in om op te geven of 401 wordt geretourneerd in plaats van 403 wanneer de verificatie mislukt. Geldige waarden zijn http401WithBearerChallenge of 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"
            }
        }
    }
}
```

Een beheerde identiteit maken

In deze stap maakt u een beheerde identiteit voor uw clienttoepassing.

Meld u aan bij het Azure-portaal.
Zoek naar beheerde identiteiten.
Selecteer Maken.
Geef uw beheerde identiteit een naam en selecteer een regio. Ten slotte selecteert u Maken.

Een rol toewijzen aan de beheerde identiteit

Vervolgens moet u de beheerde identiteit van uw client toegang verlenen tot uw zoekservice. Azure AI Search heeft verschillende ingebouwde rollen. U kunt ook een aangepaste rol maken.

Het is een best practice om minimale machtigingen te verlenen. Als uw toepassing alleen query's hoeft te verwerken, moet u de rol Search Index Data Reader toewijzen. Als de client zowel lees- als schrijftoegang nodig heeft voor een zoekindex, moet u de rol Inzender voor zoekindexgegevens gebruiken.

Meld u aan bij het Azure-portaal.
Navigeer naar uw zoekservice.
Selecteer Toegangsbeheer (IAM) in het linkernavigatiedeelvenster.
Selecteer + Toevoegen>Roltoewijzing toevoegen.
Selecteer een toepasselijke rol:
- Eigenaar
- Inzender
- Lezer
- Inzender voor zoekservice
- Inzender voor zoekindexgegevens
- Zoekindexgegevenslezer
  
  Notitie
  
  De rol Eigenaar, Inzender, Lezer en Zoekservicebijdrager zijn besturingsvlakrollen en bieden u geen toegang tot de gegevens in een zoekindex. Voor gegevenstoegang kiest u de rol Inzender voor zoekindexgegevens of de rol Lezer van zoekindexgegevens. Zie ingebouwde rollen die worden gebruikt in Search voor meer informatie over het bereik en doel van elke rol.
Selecteer op het tabblad Leden de beheerde identiteit die u toegang wilt geven tot uw zoekservice.
Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

U kunt meerdere rollen, zoals Inzender voor zoekservice en Inzender voor zoekindexgegevens, toewijzen als uw toepassing uitgebreide toegang nodig heeft tot de zoekservices, objecten en inhoud.

U kunt ook rollen toewijzen met behulp van PowerShell.

Microsoft Entra-verificatie instellen in uw client

Zodra u een beheerde identiteit en een roltoewijzing voor de zoekservice hebt, kunt u code toevoegen aan uw toepassing om de beveiligingsprincipaal te verifiëren en een OAuth 2.0-token te verkrijgen.

Gebruik de volgende clientbibliotheken voor op rollen gebaseerd toegangsbeheer:

Notitie

Zie Toegang verlenen tot Microsoft Entra-webtoepassingen autoriseren met behulp van de OAuth 2.0-codetoezengelingsstroom voor meer informatie over de stroom voor het verlenen van OAuth 2.0-code die wordt gebruikt door Microsoft Entra-id.

.NET SDK
REST API

De volgende instructies verwijzen naar een bestaand C#-voorbeeld om de codewijzigingen te demonstreren.

Kloon als uitgangspunt de broncode voor de C#-sectie van quickstart: Zoeken in volledige tekst met behulp van de Azure SDK's.

Het voorbeeld maakt momenteel gebruik van verificatie op basis van sleutels en het AzureKeyCredential maken van de SearchClient verificatie, SearchIndexClient maar u kunt een kleine wijziging aanbrengen om over te schakelen naar verificatie op basis van rollen.
Werk het NuGet-pakket Azure.Search.Documents bij naar versie 11.4 of hoger.
Importeer de Azure.Identity-bibliotheek om toegang te krijgen tot andere verificatietechnieken.

Gebruik in plaats van AzureKeyCredential in het begin van Main()Program.cs, DefaultAzureCredential zoals in het onderstaande codefragment:

// 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());

Lokaal testen

Door de gebruiker toegewezen beheerde identiteiten werken alleen in Azure-omgevingen. Als u deze code lokaal uitvoert, DefaultAzureCredential valt u terug op verificatie met uw referenties. Zorg ervoor dat u uzelf de vereiste toegang geeft tot de zoekservice als u van plan bent om de code lokaal uit te voeren.

Controleer of uw account roltoewijzingen heeft om alle bewerkingen in het quickstart-voorbeeld uit te voeren. Als u een index wilt maken en er query's op wilt uitvoeren, gebruikt u 'Search Index Data Reader' en 'Search Index Data Contributor'.
Ga naar Extra>Opties>voor Azure Service Authentication om uw Azure-aanmeldingsaccount te kiezen.

U moet nu het project vanuit Visual Studio op uw lokale systeem kunnen uitvoeren met behulp van op rollen gebaseerd toegangsbeheer voor autorisatie.

Notitie

De documentatie over Azure.Identity bevat meer informatie over DefaultAzureCredential en het gebruik van Microsoft Entra-verificatie met de Azure SDK voor .NET. DefaultAzureCredential is bedoeld om aan de slag te gaan met de SDK te vereenvoudigen door veelvoorkomende scenario's met redelijk standaardgedrag te verwerken. Ontwikkelaars die meer controle willen of waarvan het scenario niet wordt geleverd door de standaardinstellingen, moeten andere referentietypen gebruiken.

Het gebruik van een Azure SDK vereenvoudigt de OAuth 2.0-stroom, maar u kunt ook rechtstreeks programmeren op basis van het protocol in uw toepassing. Volledige details zijn beschikbaar in het Microsoft Identity Platform en de OAuth 2.0-clientreferentiestroom.

Begin met het ophalen van een token van het Microsoft Identity Platform:

POST /[tenant id]/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=[client id]
&scope=https%3A%2F%2Fsearch.azure.com%2F.default
&client_secret=[client secret]
&grant_type=client_credentials

Het vereiste bereik is 'https://search.azure.com/.default".

Nu u een token hebt, kunt u een aanvraag indienen bij de zoekservice.

GET https://[service name].search.windows.net/indexes/[index name]/docs?[query parameters]
Content-Type: application/json   
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...