OAuth 認証を使用する Microsoft Dataverse

[アーティクル]
10/04/2024

OAuth 2.0 は、認証のための業界標準プロトコルです。アプリケーションユーザーが認証のために資格情報を提供すると、 OAuth リソースにアクセスする権限があるかどうかが判断されます。

クライアントアプリケーションは、Web APIを使用してデータにアクセスするために、 OAuth の使用をサポートする必要があります。 OAuth サーバー間アプリケーションシナリオで2要素認証 (2FA) または証明書ベースの認証を有効にします。

OAuth 認証にはIDプロバイダーが必要です。 Dataverse については、Microsoft Entra ID が ID プロバイダーとなります。 Microsoftの職場または学校アカウントを使用して認証するには、 Microsoft認証ライブラリ (MSAL) を使用します。

ヒント

このトピックでは、認証ライブラリを使用した接続に関連する一般的な概念を紹介します。 Dataverse OAuth このコンテンツでは、開発者が接続を実行する方法に重点を置きますが、ライブラリの内部動作については扱いません。 Dataverse OAuth 認証に関する完全な情報については、Microsoft Entra ID ドキュメントを参照してください。まず、「認証とは何か?」から始めましょう。

提供するサンプルは適切な登録値で事前に構成されているため、独自のアプリ登録を生成せずに実行できます。独自のアプリを公開する場合は、独自の登録値を使用する必要があります。

アプリの登録

OAuthを使用して接続する場合は、まず Microsoft Entra IDテナントにアプリケーションを登録する必要があります。アプリを登録する方法は、作成するアプリの種類によって異なります。

いずれの場合も、次の記事で説明されているアプリを登録するための基本的な手順から始めてください: クイックスタート: Microsoft IDプラットフォームにアプリケーションを登録する。具体的な手順については、「チュートリアル: IDを使用してアプリを登録する」を参照してください。 Dataverse Microsoft Entra

このステップで実行する必要のある決定のほとんどは、アプリケーションの種類の選択に依存します (以下を参照)。

アプリ登録の種類

Microsoft Entra ID にてアプリケーションを登録する際には、アプリケーションの種別を選択する必要があります。登録できるアプリケーションには 2 種類あります。

アプリケーションの種類	説明
Web アプリ /API	ウェブクライアントすべてのコードをWebサーバー上で実行するクライアントアプリケーションの一種。ユーザーエージェントベースのクライアントシングルページアプリケーション (SPA) など、Webサーバーからコードをダウンロードし、ユーザーエージェント (Webブラウザーなど) 内で実行するクライアントアプリケーションの一種。
ネイティブモード	デバイスにネイティブにインストールされるクライアントアプリケーションの一種。

アプリケーションの種類

説明

Web アプリ /API

ウェブクライアント
すべてのコードをWebサーバー上で実行するクライアントアプリケーションの一種。

ユーザーエージェントベースのクライアント
シングルページアプリケーション (SPA) など、Webサーバーからコードをダウンロードし、ユーザーエージェント (Webブラウザーなど) 内で実行するクライアントアプリケーションの一種。

ネイティブモード

デバイスにネイティブにインストールされるクライアントアプリケーションの一種。

選択 Webアプリ /API を使用する場合は、 サインオンURL を指定する必要があります。これは、 Microsoft Entra IDが認証応答を送信するURLであり、認証が成功した場合はトークンも含まれます。アプリを開発している間、このURLは通常 https://localhost/appname:[port] に設定されるため、アプリをローカルで開発およびデバッグできます。アプリを公開する場合、アプリの公開された URL へのこの値を変更する必要があります。

選択 ネイティブ を使用する場合は、リダイレクトURIを指定する必要があります。このURLは、 Microsoft Entra IDが OAuth 2.0リクエストでユーザーエージェントをリダイレクトする一意の識別子です。このURLは通常、 app://<guid> のような形式の値です。

Dataverse へのアクセス権を付与する

