Zelfstudie: Microsoft Purview API's gebruiken om uw beleid in uw apps te gebruiken

Alle apps, waaronder Enterprise AI-apps, verwerken gevoelige gegevens waarvoor beveiliging is vereist tegen gegevenslekken, onbevoegde toegang en schendingen van naleving. Microsoft Purview beleid helpt organisaties gevoelige informatie te beschermen. Uw apps kunnen worden geïntegreerd met de Microsoft Purview-API's om ervoor te zorgen dat Microsoft Purview beleid het beveiligingspostuur van uw app ondersteunt.

Dit artikel bevat een overzicht van hoe u de Microsoft Purview API's kunt toevoegen aan uw bestaande bedrijfs-app om gebruik te maken van uw beleid. Het voorbeeld dat in dit artikel wordt gebruikt, is een GenAI-app, maar dezelfde concepten kunnen eenvoudig worden toegepast op niet-AI-apps. Aan het einde van deze stapsgewijze uitleg begrijpt u het volgende:

• Wanneer en hoe u de Purview-API's aanroept voor een bekende gebruiker voor een activiteit die ze uitvoeren in uw app.
• Evalueer gebruikersinvoer en app-uitvoer (bijvoorbeeld prompts en AI-antwoorden of door de gebruiker ingediende tekst en gegenereerde inhoud) op basis van dit beleid.
• Beleidsacties afdwingen in uw app, zoals het blokkeren of up-to-date blijven met beleidswijzigingen in uw tenant.

Prerequisites

Voordat u begint, moet u ervoor zorgen dat u het volgende heeft:

• Een Azure-abonnement met Microsoft Purview geconfigureerd.

• Een toepassing die is geregistreerd in Microsoft Entra ID met de juiste machtigingen.

• Basiskennis van Microsoft Graph API gesprekken.

• Toegang tot de invoer en app-uitvoer van de gebruiker die u wilt evalueren (bijvoorbeeld vragen en antwoorden in een GenAI-app, of tekst die is geüpload/gedownload door een Line-Of-Business-app).

• Voor end-to-end-tests maakt u beleidsregels in uw Microsoft Purview-portal. Zie Microsoft Purview gebruiken om gegevensbeveiliging en compliance te beheren voor bij Entra geregistreerde AI-apps voor meer informatie over de beschikbare beleidsregels.

  Important

  Als u een DLP-beleid wilt maken dat van toepassing is op uw geregistreerde entra-app, moet u de New-DlpComplianceRule PowerShell-cmdlet gebruiken. De Microsoft Purview-portal biedt momenteel geen ondersteuning voor het maken van DLP-beleid voor entra-geregistreerde toepassingen. Zie New-DlpComplianceRule voor meer informatie.

Aan de slag met Microsoft Graph

Zie Microsoft Graph Basisprincipes als u nog niet eerder Microsoft Graph gebruikt.

Met de volgende stappen kunt u experimenteren met de API. Gebruik deze stappen niet om een productie-implementatie van uw toepassing te plannen.

1. Meer informatie over de Microsoft Purview API's in Microsoft Graph om te integreren in uw app. Deze API's worden verderop in dit artikel uitgebreid beschreven.

2. Laat uw Entra-beheerder uw app registreren in Entra. Afhankelijk van het beleid van uw bedrijf kunnen ze u toestaan een app te registreren of moet u mogelijk een registratieproces volgen. Neem contact op met uw Entra-beheerder om inzicht te hebben in het proces dat moet worden gevolgd voor uw tenant. Zie de volgende bronnen voor meer informatie:

   • Registreer een toepassing bij het Microsoft Identity Platform.
   • Microsoft identity platform codevoorbeelden voor verificatie en autorisatie.
   • Microsoft Graph overzicht van verificatie en autorisatie.
   • Toepassingen in het Microsoft Entra ID ecosysteem tot stand brengen.
   • Microsoft Entra ID Guide voor onafhankelijke softwareontwikkelaars.

