Freigeben über

Integrieren von Kontoschutz-APIs

  • Artikel

Um die Microsoft Dynamics 365 Fraud Protection Funktionen vollumfänglich zu nutzen, senden Sie die Transaktionsdaten an die Echtzeit-Anwendungsprogrammierschnittstellen (APIs). In der Auswertungserfahrung können Sie dann die Ergebnisse der Verwendung von Fraud Protection analysieren. In der Schutzerfahrung können Sie außerdem Entscheidungen basierend auf den Regeln, die Sie konfiguriert haben, berücksichtigen.

Abhängig davon, wie Sie Fraud Protection verwenden, können Sie verschiedene Konto-Schutz-APIs verwenden. Zum Beispiel AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate und Label.

Weitere Informationen zu allen unterstützten Ereignissen finden Sie unter Dynamics 365 Fraud Protection API.

Einrichten

Anmelden

Wichtig

Sie müssen globaler Administrator des Microsoft Azure-Mandanten sein, um die erstmalige API-Integration durchführen zu können.

So melden Sie sich bei Fraud Protection an:

  • Wechseln Sie zum Fraud Protection-Portal, melden Sie sich an und akzeptieren Sie die allgemeinen Geschäftsbedingungen, wenn Sie aufgefordert werden, diese zu akzeptieren.

    Dieser Schritt stellt sicher, dass Fraud Protection in Ihrem Azure-Mandanten korrekt konfiguriert ist. (Sie haben diesen Schritt ggf. bereits bei der erstmaligen Anmeldung durchgeführt.)

Erstellen von Microsoft Entra-Anwendungen

Wichtig

Sie müssen Anwendungsadministrator, Cloudanwendungsadministrator oder globaler Administrator in Ihrem Azure-Mandanten sein, um diesen Schritt durchführen zu können.

Um die Token abzurufen, die zum Aufrufen der APIs erforderlich sind, müssen Sie Microsoft Entra-Anwendungen verwenden. Sie können diese Apps konfigurieren mithilfe der Echtzeit-APIs-Seite in Fraud Protection.

So konfigurieren Sie Microsoft Entra-Apps:

  1. Wählen Sie im linken Navigationsbereich die Option Konfiguration und dann Echtzeit-APIs aus.

  2. Füllen Sie dann die Felder aus, um Ihre App zu erstellen. Folgende Felder sind erforderlich:

    • Anwendungsanzeigename – Geben Sie für die App einen beschreibenden Namen ein. Der Text kann maximal 93 Zeichen umfassen.
    • Umgebung – Wählen Sie den Produktionsendpunkt aus.
    • Authentifizierungsmethode – Wählen Sie aus, ob ein Zertifikat oder ein Geheimnis (Kennwort) zur Authentifizierung verwendet wird. Wenn Sie Zertifikat auswählen, wählen Sie Datei auswählen aus, um den öffentlichen Schlüssel hochzuladen. Sie benötigen den entsprechenden privaten Schlüssel, wenn Sie Token abrufen. Wenn Sie Geheimnis auswählen, wird nach dem Erstellen der App ein Kennwort für Sie generiert.

  3. Wenn Sie alle Felder ausgefüllt haben, wählen Sie Anwendung erstellen aus.

    Die Bestätigungsseite fasst den Namen und die ID der App sowie den Zertifikatsfingerabdruck oder das Geheimnis zusammen, abhängig von Ihrer ausgewählten Authentifizierungsmethode.

Wichtig

Speichern Sie die Informationen zu Ihrem Zertifikatsfingerabdruck oder Geheimnis als Referenz für die spätere Verwendung. Das Geheimnis wird nur einmal angezeigt.

Sie können beliebig viele Apps nach Bedarf erstellen, um API-Aufrufe in Ihren Produktionsumgebungen auszuführen.

So erstellen Sie eine weitere App:

  1. Erstellen Sie eine andere Anwendung auswählen.
  2. Füllen Sie die Felder aus, um Ihre App zu erstellen, und wählen Sie dann Anwendung erstellen.

Verwalten vorhandener Microsoft Entra-Anwendungen

Nachdem Sie Ihre Microsoft Entra-Apps erstellt haben, können Sie sie über die [Azure-Portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps) verwalten. Weitere Informationen finden Sie in der Azure-Dokumentationsseite.

Aufrufen der Fraud Protection-Echtzeit-APIs

Verwenden Sie die Informationen in diesem Abschnitt, um Ihre Systeme in Fraud Protection zu integrieren.