アプリが、認証されたユーザーが操作を実行できるクライアントである場合、アクセス許可を委任された組織のユーザーとして Dynamics 365 にアクセスするようアプリケーションを構成する必要があります。

権限を設定するための具体的な手順については、「 IDを使用してアプリを登録する Microsoft Entra 」を参照してください。

アプリがサーバー間 (S2S) の認証を使用する場合、この手順は必要ありません。その構成には特定のシステムユーザーが必要であり、操作は認証が必要な任意のユーザーではなく、そのユーザーアカウントにより実行されます。

クライアントシークレット & 証明書の使用

サーバ間のシナリオでは、認証する対話型ユーザーアカウントはありません。このような場合、アプリケーションが信頼できることを確認するためのいくつかの手段を提供する必要があります。これはクライアントシークレットまたは証明書を使用して実行されます。

Webアプリ /API アプリケーションタイプに登録されているアプリの場合は、シークレットを構成できます。これらは、アプリ登録の設定の APIアクセス のキー領域を使用して設定されます。

どちらのアプリケーションの種類でも、証明書をアップロードできます。

詳細情報: 接続アプリ

認証ライブラリを使用して接続する

MicrosoftがサポートするID認証クライアントライブラリの1つを使用して、 Microsoft Entra たとえば Dataverse Microsoft認証ライブラリ (MSAL) にアクセスします。提供されたリンクでの説明にあるように、このライブラリはさまざまなプラットフォームで利用できます。

ヒント

Azure Active Directory 認証ライブラリ (ADAL) は現在アクティブに更新されておらず、2022 年 6 月までのみサポートされる予定です。 MSAL は、プロジェクトで使用するように推奨される認証ライブラリです。

認証にMSALライブラリを使用する方法を示すコードサンプルについては、 Dataverse 「クイックスタートサンプル」を参照してください。

.NET クライアントライブラリ

Dataverse OAuth 2.0プロトコルを使用したWeb APIエンドポイントによるアプリケーション認証をサポートします。カスタム .NET アプリケーションの場合、Web API エンドポイントでのアプリケーション認証に MSAL を使用します。

Dataverse SDK for .NETには、認証を処理するクライアントクラス CrmServiceClient と ServiceClient が含まれています。 CrmServiceClient クラスは現在、認証にADALを使用していますが、 ServiceClient MSALも使用しています。これらのクライアントを使用するアプリケーションコードを書き込むと、認証を直接管理する必要がなくなります。どちらのクライアントも、SDK および Web API エンドポイントで動作します。

要求で AccessToken を使用します

認証ライブラリを使用するポイントは、要求に含めることができるアクセストークンを取得することです。トークンを取得するには数行のコードのみが必要で、リクエストを実行するために HttpClient を構成するにはさらに数行必要です。

重要

この記事のサンプルコードに示されているように、パブリッククライアントには "<environment-url>/user_impersonation" スコープを使用します。機密クライアントの場合は、「<environment-url>/.default」のスコープを使用します。

単純な例

単一の Web API 要求を実行するために必要な最小コード数は次のとおりですが、推奨されている方法ではありません。このコードはMSALライブラリを使用し、 QuickStart サンプルから取得されていることに注意してください。

string resource = "https://contoso.api.crm.dynamics.com";
var clientId = "51f81489-12ee-4a9e-aaae-a2591f45987d";
var redirectUri = "http://localhost"; // Loopback for the interactive login.

// MSAL authentication
var authBuilder = PublicClientApplicationBuilder.Create(clientId)
    .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
    .WithRedirectUri(redirectUri)
    .Build();
var scope = resource + "/user_impersonation";
string[] scopes = { scope };

AuthenticationResult token =
    authBuilder.AcquireTokenInteractive(scopes).ExecuteAsync().Result;

// Set up the HTTP client
var client = new HttpClient
{
    BaseAddress = new Uri(resource + "/api/data/v9.2/"),
    Timeout = new TimeSpan(0, 2, 0)  // Standard two minute timeout.
};