3. Configureer uw app met de vereiste machtigingen. Zorg ervoor dat uw app deze machtigingen aanvraagt wanneer het token wordt aangevraagd bij Microsoft Graph. U kunt bijvoorbeeld de Content.Process.User en ProtectionScopes.Compute.User machtigingen toewijzen aan uw app. Zie Microsoft Graph referentiemateriaal voor machtigingen en toepassingen, resources en workloads autoriseren met Microsoft Entra ID voor meer informatie.

4. Laat uw tenantbeheerder Microsoft Purview beleid en instellingen configureren. Zie Microsoft Purview-oplossingen configureren in DSPM (Data Security Posture Management) voor AI voor aangepaste AI-toepassingen voor meer informatie. Uw beheerder moet de New-DlpComplianceRule PowerShell-cmdlet gebruiken om DLP-beleid te maken voor uw entra-geregistreerde apps. De Microsoft Purview-portal biedt geen ondersteuning voor dit scenario.

5. Uw app testen. Zie Een AI-toepassing testen met behulp van de Purview-API voor meer informatie.

Overzicht van Microsoft Purview API-integratie

Uw toepassing voert twee belangrijke API-aanroepen uit ter ondersteuning van uw Microsoft Purview-beleid:

1. Compute protection scopes: bepaalt welke gebruikersactiviteiten (uploadText, downloadText, uploadFile, downloadFile) beleidsevaluatie vereisen voor een specifieke gebruiker.
2. Process content: uw app verzendt een inhoudsactiviteit voor beleidsevaluatie en retourneert beleidsacties die uw app moet afdwingen (zoals het blokkeren of detecteren van beleidswijzigingen).

De volgende secties bevatten stapsgewijze implementatierichtlijnen, inclusief codevoorbeelden en het afhandelen van antwoorden.

Zie de video Microsoft Reactor voor een gedetailleerd overzicht van een demo-app die deze API-aanroepen doet.

Stap 1: Beveiligingsbereiken berekenen voor de gebruiker

De eerste stap is om te bepalen welke beleidsregels en beperkingen van toepassing zijn op een specifieke gebruiker op basis van de activiteiten die ze in uw toepassing kunnen uitvoeren (zoals het uploaden van tekstinvoer/prompts of het downloaden van AI-antwoorden). Dit wordt het berekenen van de beveiligingsomvang van de gebruiker genoemd.

Beveiligingsbereiken zijn een abstractie van beleidsregels in de tenant die van toepassing zijn op de gebruiker. Voor elke gebruiker en activiteit die de gebruiker in uw app uitvoert, wilt u het beveiligingsbereik berekenen. De beveiligingsscope geeft aan welke actie de app vervolgens moet uitvoeren: evalueren en blokkeren, evalueren en niet blokkeren, of geen evaluatie nodig.

Hier volgt een voorbeeld van een aanvraag voor protectionScopes/compute.

POST https://graph.microsoft.com/v1.0/users/7c1f8f10-cba8-4a8d-9449-db4b876d1ef70/dataSecurityAndGovernance/protectionScopes/compute
Content-type: application/json

{
   "activities": "uploadText,downloadText",
   "locations": [
      {
         "@odata.type": "microsoft.graph.policyLocationApplication",
         "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
      }
   ]
}

In de voorgaande aanroep om het beveiligingsbereik te berekenen, moet u de gebruikersactiviteiten opnemen die de gebruiker uitvoert in uw app. Geaccepteerde gebruikersactiviteiten zijn onder andere:

• uploadText: gebruikers verzenden tekstinvoer naar de app (bijvoorbeeld een prompt die is verzonden naar een AI, een bericht in een chat-app of tekst die in een formulier is geplakt).
• downloadText: op tekst gebaseerde uitvoer die de app retourneert naar de gebruiker (bijvoorbeeld een AI-antwoord of een gegenereerde hoofdtekst van het document).
• uploadFile - gebruiker verzendt een bestand naar de app (bijvoorbeeld een bestand dat is gekoppeld aan een prompt voor verwerking).
• downloadFile: een bestand dat door de app wordt geretourneerd aan de gebruiker (bijvoorbeeld een bestand dat is gegenereerd door AI of geëxporteerd door een Line-Of-Business-app).

