ODBC Driver for Microsoft Dynamics 365

Build 22.0.8479

macOS DSN の構成

このセクションでは、macOS でODBC 接続をセットアップしDSN を設定する方法を示します：

macOS の最小バージョン

CData ODBC Driver for Microsoft Dynamics 365 本製品 にはmacOS Sierra (10.12) 以上が必要です。

ドライバーのライセンス

端末で次のコマンドを実行して、本製品 のライセンスを取得します。評価版をアクティベートするには、<key> の入力を省略してください。 

cd "/Applications/CData ODBC Driver for Microsoft Dynamics 365/bin"
sudo ./install-license.sh <key>

名前とパスワードを入力するよう求められます。これらは、あなたの名前とマシンのパスワードを指します。

Microsoft Dynamics 365 への接続

接続には、Edition およびOrganizationUrl 接続プロパティが必須です。Microsoft Dynamics 365 ドライバーは、以下のMicrosoft Dynamics 365 エディションへの接続をサポートしています。

  • CustomerService
  • FieldService
  • FinOpsOnline
  • FinOpsOnPremise
  • HumanResources
  • Marketing
  • ProjectOperations
  • Sales

なお、"Supply Chain Management" は"Finance and Operations" と同一であることに注意してください。Edition を"FinOpsOnline" または"FinOpsOnPremise" のいずれかに設定することで接続できます。

Microsoft Dynamics 365 Business Central については、個別のMicrosoft Dynamics 365 Business Central ドライバーを使用してください。

OrganizationUrl は、Microsoft Dynamics 365 組織へのURL です。例：https://orgcb42e1d0.crm.dynamics.com

Microsoft Dynamics 365 への認証

OAuth

If required by your organization, Admin Consent is needed when authorizing a new OAuth application for your Azure Tenant. In all OAuth flows, the first time someone in your organization installs and uses an OAuth application, an administrator for the organization must approve the application for their Azure Tenant.

Your organization can choose, however, to disable this requirement.

デスクトップアプリケーション

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムAzureAD アプリの作成 を参照してください。

認証に関する2つの方法の違いは、カスタムOAuth アプリケーションを使用する場合に、2つの接続プロパティを追加で設定する必要があることだけです。 次の接続プロパティを設定して、接続してください。

  • AuthScheme：アプリケーション設定のAzureAD に設定。
  • OAuthClientId：（カスタムアプリケーションのみ）アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーション設定のクライアントシークレットに設定。
  • CallbackURL：アプリケーション設定のリダイレクトURL に設定。

接続すると、本製品 はデフォルトブラウザでOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。

Web アプリケーション

Web アプリケーション経由で接続する場合は、Microsoft Dynamics 365 にカスタムOAuth アプリケーションを作成および登録する必要があります。カスタムアプリケーションについて詳しくは、カスタムAzureAD アプリの作成 を参照してください。それから本製品 を使用してOAuth トークンの値を取得および管理します。 OAuth アクセストークンの取得

次の接続プロパティを設定し、OAuthAccessToken を取得します。

  • AuthScheme：AzureAD に設定。
  • OAuthClientId：アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。

  1. GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したコールバックURL に設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。

    ストアドプロシージャがOAuth エンドポイントのURL を返します。

  2. URL を開き、ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
  3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、コールバックURL のクエリ文字列の"code" パラメータに設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。

アクセストークンとリフレッシュトークンを取得すると、データに接続し、OAuth アクセストークンを自動または手動でリフレッシュすることができるようになります。

OAuth アクセストークンの自動リフレッシュ

ドライバーがOAuth アクセストークンを自動的にリフレッシュするようにするには、最初のデータ接続で次のように設定します。

  • InitiateOAuth：REFRESH に設定。
  • OAuthClientId：アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
  • OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークンに設定。
  • OAuthRefreshToken：GetOAuthAccessToken によって返されたリフレッシュトークンに設定。
  • OAuthSettingsLocation：本製品 がOAuth トークン値を保存する場所のパスを設定。これは接続間で維持されます。
次回のデータ接続では、OAuthAccessToken およびOAuthRefreshToken の値は、OAuthSettingsLocation から取得されます。

OAuth アクセストークンの手動リフレッシュ

データ接続時に手動でOAuth アクセストークンをリフレッシュするために必要な値は、OAuth リフレッシュトークンのみです。

GetOAuthAccessToken によって返されたExpiresIn パラメータ値が経過した後に、RefreshOAuthAccessToken ストアドプロシージャを使用し、手動でOAuthAccessToken をリフレッシュします。次の接続プロパティを設定します。

  • OAuthClientId：アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

次に、RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを指定します。新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定し、新しい接続をオープンします。

最後に、OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

  1. 以下の2つのオプションから選択します。
    • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
    • オプション2：別のマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
  2. その後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

カスタムOAuth アプリのOAuth クレデンシャルを使用して、ヘッドレスOAuth 認証フローに従うことができます。カスタムOAuth アプリケーションを作成するには、カスタムAzureAD アプリの作成 を参照してください。このセクションでは、データの認証および接続を行う手順について説明します。