HttpRequestHeaders headers = client.DefaultRequestHeaders;
headers.Authorization = new AuthenticationHeaderValue("Bearer", token.AccessToken);
headers.Add("OData-MaxVersion", "4.0");
headers.Add("OData-Version", "4.0");
headers.Accept.Add(
    new MediaTypeWithQualityHeaderValue("application/json"));

// Web API call
var response = client.GetAsync("WhoAmI").Result;

この単純なアプローチは、 token が約1時間で期限切れになるため、追従するにとって適切なパターンとは言えません。 MSALライブラリはトークンをキャッシュし、 AcquireTokenInteractive メソッドが呼び出されるたびにトークンを更新します。ただし、この単純な例ではトークンを 1 回だけ取得しています。

委任メッセージハンドラーを示す例

推奨される方法は、 DelegatingHandler から派生したクラスを実装し、 HttpClient のコンストラクターに渡すことです。このハンドラを使用すると、 HttpClient.SendAsync メソッドをオーバーライドして、アクセストークンが、Httpクライアントから送信される各リクエストで AcquireToken* メソッド呼び出しによって更新されるようになります。

以下は、 DelegatingHandler から派生したカスタムクラスの例です。このコードは、MSAL認証ライブラリを使用する Enhanced QuickStart サンプルから取得されています。

class OAuthMessageHandler : DelegatingHandler
{
    private AuthenticationHeaderValue authHeader;
    public OAuthMessageHandler(string serviceUrl, string clientId, string redirectUrl, string username, string password,
            HttpMessageHandler innerHandler)
        : base(innerHandler)
    {
        string apiVersion = "9.2";
        string webApiUrl = $"{serviceUrl}/api/data/v{apiVersion}/";
        var authBuilder = PublicClientApplicationBuilder.Create(clientId)
                        .WithAuthority(AadAuthorityAudience.AzureAdMultipleOrgs)
                        .WithRedirectUri(redirectUrl)
                        .Build();
        var scope = serviceUrl + "/user_impersonation";
        string[] scopes = { scope };
        // First try to get an authentication token from the cache using a hint.
        AuthenticationResult authBuilderResult=null;
        try
        {
            authBuilderResult = authBuilder.AcquireTokenSilent(scopes, username)
               .ExecuteAsync().Result;
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine(
                $"Error acquiring auth token from cache:{System.Environment.NewLine}{ex}");
            // Token cache request failed, so request a new token.
            try
            {
                if (username != string.Empty && password != string.Empty)
                {
                    // Request a token based on username/password credentials.
                    authBuilderResult = authBuilder.AcquireTokenByUsernamePassword(scopes, username, password)
                                .ExecuteAsync().Result;
                }
                else
                {
                    // Prompt the user for credentials and get the token.
                    authBuilderResult = authBuilder.AcquireTokenInteractive(scopes)
                                .ExecuteAsync().Result;
                }
            }
            catch (Exception msalex)
            {
                System.Diagnostics.Debug.WriteLine(
                    $"Error acquiring auth token with user credentials:{System.Environment.NewLine}{msalex}");
                throw;
            }
        }
        //Note that an Microsoft Entra ID access token has finite lifetime, default expiration is 60 minutes.
        authHeader = new AuthenticationHeaderValue("Bearer", authBuilderResult.AccessToken);
    }

    protected override Task<HttpResponseMessage> SendAsync(
              HttpRequestMessage request, System.Threading.CancellationToken cancellationToken)
    {
        request.Headers.Authorization = authHeader;
        return base.SendAsync(request, cancellationToken);
    }
}

この OAuthMessageHandler クラスを使用すると、単純な Main メソッドは次のようになります。