Zie waarden voor userActivityTypes voor meer informatie over gebruikersactiviteiten.

De aanroep voor het berekenen van beveiligingsbereiken retourneert een verzameling policyUserScopes. Hier volgt een voorbeeld van een antwoord met 2 beveiligingsbereiken.

HTTP/1.1 200 OK
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.policyUserScope)",
  "value": [
    {
      "activities": "uploadText,downloadText",
      "executionMode": "evaluateOffline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    },
    {
      "activities": "uploadText",
      "executionMode": "evaluateInline",
      "locations": [
        {
          "@odata.type": "#microsoft.graph.policyLocationApplication",
          "value": "83ef198a-0396-4893-9d4f-d36efbffc8bd"
        }
      ],
      "policyActions": []
    }
  ]
}

Het is belangrijk dat uw app dit antwoord parseert om te bepalen welke gebruikersactiviteit (bijvoorbeeld uploadText) beleidsevaluatie vereist voor de inhoud die door of naar de gebruiker is verzonden.

Als de geretourneerde verzameling policyUserScopes leeg is: Er gelden geen beleidsregels voor de gebruiker voor de gebruikersactiviteit. Wanneer er geen beleid is toegepast op deze gebruiker voor deze activiteit, wordt u aangeraden inhoudsactiviteiten aan te roepen om activiteiten te registreren voor controlenaleving en anomaliedetectie. U kunt dit een configureerbare instelling in uw app maken.

Als de verzameling policyUserScopes scopes bevat: Wanneer beschermingsbereiken worden geretourneerd, moet uw app de respons parseren door de waarden van activities en executionMode voor elk beschermingsbereik te controleren. In het bovenstaande voorbeeld worden in de policyUserScopes-verzameling 2 beveiligingsbereiken teruggegeven.

executionMode helpt u te bepalen welke beperking van toepassing is op een bepaalde gebruiker voor een gebruikersactiviteit. De volgende lijst bevat de geldige waarden voor executionMode:

• evaluateOffline: betekent dat u een asynchrone aanroep kunt maken om de inhoud te evalueren op basis van een beleid bij het aanroepen processContent.
• evaluateInline: betekent dat de hoofdthread van uw app geblokkeerd blijft totdat de aanroep van processContent terugkeert.

Zie executionMode-waarden voor meer informatie.

De activity geeft de gebruikersactiviteit aan waarop het beveiligingsbereik van toepassing is. Mogelijk ziet u dat een activity in meer dan 1 beveiligingsbereik voorkomt. U ziet bijvoorbeeld in het voorgaande voorbeeld dat uploadText wordt geretourneerd in beide beveiligingsbereiken. In deze situatie moet uw app het meer beperkende beveiligingsbereik toepassen op die gebruikersactiviteit.

In het volgende voorbeeld ziet u hoe uw app de voorgaande geretourneerde policyUserScopes verzameling zou parseren:

1. Door het eerste beveiligingsbereik te parseren, zien we de volgende informatie:
   • uploadText (ofwel prompts die aan de AI worden gestuurd) en downloadText (ofwel antwoorden van de AI) moeten offline worden geëvalueerd.
2. Bij het parseren van het tweede beveiligingsbereik zien we de volgende informatie:
   • uploadText (ofwel prompts die naar de AI zijn verzonden) moeten inline worden beoordeeld.
3. Voor een van de andere gebruikersactiviteiten (uploadFile, ) downloadFilezijn er geen beveiligingsbereiken van toepassing op die gebruikersactiviteiten. Overweeg om inhoudsactiviteit aan te roepen zoals eerder is beschreven.

