Freigeben über

Kontoschutz-APIs integrieren

Von Bedeutung

Ab dem 3. Februar 2025 steht Dynamics 365 Fraud Protection nicht mehr zum Kauf zur Verfügung. Die Unterstützung für Betrugsschutz endet am 3. Februar 2026. Weitere Informationen finden Sie im Artikel Ende des Supports für Dynamics 365 Fraud Protection.

Um die vollständige Suite von Features in Microsoft Dynamics 365 Fraud Protection vollständig nutzen zu können, senden Sie Ihre Transaktionsdaten an die Echtzeit-APIs (Application Programming Interfaces). In der Auswertungserfahrung können Sie dann die Ergebnisse der Verwendung von Betrugsschutz analysieren. In der Schutzumgebung können Sie auch Entscheidungen berücksichtigen, die auf den von Ihnen konfigurierten Regeln basieren.

Je nachdem, wie Sie Betrugsschutz verwenden, können Sie unterschiedliche Kontoschutz-APIs verwenden. Beispiel: AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate und Label.

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

Einrichten

Anmelden

Von Bedeutung

Um das anfängliche API-Onboarding abzuschließen, müssen Sie ein globaler Administrator in Ihrem Microsoft Azure-Mandanten sein.

So melden Sie sich bei Betrugsschutz an:

  • Wechseln Sie zum Portal "Betrugsschutz", melden Sie sich an, und akzeptieren Sie die Allgemeinen Geschäftsbedingungen, wenn Sie aufgefordert werden, sie zu akzeptieren.

    Dieser Schritt stellt sicher, dass Betrugsschutz in Ihrem Azure-Mandanten ordnungsgemäß konfiguriert ist. (Möglicherweise haben Sie diesen Schritt bereits während der erstanmeldung abgeschlossen.)

Erstellen von Microsoft Entra-Anwendungen

Von Bedeutung

Um diesen Schritt abzuschließen, müssen Sie ein Anwendungsadministrator, ein Cloudanwendungsadministrator oder ein globaler Administrator in Ihrem Azure-Mandanten sein.

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

So konfigurieren Sie Microsoft Entra-Apps:

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

  2. Füllen Sie die Felder aus, um Ihre App zu erstellen. Die folgenden Felder werden benötigt:

    • 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 geheimer Schlüssel (Kennwort) für die 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 "Geheim" auswählen, wird nach dem Erstellen der App ein Kennwort für Sie generiert.

  3. Wenn Sie mit dem Ausfüllen der Felder fertig sind, wählen Sie "Anwendung erstellen" aus.

    Auf der Bestätigungsseite werden der Name und die ID der App sowie der Zertifikatfingerabdruck oder der geheime Schlüssel zusammengefasst, abhängig von der ausgewählten Authentifizierungsmethode.

Von Bedeutung

Speichern Sie die Informationen zu Ihrem Zertifikatfingerabdruck oder geheimen Schlüssel für zukünftige Verweise. Das Geheimnis wird nur einmal angezeigt.

Sie können so viele Apps erstellen, wie Sie API-Aufrufe in Ihren Produktionsumgebungen ausführen müssen.

So erstellen Sie eine andere App:

  1. Wählen Sie "Eine andere Anwendung erstellen" aus.
  2. Füllen Sie die Felder aus, um Ihre App zu erstellen, und wählen Sie dann "Anwendung erstellen" aus.

Verwalten vorhandener Microsoft Entra-Anwendungen

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

Aufrufen der Betrugsschutz-APIs in Echtzeit

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

Erforderliche IDs und Informationen

  • API-Endpunkt – Der URI für Ihre Umgebung wird auf der Kachel " Kontoinformationen " im Dashboard "Betrugsschutz" angezeigt.
  • Verzeichnis-ID (Mandant) – Die Verzeichnis-ID ist die GUID (Globally Unique Identifier) für die Domäne eines Mandanten in Azure. Sie wird im Azure-Portal und auf der Kachel " Kontoinformationen " im Dashboard "Betrugsschutz" angezeigt.
  • 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 angezeigt wird, nachdem Sie auf der Seite "Echtzeit-APIs" die Option "Anwendung erstellen" ausgewählt haben. 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 geheimer Schlüssel – Sie finden den Zertifikatfingerabdruck oder den geheimen Schlüssel auf der Bestätigungsseite, die angezeigt wird, nachdem Sie auf der Seite "Echtzeit-APIs erstellen" die Anwendung ausgewählt haben.
  • Instanz-ID – Die Instanz-ID ist die GUID (Globally Unique Identifier) für Ihre Umgebung im Betrugsschutz. Sie wird auf der Kachel "Integration" im Dashboard "Betrugsschutz" angezeigt.

Erstellen eines Zugriffstokens

Sie müssen dieses Token generieren und für jeden API-Aufruf bereitstellen. Beachten Sie, dass Zugriffstoken eine begrenzte Lebensdauer haben. Es wird empfohlen, jedes Zugriffstoken zwischenzuspeichern und wiederzuverwenden, bis es an der Zeit ist, ein neues Zugriffstoken abzurufen.

Die folgenden C#-Codebeispiele enthalten Beispiele, die zeigen, wie Sie ein Token mithilfe Ihres Zertifikats oder geheimen Schlüssels abrufen. Ersetzen Sie die Platzhalter mithilfe Ihrer 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 vorangehende Code eine HTTP-Anforderung und empfängt 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-Dokumentation:

Aufrufen der APIs

Führen Sie die folgenden Schritte aus, um die APIs aufzurufen.

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

    Kopfzeilenname 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 jede Gruppe von API-Aufrufen, die zusammen ausgeführt werden.
    x-ms-dfpenvid Senden Sie den GUID-Wert Ihrer Instanz-ID.

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

  3. Kombinieren Sie den Header (einschließlich des Zugriffstokens) und der Nutzlast, und senden Sie sie dann an Ihren Betrugsschutz-Endpunkt.

Hinweis

Wenn Sie eine neue Umgebung erstellen, schließen Sie die Umgebungs-ID während der Integration in den API-Header ein, damit die Transaktionen ordnungsgemäß weitergeleitet werden können.

Beispiel-App anzeigen

Weitere Informationen finden Sie in der Beispiel-Händler-App und in der zugehörigen Entwicklerdokumentation. Die Beispiel-App enthält ein Beispiel, das zeigt, wie Betrugsschutz-APIs in Echtzeit aufgerufen werden. Die Dokumentation für die Beispiel-App ist immer dann mit dem tatsächlichen Beispielcode verknüpft, wenn Links möglich sind. Andernfalls sind Codebeispiele direkt in der Dokumentation enthalten.

Informationen zum Konfigurieren der Beispielwebsite, damit Sie sie verwenden können, finden Sie unter Konfigurieren der Beispielwebsite.