Delen via

Accountbeveiligings-API's integreren

  • Artikel

Als u de volledige reeks functies van Microsoft Dynamics 365 Fraud Protection wilt gebruiken, moet u uw transactiegegevens verzenden naar de realtime API's (Application Programming Interfaces). Met 'evaluate'-ervaring kunt u de resultaten van het gebruik van Fraud Protection vervolgens analyseren. Met de 'protect'-ervaring kunt u ook beslissingen nakomen dia zijn gebaseerd op de regels die u hebt geconfigureerd.

Afhankelijk van de manier waarop u Fraud Protection wilt gebruiken, gebruikt u verschillende API's voor accountbeveiliging. Bijvoorbeeld AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate en Label.

Zie Dynamics 365 Fraud Protection-API voor informatie over alle ondersteunde gebeurtenissen.

Instellingen

Aanmelden

Belangrijk

Om de eerste API-implementatie te voltooien, moet u een globale beheerder zijn in uw Microsoft Azure-tenant.

Aanmelden bij Fraud Protection:

  • Ga naar de Fraud Protection-portal, meld u aan en accepteer de voorwaarden wanneer dit wordt gevraagd.

    Deze stap zorgt ervoor dat Fraud Protection correct is geconfigureerd in uw Azure-tenant. (Het is mogelijk hebt u deze stap al hebt voltooid tijdens de eerste aanmelding.)

Microsoft Entra-toepassingen maken

Belangrijk

Om deze stap te kunnen voltooien, moet u een toepassingsbeheerder, cloudtoepassingsbeheerder of globale beheerder zijn in uw Azure-tenant.

Als u de tokens wilt verkrijgen die nodig zijn om de API's aan te roepen, moet u Microsoft Entra-toepassingen gebruiken. U kunt deze toepassingen configureren op de pagina Realtime API's in Fraud Protection.

Microsoft Entra-apps configureren:

  1. Selecteer in de linkernavigatie de optie Configuratie en selecteer Realtime API's.

  2. Vul de velden in om uw app te maken. Het volgende velden zijn vereist:

    • Weergavenaam van toepassing: voer een beschrijvende naam voor de toepassing in. De tekst mag maximaal 93 tekens lang zijn.
    • Omgeving : selecteer het productie-eindpunt.
    • Verificatiemethode: selecteer of u voor verificatie een certificaat of een geheim (wachtwoord) wilt gebruiken. Als u Certificaat selecteert, selecteert u Bestand kiezen om de openbare sleutel te uploaden. Als u tokens krijgt, hebt u de bijpassende persoonlijke sleutel nodig. Als u Geheim selecteert, wordt er een wachtwoord voor u gegenereerd nadat de app is gemaakt.

  3. Wanneer u klaar bent met het invullen van de velden, selecteert u Toepassing maken.

    De bevestigingspagina geeft een overzicht met de naam, de id, en de vingerafdruk van het certificaat of het geheim voor de toepassing, afhankelijk van de verificatiemethode.

Belangrijk

Sla de informatie over de vingerafdruk van het certificaat of het geheim op voor toekomstige referentie. Het geheim wordt slechts één keer weergegeven.

U kunt zoveel toepassingen maken als nodig zijn om API-aanroepen in uw productieomgevingen uit te voeren.

Een andere app maken:

  1. Selecteer Een andere toepassing maken.
  2. Vul de velden in om uw app te maken en selecteer vervolgens Toepassing maken.

Bestaande Microsoft Entra-toepassingen beheren