De logica die uw app moet implementeren voor deze verschillende gebruikersactiviteiten zijn als volgt:

Stap 2: Inhoud verwerken

Vervolgens moet uw app mogelijk processContent aanroepen op basis van de status van het beveiligingsbereik van de gebruiker.

Zoals eerder beschreven, moeten alle gebruikersactiviteiten waarbij de executionMode ofwel evaluateInline of evaluateOffline was, processContent aanroepen.

Wanneer u de aanroep doet, verzendt u de waarde ETag die uw app in stap 1 in de cache heeft opgeslagen vanuit de aanroep naar protectionScopes/compute om te bepalen of er wijzigingen in het beleid zijn aangebracht in uw tenant. U stuurt de ETag-waarde in de If-None-Match-header.

Hier volgt een voorbeeld van een aanroep naar processContent.

POST https://graph.microsoft.com/v1.0/me/dataSecurityAndGovernance/processContent
Content-Type: application/json

{
    "contentToProcess": {
       "contentEntries": [
          {
             "@odata.type": "microsoft.graph.processConversationMetadata",
             "identifier": "07785517-9081-4fe7-a9dc-85bcdf5e9075",
             "content": {
                "@odata.type": "microsoft.graph.textContent", 
                "data": "Write an acceptance letter for Alex Wilber with Credit card number 4532667785213500, ssn: 120-98-1437 at One Microsoft Way, Redmond, WA 98052"
             },
             "name":"PC Purview API Explorer message",
             "correlationId": "d63eafd2-e3a9-4c1a-b726-a2e9b9d9580d",
             "sequenceNumber": 0, 
             "isTruncated": false,
             "createdDateTime": "2025-05-27T17:23:20",
             "modifiedDateTime": "2025-05-27T17:23:20"
          }
       ],
       "activityMetadata": { 
          "activity": "uploadText"
       },
       "deviceMetadata": {
          "deviceType": "Unmanaged",
          "operatingSystemSpecifications": {
             "operatingSystemPlatform": "Windows 11",
             "operatingSystemVersion": "10.0.26100.0" 
          },
          "ipAddress": "127.0.0.1"
       },
       "protectedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2",
          "applicationLocation":{
             "@odata.type": "microsoft.graph.policyLocationApplication",
             "value": "83ef208a-0396-4893-9d4f-d36efbffc8bd"
          }
       },
       "integratedAppMetadata": {
          "name": "PC Purview API Explorer",
          "version": "0.2" 
       }
    }
}

Hier volgt een voorbeeld van een antwoord van processContent.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.processContentResponse",
  "protectionScopeState": "modified",
  "policyActions": [
    {
      "@odata.type": "#microsoft.graph.restrictAccessAction",
      "action": "restrictAccess",
      "restrictionAction": "block"
    }
  ],
  "processingErrors": []
}

In het voorgaande voorbeeld zijn er twee acties die uw app moet uitvoeren:

1. De processContentResponse eigenschap bevat de protectionScopeState eigenschap die is ingesteld op modified. modified geeft aan dat het beleid in de tenant is gewijzigd. Omdat het beleid is gewijzigd, moet uw app eerst aanroepen protectionScopes/compute om de nieuwe beveiligingsbereiken voor die gebruiker op te halen. Dit wordt beschreven in stap 1. Zorg ervoor dat u de nieuwe ETag-waarde in de cache opslaat.
2. Omdat de policyActions verzameling niet leeg is, moet uw app elke action stap doorlopen om de juiste actie te bepalen die moet worden uitgevoerd. In dit voorbeeld restrictAccess betekent dit dat uw app de gebruiker moet blokkeren voor de aangevraagde actie. Als de policyActions verzameling in de processContentResponse verzameling leeg was, gaat uw app verder met de aangevraagde activiteit. Als u agents bouwt, moet de agent ook blokkeren voordat hij een andere agent aanroept wanneer action is ingesteld op restrictAccess.