class Program
{
    static void Main(string[] args)
    {
        try
        {
            //Get configuration data from App.config connectionStrings
            string connectionString = ConfigurationManager.ConnectionStrings["Connect"].ConnectionString;

            using (HttpClient client = SampleHelpers.GetHttpClient(connectionString, SampleHelpers.clientId,
                SampleHelpers.redirectUrl))
            {
                // Use the WhoAmI function
                var response = client.GetAsync("WhoAmI").Result;

                if (response.IsSuccessStatusCode)
                {
                    //Get the response content and parse it.
                    JObject body = JObject.Parse(response.Content.ReadAsStringAsync().Result);
                    Guid userId = (Guid)body["UserId"];
                    Console.WriteLine("Your UserId is {0}", userId);
                }
                else
                {
                    Console.WriteLine("The request failed with a status of '{0}'",
                                response.ReasonPhrase);
                }
                Console.WriteLine("Press any key to exit.");
                Console.ReadLine();
            }
        }
        catch (Exception ex)
        {
            SampleHelpers.DisplayException(ex);
            Console.WriteLine("Press any key to exit.");
            Console.ReadLine();
        }
    }
}

構成文字列の値はApp.configファイルの接続文字列に移動され、Httpクライアントは GetHttpClient メソッドで構成されます。

public static HttpClient GetHttpClient(string connectionString, string clientId, string redirectUrl, string version = "v9.2")
{
    string url = GetParameterValueFromConnectionString(connectionString, "Url");
    string username = GetParameterValueFromConnectionString(connectionString, "Username");
    string password = GetParameterValueFromConnectionString(connectionString, "Password");
    try
    {
        HttpMessageHandler messageHandler = new OAuthMessageHandler(url, clientId, redirectUrl, username, password,
                        new HttpClientHandler());

        HttpClient httpClient = new HttpClient(messageHandler)
        {
            BaseAddress = new Uri(string.Format("{0}/api/data/{1}/", url, version)),

            Timeout = new TimeSpan(0, 2, 0)  //2 minutes
        };

        return httpClient;
    }
    catch (Exception)
    {
        throw;
    }
}

完全なコードについては、 Enhanced QuickStart サンプルを参照してください。

この例では、オーバーライドされた HttpClientではなくGetAsync . SendAsyncを使用していますが、リクエストを送信する HttpClient メソッドのいずれにも適用されます。

アプリとして接続

作成する一部のアプリは、ユーザーが対話的に実行するためのものではありません。たとえば、Dataverse データに対する操作を実行できる Web クライアントアプリケーションや、あるスケジュールに基づいたタスクを実行するコンソールアプリケーションを作成するなどのケースが考えられます。

一般のユーザーの資格情報を使用してこれらのシナリオを実行することはできますが、そのユーザーアカウントでは有料ライセンスを使用する必要があります。これは推奨されている方法ではありません。

このような場合、ID登録済みアプリケーションにバインドされた特別なアプリケーションユーザーを作成し、アプリケーション用に構成されたキーシークレットを使用するか、X.509証明書をアップロードすることができます。 Microsoft Entra この方法の別の利点は、有料ライセンスを使用しないことです。

アプリとして接続するための要求

アプリとして接続するには以下の点が必要です。

登録済みアプリ
登録されたアプリにバインドされた Dataverse ユーザー
アプリケーションシークレットまたは証明書サムプリントのいずれかを使用して接続する

アプリの登録

アプリを登録するときは、「チュートリアル: IDを使用してアプリを登録する Microsoft Entra 」で説明されているのと同じ手順の多くを実行しますが、次の例外があります。

組織ユーザーとしてDynamics 365にアクセスする 権限を付与する必要はありません。

このアプリケーションは特定のユーザーアカウントにバインドされます。
アプリ登録のシークレットを構成するか、公開キー証明書をアップロードする必要があります。

アプリ登録の「 証明書とシークレットの管理>」で資格情報を作成または表示できます。

証明書（公開鍵）を追加するには:

[証明書] タブで、選択 [証明書をアップロード]します。
アップロードするファイルを選択します。次のいずれかのファイルの種類である必要があります: .cer、.pem、.crt。
説明を入力します。
追加を選択します。

クライアントシークレット (アプリケーションパスワード) を追加するには:

クライアントシークレット タブで、クライアントシークレットの説明を追加します。
選択有効期限。
追加を選択します。

