接続の確立
JDBC データソースの作成
Java アプリケーションから接続するJDBC データソースを作成できます。CData JDBC Driver for Microsoft Dynamics CRM に基づくJDBC データソースの作成は、3つの基本ステップで構成されます。
- ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの[lib]サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
- ドライバークラスを入力します。次に例を示します。
cdata.jdbc.dynamicscrm.DynamicsCRMDriver
- JDBC URL を入力します。次に例を示します。
jdbc:dynamicscrm:User=myuseraccount;Password=mypassword;URL=https://myOrg.crm.dynamics.com/;CRM Version=CRM Online; or jdbc:cdata:dynamicscrm:User=myuseraccount;Password=mypassword;URL=https://myOrg.crm.dynamics.com/;CRM Version=CRM Online;
上記の2つ目の形式は、同じURL 形式を使用しているドライバー間でアプリケーションに競合がある場合は、CData ドライバーを使用していることを確認するために常に使用できます。URL は "jdbc:dynamicscrm:" または"jdbc:cdata:dynamicscrm:" のいずれかから始まり、任意の接続プロパティの名前と値のペアをセミコロン区切りで入力します。
Microsoft Dynamics CRM への接続
接続するには、Url に組織のルートURL を設定し、User、Password、およびCRMVersion を設定します。
Microsoft Dynamics CRM への認証
オンプレミスCRM
オンプレミスCRM の場合は、認証メソッドを選択します。
デフォルトで、本製品 は、Windows(NTLM)認証を使います。Kerberos delegation などの他の認証タイプを使うには、AuthScheme を設定します。
次は接続文字列の例です。
AuthScheme=Auto;Url=https://myOrg.crm.dynamics.com/;User=username;Password=password;CRM Version='CRM2011+'"
Internet-Facing Deployment
IFD を使用するDynamics CRM では、InternetFacingDeployment をtrue に設定します。
次は接続文字列の例です。
AuthScheme=Auto;Url=https://myOrg.crm.dynamics.com/;User=username;Password=password;InternetFacingDeployment=True;CRM Version='CRM2011+'"
Azure AD
Microsoft Dynamics CRM はAzure AD をサポートします。Azure AD を使用して認証するには、カスタムアプリケーションを作成してOAuthClientId、OAuthClientSecret を取得し、カスタムAzure AD 資格情報を使用する必要があります。AuthScheme をAzureAD に設定します。以下のAzure AD フローは、すでに設定済みであることを前提として書かれています。
接続すると、本製品 はデフォルトブラウザでAzure AD エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。本製品 が以下のAzure AD プロセスを完了します。
- コールバックURL でアクセストークンおよびADFSServer を設定し、認証リクエストを行います。
- 接続設定にOAuth 値を保存します。これらの値は接続間で永続化されます。
- 返されたリフレッシュトークンと有効なアクセストークンとを交換します。
次はInternet-Facing Deployment 用の接続文字列の例です。
AuthScheme=OAuth;Url=https://myOrg.crm.dynamics.com/;CRM Version=CRM2011+;InitiateOAuth=GETANDREFRESH;CallbackUrl=http://localhost:33333;OAuthClientId=ClientID;ADFSServer=https://auth.adfs.com/;"以下はオンライン環境用の接続文字列の例です。
AuthScheme=OAuth;Url=https://myOrg.crm.dynamics.com/;CRM Version=CRMOnline;InitiateOAuth=GETANDREFRESH;CallbackUrl=http://localhost:33333;OAuthClientId=ClientID;AzureTenant=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx;"
デスクトップアプリケーション
カスタムOAuth アプリケーションの資格情報を使用して認証するには、OAuth アクセストークンを取得し、更新する必要があります。これらを設定すると、接続の準備が整います。OAuth アクセストークンの取得およびリフレッシュ
- InitiateOAuth: GETANDREFRESH。OAuthAccessToken を自動的に取得およびリフレッシュするために使用します。
- OAuthClientId:アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:アプリケーションの登録時に割り当てられたクライアントシークレット。
- CallbackURL:アプリケーションの登録時に定義されたリダイレクトURI。
接続すると、本製品 はデフォルトブラウザでMicrosoft Dynamics CRM のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。
アプリケーションにアクセス許可を与えると、本製品 はOAuth プロセスを完了します。
- 本製品 はMicrosoft Dynamics CRM からアクセストークンを取得し、それを使ってデータをリクエストします。
- OAuth 値はOAuthSettingsLocation で指定されたパスに保存されます。これらの値は接続間で永続化されます。
アクセストークンの期限が切れたときは、本製品 は自動でアクセストークンをリフレッシュします。
Web アプリケーション
Web アプリケーション経由で接続する場合は、 Microsoft Dynamics CRM にカスタムOAuth アプリケーションを登録する必要があります。カスタムOAuth アプリケーションの作成 を参照してください。それから本製品 を使用してOAuth トークンの値を取得および管理します。 OAuth アクセストークンの取得
認証タイプに応じて以下のいずれかの接続プロパティグループを設定して、OAuthAccessToken を取得します。
- クライアントシークレット
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthClientSecret:アプリケーション設定のクライアントシークレット。
- 証明書
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthJWTCert:JWT 証明書のストア。
- OAuthJWTCertType:OAuthJWTCert で指定された証明書ストアの種類。
続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。
-
GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、CallbackURL インプットをアプリケーション設定で指定したリダイレクトURI に設定します。必要に応じて、Permissions パラメータを設定してカスタム権限をリクエストします。
ストアドプロシージャがOAuth エンドポイントのURL を返します。
- URL を開き、ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
- GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、コールバックURL のクエリ文字列の"code" パラメータに設定します。必要に応じて、Permissions パラメータを設定してカスタム権限をリクエストします。
OAuthAccessToken 接続プロパティをストアドプロシージャで返されたアクセストークンに設定し、データに接続します。ExpiresIn 秒後に、アクセストークンの期限が切れたときは、GetOAuthAccessToken を呼び出し、新しいアクセストークンを取得します。
ヘッドレスマシン
ドライバーを設定するため、ヘッドレスマシンでユーザーアカウントにOAuth を使用します。インターネットブラウザに対応した別の端末で認証する必要があります。
- 以下の2つのオプションから選択します。
- オプション1:後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
- オプション2:別のマシンに本製品 をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。
- その後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。
オプション1:Verifier code を取得および交換
Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。
インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。
- 以下のオプションから選択します。
- 埋め込みOAuth アプリケーションを使用する場合は、Microsoft Dynamics CRM OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
- カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定し、認証URL を作成します。
- InitiateOAuth: OFF。
- OAuthClientId:アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:アプリケーションの登録時に割り当てられたクライアントシークレット。
- ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
- verifier code の値を保存します。後でOAuthVerifier 接続プロパティを設定するために必要です。
ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。
- InitiateOAuth: REFRESH。
- OAuthVerifier:verifier code。
- OAuthClientId:(カスタムアプリケーションのみ)カスタムOAuth アプリケーション設定のクライアントId。
- OAuthClientSecret:(カスタムアプリケーションのみ)カスタムOAuth アプリケーション設定のクライアントシークレット。
- OAuthSettingsLocation:ドライバーがOAuth トークン値を保存するファイルの場所。これは接続間で維持されます。
OAuth 設定ファイルが生成されたら、以下のように接続プロパティをリセットする必要があります。
- InitiateOAuth: REFRESH。
- OAuthClientId:(カスタムアプリケーションのみ)アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:(カスタムアプリケーションのみ)アプリケーションの登録時に割り当てられたクライアントシークレット。
- OAuthSettingsLocation:暗号化されたOAuth 認証値が保存される場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
オプション2:OAuth 設定を転送
ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続を作成し、インストールする必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。
「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。
接続が正常にテストされたら、OAuth 設定ファイルをヘッドレスマシンにコピーします。
ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。
- InitiateOAuth: REFRESH。
- OAuthClientId:(カスタムアプリケーションのみ)アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:(カスタムアプリケーションのみ)アプリケーションの登録時に割り当てられたクライアントシークレット。
- OAuthSettingsLocation:OAuth 設定ファイルの場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
管理者の同意
管理者の同意とは、Azure Active Directory テナントの管理者が、管理者の同意を必要とするアプリケーションに権限を付与することを指します。 CData JDBC Driver for Microsoft Dynamics CRM 内の埋め込みアプリケーションには、管理者の同意を必要とするアクセス許可はありません。したがって、この情報はカスタムアプリケーションにのみ適用されます。
管理者の同意の付与
Azure ポータルで新しいOAuth アプリケーションを作成する場合には、アプリに必要なアクセス許可を指定する必要があります。一部のアクセス許可には、「管理者の同意が必要」と記載されている場合があります。 例えば、すべてのグループのアクセス許可には管理者の同意が必要です。アプリケーションに管理者の同意が必要な場合、いくつかの方法があります。
管理者の同意を付与する最も簡単な方法は、管理者がportal.azure.com にログインして、アプリの登録で作成したアプリケーションに移動するよう要求することです。[API のアクセス許可]に、[管理者の同意の付与]ボタンがあります。ここで、アプリケーションが作成されたテナントでアクセス許可を持つことに同意できます。
管理者が同意すると、通常どおり認証を実行できます。
クライアントクレデンシャル
クライアント資格情報は、直接ユーザー認証が行われないOAuth のフローを指します。代わりに、資格情報はアプリケーション自体のためだけに作成されます。 アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。そのため、認証フローが標準とは少し違ったものになります。クライアントOAuth フロー
クライアントOAuth フローに関連するすべてのアクセス許可には、管理者の同意が必要です。これは、CData JDBC Driver for Microsoft Dynamics CRM が埋め込まれたアプリケーションをクライアントOAuth フローでは使用できないことを意味します。クライアント資格情報を使用するには、独自のOAuth アプリケーションの作成が必要になります。 詳しくは、カスタムOAuth アプリケーションの作成 を参照してください。
portal.azure.com の[アプリの登録]で[API のアクセス許可]に移動し、Microsoft Graph アクセス許可を選択します。アクセス許可には、委任されたアクセス許可とアプリケーションの許可の2つの異なるアクセス許可セットがあります。 クライアントの資格情報認証時に使用されるアクセス許可は、[アプリケーションの許可]の下にあります。インテグレーションに必要なアクセス許可を選択します。
認証タイプに応じて、以下のいずれかの接続プロパティグループを設定すると、接続できるようになります。
- クライアントシークレット
- InitiateOAuth: GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant:接続するテナント。
- OAuthGrantType: CLIENT。
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthClientSecret:アプリケーション設定のクライアントシークレット。
- 証明書
- InitiateOAuth: GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant:接続するテナント。
- OAuthGrantType: CLIENT。
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthJWTCert:JWT 証明書のストア。
- OAuthJWTCertType:OAuthJWTCert で指定された証明書ストアの種類。
クライアント資格情報での認証は、他の接続同様に自動的に行われますが、ユーザーにプロンプトするウィンドウは表示されません。ユーザーコンテキストがないため、ブラウザのポップアップは必要ないからです。接続が行われ、内部的に処理されます。
Azure サービスプリンシパル
Azure サービスプリンシパルとしての認証は、OAuth クライアントクレデンシャルフローを介して処理され、直接のユーザー認証は行われません。代わりに、クレデンシャルはアプリケーション自体のためだけに作成されます。アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。Azure AD アプリとAzure サービスプリンシパルの作成
Azure サービスプリンシパルを使用して認証する場合、Azure AD テナントにアプリケーションを登録する必要があります。 アプリケーションへのロールの割り当て サブスクリプションのリソースにアクセスするには、アプリケーションにロールを割り当てる必要があります。- 検索バーでサブスクリプションサービスを検索・選択して、サブスクリプションページを開きます。
- アプリケーションを割り当てるサブスクリプションを選択します。
- アクセス制御 (IAM)を開き、追加 -> ロール割り当ての追加 を選択してロール割り当ての追加ページを開きます。
- 作成したAzure AD アプリに割り当てるロールとして、所有者を選択します。
- 以下の「両メソッド共通」で説明されているプロパティを設定。
- グループプロパティを設定。グループの選択は、設定されたアプリケーション認証(クライアントシークレットまたは証明書)に依存します。
両メソッド共通
クライアントシークレットか証明書認証を選択する前に、まず以下の手順に従って設定を行います。その後、該当するセクションの設定に進んでください。
- AuthScheme:アプリケーション設定のAzureServicePrincipal。
- InitiateOAuth: GETANDREFRESH。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
- AzureTenant:接続するテナント。
- OAuthClientId:アプリケーション設定のクライアントId。
続いて、以下を設定します。
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthClientSecret:アプリケーション設定のクライアントシークレット。
証明書を使用した認証
続いて、以下を設定します。
- OAuthJWTCert:JWT 証明書のストア。
- OAuthJWTCertType:OAuthJWTCert で指定された証明書ストアの種類。
Kerberos
Kerberos で認証する方法についての詳細は、Kerberos の使用 を参照してください。
- クライアントシークレット
- InitiateOAuth: GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant:接続するテナント。
- OAuthGrantType: CLIENT。
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthClientSecret:アプリケーション設定のクライアントシークレット。
- 証明書
- InitiateOAuth: GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant:接続するテナント。
- OAuthGrantType: CLIENT。
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthJWTCert:JWT 証明書のストア。
- OAuthJWTCertType:OAuthJWTCert で指定された証明書ストアの種類。