Integrare le API di protezione di account

Per sfruttare la gamma completa delle funzionalità di Microsoft Dynamics 365 Fraud Protection, è necessario invia i dati sulle transazioni alle API in tempo reale. Nell'esperienza di valutazione è possibile analizzare i risultati dell'uso di Fraud Protection. Nell'esperienza di protezione, è inoltre possibile rispettare le decisioni basate sulle regole configurate.

A seconda di come scegli di utilizzare Fraud Protection, puoi usare API di protezione di account differenti. Ad esempio, AccountCreation, AccountLogin, AccountCreationStatus, AccountLoginStatus, AccountUpdate e Label.

Per le informazioni sugli eventi supportati, vedere API di Dynamics 365 Fraud Protection

Imposta

Accedi

Per accedere a Fraud Protection:

• Andare al portale di Fraud Protection, accedere e accettare i termini e le condizioni se viene richiesto di accettarli.

  Questo passaggio garantisce che Fraud Protection sia configurato correttamente nel tenant di Azure. È possibile aver già completato questo passaggio durante l'accesso iniziale.

Creare applicazioni Microsoft Entra

Per acquisire i token necessari per chiamare le API, è necessario usare le applicazioni Microsoft Entra. È possibile configurare queste app utilizzando la pagina API in tempo reale in Fraud Protection.

Per configurare le app Microsoft Entra:

1. Nel riquadro di spostamento a sinistra, selezionare Configurazione e quindi API in tempo reale.

2. Compila i campi per creare l'app. I campi seguenti sono obbligatori:

   • Nome visualizzato dell'applicazione - Immettere un nome descrittivo per l'app. La lunghezza massima consentita è di 93 caratteri.
   • Ambiente - Selezionare l'endpoint di produzione.
   • Metodo di autenticazione - Selezionare se utilizzare un certificato o un segreto (password) per l'autenticazione. Se si seleziona Certificato, selezionare Scegli file per caricare la chiave pubblica. Quando si acquisiscono i token, sarà necessaria la chiave privata corrispondente. Se si seleziona Segreto, viene generata una password dopo la creazione dell'app.

3. Al termine della compilazione dei campi, selezionare Crea applicazione.

   Nella pagina di conferma verrà riepilogato il nome dell'app, l'ID e l'identificazione digitale del certificato o il segreto, a seconda della modalità di autenticazione selezionata.

È possibile creare il numero di app necessario per eseguire le chiamate API in ognuno degli ambienti di produzione.

Per creare un'altra app:

1. Seleziona Crea un'altra applicazione.
2. Compila i campi per creare la tua app, quindi seleziona Crea applicazione.

Gestire le applicazioni Microsoft Entra esistenti

Dopo aver creato le app Microsoft Entra, puoi gestirle tramite [portale di Azure](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps). Per ulteriori informazioni, vedere il sito della documentazione di Azure.

Chiamare le API in tempo reale di Fraud Protection

Utilizzare le informazioni in questa sezione per integrare i sistemi con Fraud Protection.

ID e informazioni necessarie

• Endpoint API - L'URI per l'ambiente appare nel riquadro Informazioni sull'account nel dashboard di Fraud Protection.
• ID directory (tenant) - L'ID directory è l'identificatore univoco globale (GUID) per il dominio di un tenant in Azure. Compare nel portale di Azure e nel riquadro Informazioni sull'account nel dashboard di Fraud Protection.
• ID applicazione (client): l'ID applicazione identifica l'app Microsoft Entra creata per chiamare le API. È possibile trovare questo ID nella pagina di conferma che appare dopo aver selezionato Crea applicazione nella pagina API in tempo reale. È disponibile anche in seguito, sotto Registrazioni app nel portale di Azure. Ci sarà un ID per ogni app creata.
• Identificazione digitale o segreto del certificato - È possibile trovare l'identificazione digitale o il segreto del certificato nella pagina di conferma che appare dopo aver selezionato Crea applicazione nella pagina API in tempo reale.
• ID istanza - L'ID istanza è l'identificatore univoco globale (GUID) per l'ambiente in Fraud Protection. Appare nel riquadro Integrazione nel dashboard di Fraud Protection.

Generare un token di accesso

È necessario generare questo token e fornirlo con ogni chiamata API. Si noti che i token di accesso hanno una durata limitata. È consigliabile memorizzare ogni token di accesso nella cache e riutilizzarlo finché non sia tempo per ottenere un nuovo token di accesso.

Il codice C# seguente fornisce esempi di acquisizione di un token utilizzando un certificato o un segreto. Sostituire i segnaposto con le informazioni specifiche.

Identificazione digitale certificato

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

Segreto

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

Risposta

In background, il codice precedente genera una richiesta HTTP e riceve una risposta simile al seguente esempio.

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

Per ulteriori informazioni, vedere la documentazione di Azure:

• Usare l'asserzione client per ottenere i token di accesso da Microsoft Entra ID
• Memorizzare nella cache i token di accesso

Chiamare le API

Per chiamare le API, eseguire la procedura seguente.

1. Passare le seguenti intestazioni HTTP obbligatorie per ogni richiesta.

   Nome intestazione	Valore intestazione
   Autorizzazione	Usare il formato seguente per questa intestazione: Bearer accesstoken, dove accesstoken è il token restituito da Microsoft Entra ID.
   x-ms-correlation-id	Invia un nuovo valore GUID in ogni set di chiamate API effettuate insieme.
   x-ms-dfpenvid	Invia il valore GUID del tuo ID istanza.

2. Genera un payload basato su evento. Compila i dati evento con le informazioni pertinenti dal sistema. Per le informazioni sugli eventi supportati, vedere API di Dynamics 365 Fraud Protection

3. Combina l'intestazione (che include il token di accesso) e il payload e quindi inviali all'endpoint di Fraud Protection

Visualizzare l'app di esempio

Per ulteriore riferimento, vedere l'app fornitore di esempio e la documentazione di sviluppo correlata. L'app di esempio fornisce un esempio che mostra come chiamare le API di Fraud Protection in tempo reale. La documentazione per l'app di esempio è collegata al codice di esempio effettivo ogni volta che tali collegamenti sono possibili. In caso contrario, esempi di codice sono presenti direttamente nella documentazione.

Per informazioni su come configurare il sito di esempio in modo da poterlo utilizzare, vedere Configurare il sito di esempio.