オプション1：Verifier code を取得および交換

まず最初に、ヘッドレスマシンで次のプロパティを設定します。

  • InitiateOAuth：OFF に設定。
  • OAuthClientId：OAuth 統合設定のクライアントID に設定。
  • OAuthClientSecret：OAuth 統合設定のクライアントシークレットに設定。

次に、別のマシンから認証して 接続プロパティを取得します。

  1. GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットにアプリ設定で指定したリダイレクトURI を設定します。ストアドプロシージャは、OAuth エンドポイントへのURL とPKCEVerifier を返します。
  2. 返されたURL をブラウザで開きます。ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
  3. Verifier の値とPKCEVerifier の値を保存します。 接続プロパティにVerifier の値を設定し、 接続プロパティにPKCEVerifier の値を設定する必要があります。

最後に、ヘッドレスマシンで、次の接続プロパティを設定してOAuth 認証値を取得します。

  • OAuthClientId：OAuth 統合設定のクライアントID に設定。
  • OAuthClientSecret：OAuth 統合設定のクライアントシークレットに設定。
  • OAuthVerifier：verifier code に設定。
  • OAuthSettingsLocation：暗号化されたOAuth 認証値を指定されたファイルに永続化。
  • InitiateOAuth：REFRESH に設定。

データへの接続

OAuth 設定ファイルが生成されたら、次のプロパティを設定してデータに接続します。

  • OAuthSettingsLocation：暗号化されたOAuth 認証値を含むファイルに設定。アクセストークンの自動リフレッシュを有効にするために、このファイルがプロバイダーに読み書きのアクセス許可を与えることを確認してください。
  • InitiateOAuth：REFRESH に設定。

オプション2：OAuth 設定を転送

別のマシンに本製品 をインストールするには、認証してから、結果のOAuth 値を転送します。

  1. セカンドマシンに、本製品 をインストールして、次の接続プロパティセットで接続します。
    • OAuthSettingsLocation：書き込み可能なテキストファイルに設定。
    • OAuthClientId：アプリケーション設定のクライアントID に設定。
    • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
    • CallbackURL：アプリケーション設定のコールバックURL に設定。
  2. 認証する接続をテストします。生成された認証値は、OAuthSettingsLocation で指定されたパスに書き込まれて暗号化されます。接続テストに成功したら、OAuth 設定ファイルをヘッドレスマシンにコピーします。ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。
    • InitiateOAuth：REFRESH に設定。
    • OAuthSettingsLocation：OAuth 設定ファイルのパスに設定。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。

管理者の同意

管理者の同意 とは、Azure Active Directory テナントの管理者が、管理者の同意を必要とするアプリケーションに権限を付与することを指します。 CData ODBC Driver for Microsoft Dynamics 365 内の埋め込みアプリには、管理者の同意を必要とするアクセス許可はありません。したがって、この情報はカスタムアプリケーションにのみ適用されます。

管理者の同意の付与

Azure ポータルで新しいOAuth アプリを作成する場合には、アプリに必要なアクセス許可を指定する必要があります。一部のアクセス許可には、「管理者の同意が必要」と記載されている場合があります。 例えば、すべてのグループのアクセス許可には管理者の同意が必要です。アプリに管理者の同意が必要な場合、いくつかの方法があります。

管理者の同意を付与する最も簡単な方法は、管理者がportal.azure.com にログインして、［アプリの登録］で作成したアプリに移動するだけです。［API のアクセス許可］に、 ［管理者の同意の付与］ボタンがあります。ここで、アプリが作成されたテナントでアクセス許可を持つことに同意できます。

組織に複数のテナントがある場合、またはアプリが組織外の他のテナントにアクセス許可を与える必要がある場合、GetAdminConsentURL を使用してAdmin Authorization URL を生成できます。 GetOAuthAuthorizationUrl とは異なり、このエンドポイントから返される重要な情報はありません。アクセスを許可すると、許可が付与されたことを示すboolean を返します。

管理者が同意すると、通常通り認証を行うことができます。

クライアントクレデンシャル

クライアント資格情報は、直接ユーザー認証が行われないOAuth のフローを指します。代わりに、資格情報はアプリ自体のためだけに作成されます。 アプリで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。そのため、認証フローが標準とは少し違ったものになります。

クライアントOAuth フロー

クライアントOAuth フローに関連するすべての権限には、管理者の同意が必要です。これは、CData ODBC Driver for Microsoft Dynamics 365 が埋め込まれたアプリをクライアントOAuth フローでは使用できないことを意味します。クライアント資格情報を使用するには、独自のOAuth アプリの作成が必要になります。 詳しくは、カスタムAzureAD アプリの作成 を参照してください。

portal.azure.com の［アプリの登録］で［API のアクセス許可］に移動し、［Microsoft Graph］アクセス許可を選択します。アクセス許可には、委任されたアクセス許可とアプリケーションの許可の2つの異なるアクセス許可セットがあります。 クライアントの資格情報認証時に使用されるアクセス許可は、［アプリケーションの許可］の下にあります。インテグレーションに必要なアクセス許可を選択します。

