Verbinding maken met Azure AI Zoeken met behulp van rollen

Notitie

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Azure AI Zoeken ondersteunt toegangsbeheer via Microsoft Entra ID. Op rollen gebaseerde toegang is optioneel, maar wordt aanbevolen. Het alternatief is verificatie op basis van sleutels. Dit is de standaardinstelling.

Als u meerdere rollen aan een beveiligingsprincipaal toewijst, worden machtigingen gecombineerd. Roltoewijzingen zijn van toepassing op alle hulpprogramma's en clientbibliotheken.

In dit artikel wordt uitgelegd hoe u ingebouwde rollen toewijst voor servicebeheer, ontwikkeling en alleen-lezen toegang voor query's en ophalen. Het biedt ook stappen voor het maken van aangepaste rollen en het testen van roltoewijzingen.

Aanbeveling

Vereisten

Ingebouwde rollen

Rollen zijn een verzameling machtigingen die van invloed zijn op het besturingsvlak of het gegevensvlak:

  • Besturingsvlak: Bewerkingen voor het inrichten, configureren en beheren van services. Besturingsvlakbewerkingen omvatten het maken of verwijderen van zoekservices, het weergeven van API-sleutels en het beheren van netwerk- en verificatie-instellingen. Beschikbaar via de Azure Resource Manager REST API's, Search Management REST API's en equivalente Azure SDK clientbibliotheken.

  • Gegevensvlak: Bewerkingen tegen het eindpunt van de zoekservice. Gegevensvlakbewerkingen worden onderverdeeld in twee categorieën: objectbeheer en toegang tot inhoud. Beschikbaar via de Search Service REST API's en equivalente Azure SDK-clientbibliotheken.

Beschrijvingen van rollen

De volgende ingebouwde rollen verlenen machtigingen aan Azure AI Zoeken. Rollen in het besturingsvlak zijn altijd beschikbaar, terwijl toegang op basis van rollen moet worden ingeschakeld voor gegevensvlakrollen op uw zoekservice. U kunt ingebouwde rollen combineren voor bredere toegang of een aangepaste rol maken met de specifieke machtigingen die u nodig hebt.

Rol Vliegtuig Beschrijving
Eigenaar Beheersen
  • Volledige toegang tot het besturingsvlak, inclusief de mogelijkheid om rollen toe te wijzen en verificatie-instellingen te wijzigen.
  • Abonnementsbeheerders hebben deze rol standaard.
  • Kan API-sleutels beheren.
  • Kan geen zoekobjecten maken, geen documenten laden, geen query-indexen uitvoeren of gegevens ophalen uit kennisbanken.
Inzender Beheersen
  • Hetzelfde niveau van toegang tot het besturingsvlak als eigenaar, minus de mogelijkheid om rollen toe te wijzen.
Lezer Beheersen
  • Alleen-lezen toegang tot het controlevlak.
  • Kan metrische servicegegevens en objectdefinities weergeven.
  • Kan API-sleutels niet weergeven of beheren, documenten laden, queryindexen uitvoeren of ophalen uit knowledge bases.