Nadat u uw Microsoft Entra-apps hebt gemaakt, kunt u deze beheren via [Azure Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Raadpleeg de Azure-documentatiewebsite voor meer informatie.

De realtime API's van Fraud Protection aanroepen

Gebruik de informatie in deze sectie om uw systemen te integreren met Fraud Protection.

Vereiste id's en gegevens

  • API-eindpunt: de URI voor uw omgeving wordt weergegeven op de tegel Accountgegevens van het Fraud Protection-dashboard.
  • Directory-id (tenant): de directory-id is de GUID (Globally Unique Identifier) voor het domein van een tenant in Azure. Deze verschijnt in de Azure Portal en op de tegel Accountgegevens op het Fraud Protection-dashboard.
  • Toepassings-id (client): de toepassings-id identificeert de Microsoft Entra-app die u hebt gemaakt om API's aan te roepen. U vindt deze id op de bevestigingspagina die wordt weergegeven nadat u Toepassing maken hebt geselecteerd op de pagina Realtime API's. U kunt deze ook later vinden onder App-registraties in de Azure Portal. Er is één id voor elke app die u hebt gemaakt.
  • Vingerafdruk van certificaat of geheim: u vindt de vingerafdruk van het certificaat of het geheim op de bevestigingspagina die wordt weergegeven nadat u Toepassing maken hebt geselecteerd op de pagina Realtime API's.
  • Exemplaar-id: de exemplaar-id is de GUID voor uw omgeving in Fraud Protection. Deze wordt weergegeven op de tegel Integratie van het Fraud Protection-dashboard.

Een toegangstoken genereren

U moet dit token genereren en bij elke API-aanroep opgeven. Houd er rekening mee dat toegangstokens een beperkte levensduur hebben. We raden u aan om elke token in de cache te plaatsen en opnieuw te gebruiken totdat het tijd is om een nieuwe toegangstoken te krijgen.

De volgende voorbeelden in C#-code laten zien hoe u een token verkrijgt met behulp van uw certificaat of geheim. Vervang de tijdelijke aanduidingen door uw eigen informatie.

Vingerafdruk certificaat

public async Task<string> AcquireTokenWithCertificateAsync()
{
    var x509Cert = CertificateUtility.GetByThumbprint("<Certificate thumbprint>");
    var clientAssertion = new ClientAssertionCertificate("<Client ID>", x509Cert);
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

Geheim

public async Task<string> AcquireTokenWithSecretAsync()
{
    var clientAssertion = new ClientCredential("<Client ID>", "<Client secret>");
    var context = new AuthenticationContext("<Authority URL. Typically https://login.microsoftonline.com/[Directory_ID]>");
    var authenticationResult = await context.AcquireTokenAsync("<API endpoint>", clientAssertion);

    return authenticationResult.AccessToken;
}

Respons

Met de voorgaande code wordt achter de scherm een HTTP-aanvraag gegenereerd en ontvangt u een reactie vergelijkbaar met het volgende voorbeeld.

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Date: <date>
Content-Length: <content length>

{
    "token_type":"Bearer",
    "expires_in":"3599",
    "ext_expires_in":"3599",
    "expires_on":"<date timestamp>",
    "not_before":"<date timestamp>",
    "resource":"https://api.dfp.dynamics.com",
    "access_token":"<your access token; e.g.: eyJ0eXA...NFLCQ>"
}

Raadpleeg de Azure-documentatiewebsite voor meer informatie:

De API's aanroepen

Volg deze stappen om de API's aan te roepen.

  1. Geef bij elk verzoek de volgende vereiste HTTP-headers door.

    Headernaam Headerwaarde
    Autorisatie Gebruik de volgende indeling voor deze header: Bearer-toegangstoken, waarbij het toegangstoken het token is dat wordt geretourneerd door Microsoft Entra-id.
    x-ms-correlation-id Verzend een nieuwe GUID-waarde voor elke set API-aanroepen die samen worden ingediend.
    x-ms-dfpenvid Verzend de GUID-waarde van uw exemplaar-id.

  2. Genereer een op gebeurtenissen gebaseerde payload. Vul voor de gebeurtenisgegevens de relevante informatie van uw systeem in. Zie Dynamics 365 Fraud Protection-API voor informatie over alle ondersteunde gebeurtenissen.

  3. Combineer de header (inclusief de toegangstoken) en de payload en stuur deze vervolgens naar uw Fraud Protection-eindpunt.

Notitie

Als u een nieuwe omgeving maakt, neemt u tijdens de integratie de omgevings-id op in de API-header, zodat de transacties correct kunnen worden gerouteerd.

De voorbeeld-app weergeven

Voor extra referentie raadpleegt u de voorbeeld-app voor handelaren en bekijkt u de bijbehorende documentatie voor ontwikkelaars. De voorbeeld-app bevat een voorbeeld waarin wordt aangegeven hoe u Fraud Protection-API's in realtime aanroept. De documentatie voor de voorbeeld-app is gekoppeld aan de werkelijke voorbeeldcode wanneer koppelingen mogelijk zijn. Anders worden codevoorbeelden rechtstreeks in de documentatie opgenomen.

Zie De voorbeeldsite configureren voor informatie over het configureren van de voorbeeldsite zodat u deze kunt gebruiken.