認証タイプに応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

  1. クライアントシークレット
    • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthGrantType：CLIENT に設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
  2. 証明書
    • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthGrantType：CLIENT に設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthJWTCert：JWT 証明書ストアを設定。
    • OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

Azure AD

Azure AD は、OAuth を使用して認証する接続タイプです。AuthScheme をAzureAD に設定します。

下記の手順に従って、カスタムAzureAD アプリの資格情報を使用して認証します。カスタムAzureAD アプリの作成 を参照してください。

アプリの認証には、クライアントシークレットを使用する方法と、証明書を使用する方法の2種類があります。 設定されたアプリ認証に応じて、いずれかを使用できます。 AzureAD アクセストークンの取得

認証タイプに応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

  1. クライアントシークレット
    • AuthScheme：アプリ設定の"AzureServicePrincipal" に設定。
    • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、AzureAD 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。
  2. 証明書
    • AuthScheme：アプリ設定の"AzureServicePrincipal" に設定。
    • InitiateOAuth：GETANDREFRESH に設定。InitiateAzureAD を使うと、AzureAD 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthJWTCert：JWT 証明書ストアを設定。
    • OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

Azure サービスプリンシパル

Azure サービスプリンシパルは、OAuth を経由する接続タイプです。AuthScheme をAzureServicePrincipal に設定します。

Azure サービスプリンシパルとしての認証は、OAuth クライアントクレデンシャルフローを介して処理されます。直接のユーザー認証は行われません。代わりに、クレデンシャルはアプリケーション自体のためだけに作成されます。アプリで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。 Azure アプリとAzure サービスプリンシパルの作成 Azure サービスプリンシパルを使用して認証する場合、Azure AD テナントにアプリケーションを登録する必要があります。詳しくは、カスタムAzureAD サービスプリンシパルアプリの作成 を参照してください。 アプリケーションへのロールの割り当て サブスクリプションのリソースにアクセスするには、アプリケーションにロールを割り当てる必要があります。

  1. 検索バーでサブスクリプションサービスを検索・選択して、［サブスクリプション］ページを開きます。
  2. アプリケーションを割り当てる特定のサブスクリプションを選択します。
  3. ［アクセス制御 (IAM)］を開き、［追加］->［ロール割り当ての追加］を選択して［ロール割り当ての追加］ページを開きます。
  4. 作成したAzure AD アプリに割り当てるロールとして、［所有者］を選択します。
認証の完了 設定されたアプリ認証（クライアントシークレットまたは証明書）に応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

クライアントシークレットか証明書認証を選択する前に、まず以下の手順に従って設定を行います。その後、該当するセクションの設定に進んでください。

  1. AuthScheme：アプリ設定のAzureServicePrincipal に設定。
  2. InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
  3. AzureTenant：接続するテナントに設定。
  4. OAuthClientId：アプリ設定のクライアントId に設定。
クライアントシークレット

続いて、以下を設定します。

  1. OAuthClientId：アプリ設定のクライアントId に設定。
  2. OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。

証明書

続いて、以下を設定します。

  1. OAuthJWTCert：JWT 証明書ストアを設定。
  2. OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

下記の手順に従って、AzureAD アプリの資格情報を使用して認証します。カスタムAzureAD サービスプリンシパルアプリの作成 を参照してください。

AzureAD サービスプリンシパルアプリ

アプリの認証には、クライアントシークレットを使用する方法と、証明書を使用する方法の2種類があります。 設定されたアプリ認証に応じて、いずれかを使用できます。 AzureAD アクセストークンの取得

認証タイプに応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。

  1. クライアントシークレット
    • AuthScheme：アプリ設定の"AzureServicePrincipal" に設定。
    • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、AzureAD 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthClientSecret：アプリ設定のクライアントシークレットに設定。
  2. 証明書
    • AuthScheme：アプリ設定の"AzureServicePrincipal" に設定。
    • InitiateOAuth：GETANDREFRESH に設定。InitiateAzureAD を使うと、AzureAD 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
    • AzureTenant：接続するテナントに設定。
    • OAuthClientId：アプリ設定のクライアントId に設定。
    • OAuthJWTCert：JWT 証明書ストアを設定。
    • OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアの種類に設定。

MSI

Azure VM 上でMicrosoft Dynamics 365 を実行している場合は、Managed Service Identity（MSI）の資格情報を利用して接続が可能です。
  • AuthScheme：AzureMSI に設定。

MSI 資格情報が認証用に自動的に取得されます。

ドライバーのアンインストール

ドライバーをアンインストールする最も簡単な方法は、ターミナルを開いて、インストールディレクトリにあるuninstall.sh スクリプトを実行します。次に例を示します。 

cd "/Applications/CData ODBC Driver for Microsoft Dynamics 365"
sudo ./uninstall.sh

Note：このスクリプトはインストールディレクトリから実行される必要があります。

Copyright (c) 2023 CData Software, Inc. - All rights reserved.
Build 22.0.8479