Auktorisera åtkomst till en sökapp med hjälp av Microsoft Entra-ID

  • Artikel

Sökprogram som bygger på Azure AI Search kan nu använda Microsofts identitetsplattform för autentiserad och auktoriserad åtkomst. I Azure är identitetsprovidern Microsoft Entra-ID. En viktig fördel med att använda Microsoft Entra-ID är att dina autentiseringsuppgifter och API-nycklar inte längre behöver lagras i koden. Microsoft Entra autentiserar säkerhetsobjektet (en användare, grupp eller tjänst) som kör programmet. Om autentiseringen lyckas returnerar Microsoft Entra-ID:t åtkomsttoken till programmet och programmet kan sedan använda åtkomsttoken för att auktorisera begäranden till Azure AI Search.

Den här artikeln visar hur du konfigurerar klienten för Microsoft Entra-ID:

  • För autentisering skapar du en hanterad identitet som säkerhetsprincip. Du kan också använda en annan typ av objekt för tjänstens huvudnamn, men den här artikeln använder hanterade identiteter eftersom de eliminerar behovet av att hantera autentiseringsuppgifter.

  • För auktorisering tilldelar du en Azure-roll till den hanterade identiteten som ger behörighet att köra frågor eller hantera indexeringsjobb.

  • Uppdatera klientkoden för att anropa TokenCredential(). Du kan till exempel komma igång med nya SearchClient(endpoint, new DefaultAzureCredential()) för att autentisera via ett Microsoft Entra-ID med hjälp av Azure.Identity.

Konfigurera rollbaserad åtkomst för dataplan

Gäller för: Search Index Data Contributor, Search Index Data Reader, Search Service Contributor

I det här steget konfigurerar du söktjänsten för att identifiera ett auktoriseringshuvud på databegäranden som tillhandahåller en OAuth2-åtkomsttoken.

  1. Logga in på Azure-portalen och öppna söktjänstsidan.

  2. Välj Nycklar i det vänstra navigeringsfönstret.

    Screenshot of the keys page with authentication options.

  3. Välj ett alternativ för API-åtkomstkontroll . Vi rekommenderar båda om du vill ha flexibilitet eller om du behöver migrera appar.

    Alternativ Description
    API-nyckel (standard) Kräver en administratör eller fråga API-nycklar i begärandehuvudet för auktorisering. Inga roller används.
    Rollbaserad åtkomstkontroll Kräver medlemskap i en rolltilldelning för att slutföra uppgiften, som beskrivs i nästa steg. Det kräver också ett auktoriseringshuvud.
    Båda Begäranden är giltiga med antingen en API-nyckel eller rollbaserad åtkomstkontroll.

Ändringen träder i kraft omedelbart, men vänta några sekunder innan du testar.

Alla nätverksanrop för söktjänståtgärder och innehåll respekterar det alternativ du väljer: API-nycklar, ägartoken eller någon av dem om du väljer Båda.

När du aktiverar rollbaserad åtkomstkontroll i portalen blir felläget "http401WithBearerChallenge" om auktoriseringen misslyckas.

Skapa en hanterad identitet

I det här steget skapar du en hanterad identitet för klientprogrammet.

  1. Logga in på Azure-portalen.

  2. Sök efter hanterade identiteter.

  3. Välj + Skapa.

  4. Ge din hanterade identitet ett namn och välj en region. Välj sedan Skapa.

    Screenshot of the Create Managed Identity wizard.

Tilldela en roll till den hanterade identiteten

Därefter måste du ge din hanterade identitet åtkomst till söktjänsten. Azure AI Search har olika inbyggda roller. Du kan också skapa en anpassad roll.

