アカウント保護 API を統合する

2025-05-07

重要

2025 年 2 月 3 日の時点で、Dynamics 365 Fraud Protection は購入できなくなります。不正アクセス防止のサポートは、2026 年 2 月 3 日に終了します。詳細については、「Dynamics 365 Fraud Protection のサポート終了」記事を参照してください。

Microsoft Dynamics 365 Fraud Protection の完全な機能スイートを利用するには、トランザクションデータをリアルタイムアプリケーションプログラミングインターフェイス (API) に送信します。評価エクスペリエンスでは、不正アクセス防止を使用した結果を分析できます。保護エクスペリエンスでは、構成した規則に基づく決定を受け入れることもできます。

不正アクセス防止の使用方法に応じて、さまざまな アカウント保護 API を使用できます。たとえば、 AccountCreation、 AccountLogin、 AccountCreationStatus、 AccountLoginStatus、 AccountUpdate、 Label などです。

サポートされているすべてのイベントの詳細については、「 Dynamics 365 Fraud Protection API」を参照してください。

セットアップ

重要

最初の API オンボードを完了するには、Microsoft Azure テナントの全体管理者である必要があります。

Fraud Protection ポータルに移動し、サインインし、同意するように求められたら使用条件に同意します。

この手順により、Azure テナントで Fraud Protection が正しく構成されます。 (最初のサインアップ中に既にこの手順を完了している可能性があります)。

Microsoft Entra アプリケーションを作成する

重要

この手順を完了するには、Azure テナントのアプリケーション管理者、クラウドアプリケーション管理者、またはグローバル管理者である必要があります。

API を呼び出すために必要なトークンを取得するには、Microsoft Entra アプリケーションを使用する必要があります。これらのアプリは、Fraud Protection の [リアルタイム API] ページを使用して構成できます。

Microsoft Entra アプリを構成するには:

左側のナビゲーションウィンドウで、[ 構成] を選択し、[ リアルタイム API] を選択します。
項目に入力してアプリを作る。必須のフィールドを次に示します。
- アプリケーションの表示名 – アプリのわかりやすい名前を入力します。最大長は 93 文字です。
- 環境 – 運用エンドポイントを選択します。
- 認証方法 – 認証 に証明書またはシークレット (パスワード) を使用するかどうかを選択します。 [ 証明書] を選択した場合は、[ ファイルの選択 ] を選択して公開キーをアップロードします。トークンを取得するときは、一致する秘密キーが必要です。 [シークレット] を選択すると、アプリの作成後にパスワードが生成されます。
フィールドの入力が完了したら、[ アプリケーションの作成] を選択します。

確認ページには、選択した認証方法に応じて、アプリの名前と ID、および証明書の拇印またはシークレットが要約されます。

重要

今後参照するために、証明書の拇印またはシークレットに関する情報を保存します。シークレットは 1 回だけ表示されます。

運用環境で API 呼び出しを実行するために必要な数のアプリを作成できます。

別のアプリを作成するには:

[ 別のアプリケーションの作成] を選択します。
フィールドに入力してアプリを作成し、 アプリケーションの作成を選択します。

既存の Microsoft Entra アプリケーションを管理する

Microsoft Entra アプリを作成したら、[Azure portal](https://portal.azure.com/#blade/Microsoft_Microsoft Entra ID_IAM/ActiveDirectoryMenuBlade/RegisteredApps) から管理できます。詳細については、 Azure のドキュメントサイトを参照してください。

不正アクセス防止のリアルタイム API を呼び出す

このセクションの情報を使用して、システムを Fraud Protection と統合します。

必要な ID と情報

API エンドポイント – 環境の URI は、Fraud Protection ダッシュボードの Account 情報 タイルに表示されます。
ディレクトリ (テナント) ID – ディレクトリ ID は、Azure 内のテナントのドメインのグローバル一意識別子 (GUID) です。これは、Azure portal と、不正アクセス防止ダッシュボードの Account 情報 タイルに表示されます。
アプリケーション (クライアント) ID – アプリケーション ID は、API を呼び出すために作成した Microsoft Entra アプリを識別します。この ID は、[リアルタイム API] ページで [アプリケーションの作成] を選択した後に表示される確認ページで確認できます。後で Azure portal の [アプリの登録] で確認することもできます。作成したアプリごとに 1 つの ID があります。
証明書の拇印またはシークレット – [リアルタイム API] ページで [アプリケーションの作成] を選択した後に表示される確認ページで、証明書の拇印またはシークレットを確認できます。
インスタンス ID - インスタンス ID は、Fraud Protection の環境のグローバル一意識別子 (GUID) です。不正アクセス防止ダッシュボードの Integration タイルに表示されます。

アクセストークンを生成する

このトークンを生成し、各 API 呼び出しで提供する必要があります。アクセストークンの有効期間が制限されていることに注意してください。新しいアクセストークンを取得するまで、各アクセストークンをキャッシュして再利用することをお勧めします。

次の C# コードサンプルでは、証明書またはシークレットを使用してトークンを取得する方法を示す例を示します。独自の情報を使用してプレースホルダーを置き換えてください。

証明書の拇印

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

シークレット

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

応答

上記のコードはバックグラウンドで HTTP 要求を生成し、次の例のような応答を受け取ります。

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

詳細については、Azure のドキュメントを参照してください。

API を呼び出す

API を呼び出すには、次の手順に従います。

次の必須 HTTP ヘッダーを各要求に渡します。

ヘッダー名	ヘッダーの値
認証	このヘッダーには、 Bearer accesstoken という形式を使用します。ここで、 accesstoken は Microsoft Entra ID によって返されるトークンです。
x-ms-correlation-id	一緒に作成した各 API 呼び出しセットで新しい GUID 値を送信します。
x-ms-dfpenvid	インスタンス ID の GUID 値を送信します。

イベントベースのペイロードを生成します。イベントデータにシステムの関連情報を入力します。サポートされているすべてのイベントの詳細については、「 Dynamics 365 Fraud Protection API」を参照してください。
ヘッダー (アクセストークンを含む) とペイロードを組み合わせて、Fraud Protection エンドポイントに送信します。

注

新しい環境を作成する場合は、統合時に API ヘッダーに環境 ID を含めて、トランザクションを正しくルーティングできるようにします。

サンプルアプリを表示する

その他のリファレンスについては、サンプルのマーチャントアプリを参照し、付属の開発者向けドキュメントを参照してください。このサンプルアプリでは、Fraud Protection API をリアルタイムで呼び出す方法を示す例を示します。サンプルアプリのドキュメントは、リンクが可能な場合は常に実際のサンプルコードにリンクされます。それ以外の場合は、コードサンプルがドキュメントに直接含まれます。

サンプルサイトを使用できるように構成する方法については、「サンプルサイトの構成」を参照してください。

次の方法で共有

アカウント保護 API を統合する

セットアップ

サインイン

Fraud Protection にサインインするには:

Microsoft Entra アプリケーションを作成する

Microsoft Entra アプリを構成するには:

別のアプリを作成するには:

既存の Microsoft Entra アプリケーションを管理する

不正アクセス防止のリアルタイム API を呼び出す

必要な ID と情報

アクセス トークンを生成する

API を呼び出す

サンプル アプリを表示する

フィードバック

その他のリソース

アクセストークンを生成する

サンプルアプリを表示する