Erforderliche IDs und Informationen

  • API-Endpunkt – Der URI für Ihre Umgebung wird auf der Kachel Kontoinformationen im Fraud Protection-Dashboard angezeigt.
  • Verzeichnis-ID (Mandant) – Die Verzeichnis-ID bezeichnet den Globally Unique Identifier (GUID) für die Domäne des Mandanten in Azure. Sie erscheint im Azure-Portal und auf der Kachel Kontoinformationen im Fraud Protection-Dashboard.
  • Anwendungs-ID (Client-ID ) – Die Anwendungs-ID identifiziert die Microsoft Entra-App, die Sie zum Aufrufen von APIs erstellt haben. Sie finden diese ID auf der Bestätigungsseite, die nach Ihrer Auswahl von Erstellen einer Anwendung auf der Echtzeit-APIs-Seite angezeigt wird. Sie finden sie auch später unter App-Registrierungen im Azure-Portal. Es gibt eine ID für jede App, die Sie erstellt haben.
  • Zertifikatfingerabdruck oder Geheimnis – Den Zertifikatfingerabdruck oder das Geheimnis finden Sie auf der Bestätigungsseite, die nach Ihrer Auswahl von Erstellen einer Anwendung auf der Echtzeit-APIs-Seite angezeigt wird.
  • Instanz-ID – die Instanz-ID ist die global eindeutige Kennung (GUID) für Ihre Umgebung in Fraud Protection. Es wird in der Integration-Kachel auf dem Fraud Protection-Dashboard angezeigt.

Erstellen Sie ein Zugriffstoken

Sie müssen dieses Token generieren und für jeden API-Aufruf angeben. Beachten Sie, dass Zugriffstoken eine begrenzte Lebensdauer haben. Wir empfehlen Ihnen, jedes Zugriffstoken zwischenzuspeichern und erneut zu verwenden, bis es Zeit ist, ein neues Zugriffstoken abzurufen.

Die folgenden C#-Codebeispiele enthalten Beispiele, die zeigen, wie Sie mithilfe Ihres Zertifikats oder Geheimnisses ein Token abrufen. Ersetzen Sie die Platzhalter durch Ihre eigenen Informationen.

Zertifikatfingerabdruck

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;
}

Geheimnis

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;
}

Antwort

Im Hintergrund generiert der vorhergehende Code eine HTTP-Anforderung und erhält eine Antwort, die dem folgenden Beispiel ähnelt.

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>"
}

Weitere Informationen finden Sie in der Azure-Dokumentationsseite:

Aufrufen der APIs

Gehen Sie zum Aufrufen der APIs folgendermaßen vor.

  1. Übergeben Sie die folgenden erforderlichen HTTP-Kopfzeilen für jede Anforderung.

    Headername Headerwert
    Autorisierung Verwenden Sie das folgende Format für diesen Header: Bearer accesstoken, wobei accesstoken das Token ist, das von Microsoft Entra ID zurückgegeben wird.
    x-ms-correlation-id Senden Sie einen neuen GUID-Wert für jeden Satz von API-Aufrufen, die zusammen gemacht werden.
    x-ms-dfpenvid Senden Sie den GUID-Wert Ihrer Instanz-ID.

  2. Erstellen Sie eine ereignisbasierte Nutzlast. Füllen Sie die Ereignisdaten mit den relevanten Informationen vom System aus. Weitere Informationen zu allen unterstützten Ereignissen finden Sie unter Dynamics 365 Fraud Protection API.

  3. Kombinieren Sie die Kopfzeile (die das Zugriffstoken enthält) und die Nutzlast, und senden Sie diese dann zum Fraud Protection-Endpunkt.

Notiz

Wenn Sie eine neue Umgebung erstellen, geben Sie bei der Integration die Umgebungs-ID im API-Header an, damit die Transaktionen korrekt weitergeleitet werden können.

Beispiel-App anzeigen

Für zusätzliche Referenz siehe die Beispielhändler-App und die dazugehörige Entwicklerdokumentation. Die Beispiel-App enthält ein Beispiel, das zeigt, wie Fraud Protection-APIs in Echtzeit aufgerufen werden. Die Dokumentation zur Beispiel-App ist mit dem tatsächlichen Beispielcode verknüpft, wenn diese Links möglich sind. Andernfalls sind Codebeispiele direkt in der Dokumentation enthalten.

Informationen zum Konfigurieren der Beispielwebsite für die Verwendung finden Sie unter Konfigurieren der Beispielwebsite.