Det är en bra idé att bevilja minimibehörigheter. Om ditt program bara behöver hantera frågor bör du tilldela rollen Dataläsare för sökindex. Om den behöver både läs- och skrivåtkomst i ett sökindex bör du också använda rollen Search Index Data Contributor( Search Index Data Contributor ).

  1. Logga in på Azure-portalen.

  2. Gå till söktjänsten.

  3. Välj Åtkomstkontroll (IAM) i det vänstra navigeringsfönstret.

  4. Välj + Lägg till>Lägg till rolltilldelning.

    Screenshot of Access control (IAM) page with Add role assignment menu open.

  5. Välj en tillämplig roll:

    • Ägare
    • Deltagare
    • Läsare
    • Söktjänstdeltagare
    • Search Index Data Contributor
    • Dataläsare för sökindex

    Mer information om tillgängliga roller finns i Inbyggda roller som används i Sök.

    Kommentar

    Rollerna Ägare, Deltagare, Läsare och Söktjänstdeltagare ger dig inte åtkomst till data i ett sökindex, så du kan inte köra frågor mot ett sökindex eller indexdata med hjälp av dessa roller. För dataåtkomst till ett sökindex behöver du antingen rollen Search Index Data Contributor eller Search Index Data Reader.

  6. På fliken Medlemmar väljer du den hanterade identitet som du vill ge åtkomst till din söktjänst.

  7. På fliken Granska + tilldela väljer du Granska + tilldela för att tilldela rollen.

Du kan tilldela flera roller, till exempel Search Service-deltagare och Search Index Data Contributor, om ditt program behöver omfattande åtkomst till söktjänster, objekt och innehåll.

Du kan också tilldela roller med hjälp av PowerShell.

Konfigurera Microsoft Entra-autentisering i klienten

När du har en hanterad identitet och en rolltilldelning i söktjänsten är du redo att lägga till kod i ditt program för att autentisera säkerhetsobjektet och hämta en OAuth 2.0-token.

Använd följande klientbibliotek för rollbaserad åtkomstkontroll:

Kommentar

Mer information om det OAuth 2.0-kodbidragsflöde som används av Microsoft Entra-ID finns i Auktorisera åtkomst till Microsoft Entra-webbprogram med hjälp av OAuth 2.0-kodbidragsflödet.

Följande instruktioner refererar till ett befintligt C#-exempel för att demonstrera kodändringarna.

  1. Som utgångspunkt klonar du källkoden för C#-avsnittet i Snabbstart: Fulltextsökning med hjälp av Azure SDK:er.

    Exemplet använder för närvarande nyckelbaserad autentisering och AzureKeyCredential för att skapa SearchClient och SearchIndexClient men du kan göra en liten ändring för att växla över till rollbaserad autentisering.

  2. Uppdatera NuGet-paketet för Azure.Search.Documents till version 11.4 eller senare.

  3. Importera Azure.Identity-biblioteket för att få åtkomst till andra autentiseringstekniker.

  4. I stället för att använda AzureKeyCredential i början av Main() i Program.cs använder du DefaultAzureCredential som i kodfragmentet nedan:

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

Lokal testning

Användartilldelade hanterade identiteter fungerar endast i Azure-miljöer. Om du kör den här koden lokalt DefaultAzureCredential återgår du till att autentisera med dina autentiseringsuppgifter. Se till att du även har gett dig själv den åtkomst som krävs till söktjänsten om du planerar att köra koden lokalt.

  1. Kontrollera att ditt konto har rolltilldelningar för att köra alla åtgärder i snabbstartsexemplet. För att både skapa och fråga ett index behöver du "Search Index Data Reader" och "Search Index Data Contributor".

  2. Gå till VerktygSalternativ>>Azure Service Authentication för att välja ditt Azure-inloggningskonto.

Nu bör du kunna köra projektet från Visual Studio i ditt lokala system med hjälp av rollbaserad åtkomstkontroll för auktorisering.

Kommentar

Dokumentationen om Azure.Identity innehåller mer information om DefaultAzureCredential och användning av Microsoft Entra-autentisering med Azure SDK för .NET. DefaultAzureCredential är avsedd att förenkla komma igång med SDK genom att hantera vanliga scenarier med rimliga standardbeteenden. Utvecklare som vill ha mer kontroll eller vars scenario inte hanteras av standardinställningarna bör använda andra typer av autentiseringsuppgifter.

Se även