Inzender voor zoekservice Controle & Data
  • Volledige toegang tot de control plane. Toegang tot het gegevensvlak is beperkt tot objectbeheer.
  • Kan indexen, indexeerfuncties, vaardigheidensets, kennisbanken en andere zoekobjecten maken.
  • Kan beheer- en query-API-sleutels ophalen via besturingsvlakbewerkingen.
  • Kan geen documenten laden, indexen opvragen of rechtstreeks ophalen uit knowledge bases via op rollen gebaseerde toegang.
  • Zie Microsoft.Search/searchServices/* voor de volledige lijst met machtigingen.
Inzender voor zoekindexgegevens Gegevens
  • Lees-schrijftoegang tot inhoud.
  • Kan documenten laden, indexen opvragen en ophalen uit knowledge bases.
  • Kan objectdefinities niet wijzigen of beheerderssleutels ophalen.
Zoekindexgegevenslezer Gegevens
  • Alleen-lezen inhoudstoegang.
  • Kan query's uitvoeren op indexen en ophalen uit knowledge bases.
  • Kan geen documenten laden, objectdefinities wijzigen of beheerderssleutels ophalen.

Belangrijk

  • Eigenaar, Inzender en Inzender voor zoekservice kunnen beheerderssleutels ophalen, die volledige lees-/schrijftoegang tot het gegevensvlak bieden. Wijs deze rollen alleen toe aan vertrouwde gebruikers.
  • Gegevensvlakrollen zijn standaard van toepassing op alle indexen in de zoekservice. Zie Toegang verlenen tot één index als u de Search Index Data Contributor of Search Index Data Reader wilt beperken tot één index.

Samenvatting van machtigingen

Gebruik de volgende tabel om snel te vinden welke rol de benodigde machtigingen biedt.

Machtigingen Eigenaar/bijdrager Lezer Inzender voor zoekservice Inzender voor zoekindexgegevens Zoekindexgegevenslezer
Azure AI Zoeken-services maken en configureren ✅ ❌ ✅ ❌ ❌
Toegangsdienst in de Azure portal ✅ ✅ ✅ ❌ ❌
Service-eigenschappen, metrische gegevens en eindpunt weergeven ✅ ✅ ✅ ❌ ❌
Alle objecten in de service weergeven ✅ ✅ ✅ ❌ ❌
Toegangsquota en servicestatistieken ✅ ❌ ✅ ❌ ❌
Sleutels weergeven, kopiëren en opnieuw genereren ✅ ❌ ✅ ❌ ❌
Verificatieopties instellen ✅ ❌ ✅ ❌ ❌
Rollen, beleidsregels en definities weergeven ✅ ✅ ✅ ❌ ❌
Netwerkbeveiliging en privéverbindingen configureren ✅ ❌ ✅ ❌ ❌
Zoekobjecten maken, uitvoeren en beheren 1 ❌ ❌ ✅ ❌ ❌
Gegevens uploaden voor indexering 2 ❌ ❌ ❌ ✅ ❌
Een query op uitvoeren op een index ❌ ❌ ❌ ✅ ✅
Ophalen uit een knowledge base ❌ ❌ ❌ ✅ ✅
Machtigingsfilters overslaan met verhoogde leesrechten (preview) ❌ ❌ ❌ ✅ ❌

1 Bevat indexen, indexeerfuncties, gegevensbronnen, vaardighedensets, aliassen, synoniemenkaarten, foutopsporingssessies, knowledge bases en kennisbronnen. Indexers ondersteunen ook start- en resetbewerkingen.

2 Een eigenaar of inzender kan de wizard Gegevens importeren uitvoeren om indexen te maken en te laden, ook al kunnen ze geen documenten uploaden in andere clients. Op dezelfde manier kunnen indexeerfuncties naar elke index in de zoekservice schrijven, ongeacht roltoewijzingen per index. In beide gevallen voert de zoekservice (niet de gebruiker) de gegevensvlakacties uit met behulp van de Microsoft.Search/searchServices/indexes/documents/* machtigingen.

Ingebouwde rollen toewijzen

In deze sectie wijst u rollen toe voor:

Rollen toewijzen voor servicebeheer

Met de volgende rollen kunt u een zoekservice maken, configureren en beheren. Deze rollen zijn hiërarchisch, dus selecteer er een op basis van het benodigde toegangsniveau.

Rol Id
Eigenaar 8e3af657-a8ff-443c-a75c-2fe8c4bcb635
Inzender b24988ac-6180-42a0-ab88-20f7382dd24c
Lezer acdd72a7-3385-48ef-bd42-f606fba81ae7

  1. Ga naar uw zoekservice in de Azure portal.

  2. Selecteer toegangsbeheer (IAM) in het linkerdeelvenster.

  3. Selecteer +>Roltoewijzing toevoegen.

    Schermopname van de pagina Toegangsbeheer (IAM) voor het toewijzen van servicebeheerrollen.

  4. Selecteer een rol: Eigenaar, Inzender of Lezer.

  5. Selecteer op het tabblad Lids de Microsoft Entra gebruikers- of groepsidentiteit. Als u machtigingen instelt voor een andere Azure-service, selecteert u een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit.

  6. Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

Rollen toewijzen voor ontwikkeling

Met de volgende rollen kunt u zoekobjecten maken, documenten laden, queryindexen uitvoeren en ophalen uit knowledge bases. Wijs alle drie de rollen toe om het volledige scala aan ontwikkelingstaken te behandelen.

Rol Id
Inzender voor zoekservice 7ca78c08-252a-4471-8644-bb5ff32d4ba0
Inzender voor zoekindexgegevens 8ebe5a00-799e-43f5-93ac-243d3dce84a7
Zoekindexgegevenslezer 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Ga naar uw zoekservice in de Azure portal.

  2. Selecteer toegangsbeheer (IAM) in het linkerdeelvenster.

  3. Selecteer +>Roltoewijzing toevoegen.

    Schermopname van de pagina Toegangsbeheer (IAM) voor het toewijzen van ontwikkelingsrollen.

  4. Selecteer Inzender voor zoekservice.

  5. Selecteer op het tabblad Lids de Microsoft Entra gebruikers- of groepsidentiteit. Als u machtigingen instelt voor een andere Azure-service, selecteert u een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit.

  6. Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

  7. Herhaal deze stappen om Search Index Data Contributor en Search Index Data Reader toe te wijzen.

Rollen toewijzen voor alleen-lezentoegang

Gebruik de volgende rol voor apps en processen die alleen leestoegang nodig hebben tot indexen en knowledge bases. Ondersteunde bewerkingen zijn zoeken, opzoeken, automatisch aanvullen en suggesties voor indexen en ophalen voor knowledge bases.

Rol Id
Zoekindexgegevenslezer 1407120a-92aa-4202-b7e9-c0e197c71c8f

  1. Ga naar uw zoekservice in de Azure portal.

  2. Selecteer toegangsbeheer (IAM) in het linkerdeelvenster.

  3. Selecteer +>Roltoewijzing toevoegen.

    Schermopname van de pagina Toegangsbeheer (IAM) voor het toewijzen van alleen-lezen gegevenstoegangsrollen.

  4. Selecteer de rol Search Index Data Reader .

  5. Selecteer op het tabblad Lids de Microsoft Entra gebruikers- of groepsidentiteit. Als u machtigingen instelt voor een andere Azure-service, selecteert u een door het systeem toegewezen of door de gebruiker toegewezen beheerde identiteit.

  6. Selecteer op het tabblad Beoordelen en toewijzen de optie Beoordelen en toewijzen om de rol toe te wijzen.

Roltoewijzingen testen

Gebruik een client om roltoewijzingen te testen. Houd er rekening mee dat rollen cumulatief zijn. U kunt geërfde rollen die zijn toegewezen op het niveau van het abonnement of de resourcegroep niet verwijderen of weigeren op het niveau van de resource (zoekservice).

Voordat u verdergaat, configureert u uw toepassing voor sleutelloze verbindingen en beschikt u over roltoewijzingen.

  1. Ga naar uw zoekservice in de Azure portal.

  2. Selecteer zoekbeheerindexen> in het linkerdeelvenster om indexgerelateerde machtigingen te testen:

    • Inzenders voor zoekservices kunnen zoekobjecten maken, wijzigen en verwijderen, maar kunnen geen documenten laden of query's uitvoeren. Als u machtigingen wilt controleren, maakt u een zoekindex.

    • Inzenders voor zoekindexgegevens kunnen documenten laden. Er is geen optie documenten laden in de Azure-portal buiten de Import data wizard, maar u kunt opnieuw instellen en een indexeerfunctie uitvoeren om machtigingen voor het laden van documenten te bevestigen.

    • Zoekindexgegevenslezers kunnen query's uitvoeren op indexen. Gebruik Search Explorer om machtigingen te verifiëren. U moet query's kunnen verzenden en resultaten kunnen weergeven, maar u kunt geen indexdefinities weergeven of indexen maken.

Toegang verlenen tot één index

In sommige scenario's wilt u de toegang van een toepassing tot één resource beperken, zoals een index.

Op dit moment biedt de Azure-portal geen ondersteuning voor roltoewijzingen op indexniveau. Gebruik de Azure CLI, PowerShell of de REST API om rollen toe te wijzen die aan één index zijn toegewezen.

Per-indexscope en indexeerbewerkingen

Roltoewijzingen per index zijn alleen van toepassing op directe API-bewerkingen, zoals query's of documentuploads van gebruikers of toepassingen. Indexeerders worden niet beperkt door machtigingen per index omdat ze werken met service-referenties.

Een gebruiker met de rol Inzender voor zoekservice kan indexeerfuncties maken die naar een willekeurige index in de zoekservice schrijven, zelfs indexen waarbij die gebruiker geen roltoewijzing per index heeft.

Voor strikte gegevensisolatie tussen indexen kunt u de volgende benaderingen overwegen:

  • Gebruik afzonderlijke zoekservices voor teams of gebruikers die isolatie op indexniveau vereisen.
  • Wijs inzender voor de zoekservice alleen toe aan beheerders die indexeerfuncties beheren.
  • Gebruik toegangsbeheer op documentniveau met beveiligingsfilters om queryresultaten binnen een gedeelde index te beperken.

Een aangepaste rol maken

Als ingebouwde rollen niet de juiste combinatie van machtigingen bieden, kunt u een aangepaste rol maken ter ondersteuning van de bewerkingen die u nodig hebt.

In de volgende voorbeelden kloont u de zoekindexgegevenslezer en voegt u vervolgens de mogelijkheid toe om indexen op naam weer te geven. Normaal gesproken wordt het weergeven van de indexen voor een zoekservice beschouwd als een beheerrecht.

  1. Meld u aan bij de Azure-portal en navigeer naar uw zoekservice.

  2. Selecteer toegangsbeheer (IAM) in het linkerdeelvenster.

  3. Zoek op het tabblad RollenZoekindexgegevenslezer of een andere rol, selecteer het beletselteken (...) en selecteer Klonen.

  4. Voer op het tabblad Basics een naam in voor de aangepaste rol, zoals Search Index Data Explorer en selecteer Next.

  5. Selecteer Machtigingen toevoegen op het tabblad Machtigingen.

  6. Selecteer in het deelvenster Machtigingen de tegel Microsoft Search.

  7. Stel de volgende machtigingen in met Acties bovenaan geselecteerd:

    • Onder Microsoft.Search/operations, selecteer Lezen: alle beschikbare bewerkingen weergeven.
    • Onder Microsoft.Search/searchServices/indexes, selecteer Lezen : Lees index.

  8. Ga naar Gegevensacties bovenaan en selecteer onder Microsoft.Search/searchServices/indexes/documentsLezen: Documenten lezen.

    De JSON-definitie ziet er als volgt uit:

    {
    "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. Selecteer Toevoegen om het deelvenster te sluiten.

  10. Selecteer Beoordelen en maken om de rol te maken.

    U kunt nu gebruikers en groepen toewijzen aan de rol. Zie Azure aangepaste rollen maken of bijwerken met behulp van de Azure portal voor meer informatie over deze stappen.

Beleid voor voorwaardelijke toegang maken

Als u organisatiebeleid wilt afdwingen, zoals meervoudige verificatie, gebruikt u Microsoft Entra Voorwaardelijke toegang.

Een beleid voor voorwaardelijke toegang maken voor Azure AI Zoeken:

  1. Meld u aan bij de Azure-portal.

  2. Zoek naar Microsoft Entra Voorwaardelijke toegang.

  3. Selecteer op de pagina Overzichtde optie Nieuw beleid maken.

  4. Voeg onder Cloud-apps of -actiesAzure AI Zoeken toe als cloud-app, afhankelijk van hoe u uw beleid wilt instellen.

  5. Werk de resterende parameters van uw beleid bij. Geef bijvoorbeeld op op welke gebruikers en groepen het beleid van toepassing is.

  6. Sla het beleid op.

Belangrijk

Als aan uw zoekservice een beheerde identiteit is toegewezen, wordt de specifieke zoekservice weergegeven als een cloud-app. Maar als u die specifieke zoekservice selecteert, wordt het beleid niet toegepast. Selecteer in plaats daarvan de algemene Azure AI Zoeken cloud-app om beleid voor voorwaardelijke toegang toe te passen op uw zoekservice.

Troubleshooting

Wanneer u toepassingen ontwikkelt die gebruikmaken van op rollen gebaseerd toegangsbeheer voor verificatie, kunnen er enkele veelvoorkomende problemen optreden:

  • De standaardconfiguratie voor een zoekservice is verificatie op basis van sleutels. Als u deze instelling niet wijzigt in Zowel of op rollen gebaseerd toegangsbeheer, worden alle aanvragen die gebruikmaken van verificatie op basis van rollen automatisch geweigerd, ongeacht de onderliggende machtigingen.

  • Als uw aanvraag een API-sleutel bevat naast referenties op basis van rollen, wordt de service geverifieerd met behulp van de sleutel. Verwijder de API-sleutel uit uw aanvraagheaders om verificatie op basis van rollen te gebruiken.

  • Als het autorisatietoken afkomstig is van een beheerde identiteit en u onlangs de juiste machtigingen hebt toegewezen, kan het enkele uren duren voordat de machtigingentoewijzingen van kracht worden.

  • Als query's met machtigingen op documentniveau geen verwachte resultaten retourneren, gebruikt u Inzender voor zoekindexgegevens of maakt u een aangepaste rol met verhoogde machtigingen (preview) om te onderzoeken.

Volgende stap

In dit artikel wordt uitgelegd hoe u rollen toewijst voor besturings- en gegevensvlakbewerkingen op Azure AI Zoeken. Voor uitgebreide instructies over het toevoegen van op rollen gebaseerde toegang tot uw toepassingscode:

Verbind uw app met Azure AI Zoeken met behulp van identiteiten

  • Laatst bijgewerkt om