重要

設定の変更を保存すると、秘密の値が表示されます。ページを離れるとその値にアクセスできなくなるため、クライアントアプリケーションコードで使用するためにシークレット値を必ずコピーしてください。

詳細情報: 資格情報の追加

登録されたアプリにバインドされた Dataverse のユーザーアカウント

最初に必須となる作業は、セキュリティ役割のカスタマイズです。ここで Dataverse の内部でこのアカウントにどのようなアクセス権や権限を付与するかを定義します。詳細情報: カスタムセキュリティロールを作成または構成する

ユーザー定義セキュリティロールを作成した後、使用するユーザーアカウントを作成する必要があります。

Dataverse アプリケーションユーザーを手動で作成します

アプリケーションユーザーを作成する手順については、管理 Power Platform の記事「アプリケーションユーザーの作成」を参照してください。

アプリケーションユーザーを作成したら、作成したカスタムセキュリティロールにアプリケーションユーザーを関連付けます。

アプリケーションシークレットを使用して接続する

クライアントシークレットを使用して接続し、 Microsoft.Xrm.Tooling.Connector.CrmServiceClient を使用する場合は、次のようなコードを使用できます。

string SecretID = "00000000-0000-0000-0000-000000000000";
string AppID = "545ce4df-95a6-4115-ac2f-e8e5546e79af";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=ClientSecret;
                        SkipDiscovery=true;url={InstanceUri};
                        Secret={SecretID};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

証明書サムプリントを使用して接続する

証明書を使用して接続し、 Microsoft.Xrm.Tooling.Connector.CrmServiceClient を使用する場合は、次のようなコードを使用できます。

string CertThumbPrintId = "DC6C689022C905EA5F812B51F1574ED10F256FF6";
string AppID = "545ce4df-95a6-4115-ac2f-e8e5546e79af";
string InstanceUri = "https://yourorg.crm.dynamics.com";

string ConnectionStr = $@"AuthType=Certificate;
                        SkipDiscovery=true;url={InstanceUri};
                        thumbprint={CertThumbPrintId};
                        ClientId={AppID};
                        RequireNewInstance=true";
using (ServiceClient svc = new ServiceClient(ConnectionStr))
{
    if (svc.IsReady)
    {
    //your code goes here
    }

}

次の方法で共有

OAuth 認証を使用する Microsoft Dataverse

アプリの登録

アプリ登録の種類

Dataverse へのアクセス権を付与する

クライアントシークレット & 証明書の使用

認証ライブラリを使用して接続する

.NET クライアントライブラリ

要求で AccessToken を使用します

単純な例

委任メッセージハンドラーを示す例

アプリとして接続

アプリとして接続するための要求

アプリの登録

登録されたアプリにバインドされた Dataverse のユーザーアカウント

Dataverse アプリケーションユーザーを手動で作成します

アプリケーションシークレットを使用して接続する

証明書サムプリントを使用して接続する

関連項目

フィードバック

その他のリソース

次の方法で共有

OAuth 認証を使用する Microsoft Dataverse

アプリの登録

アプリ登録の種類

Dataverse へのアクセス権を付与する

クライアント シークレット & 証明書の使用

認証ライブラリを使用して接続する

.NET クライアント ライブラリ

要求で AccessToken を使用します

単純な例

委任メッセージ ハンドラーを示す例

アプリとして接続

アプリとして接続するための要求

アプリの登録

登録されたアプリにバインドされた Dataverse のユーザー アカウント

Dataverse アプリケーション ユーザーを手動で作成します

アプリケーション シークレットを使用して接続する

証明書サムプリントを使用して接続する

関連項目

フィードバック

その他のリソース

クライアントシークレット & 証明書の使用

.NET クライアントライブラリ

委任メッセージハンドラーを示す例

登録されたアプリにバインドされた Dataverse のユーザーアカウント

Dataverse アプリケーションユーザーを手動で作成します

アプリケーションシークレットを使用して接続する