接続の確立
JDBC データソースの作成
Java アプリケーションから接続するJDBC データソースを作成できます。CData JDBC Driver for SQL Server に基づくJDBC データソースの作成は、3つの基本ステップで構成されます。
- ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの[lib]サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
- ドライバークラスを入力します。次に例を示します。
cdata.jdbc.sql.SQLDriver
- JDBC URL を入力します。次に例を示します。
jdbc:sql:user=myuser;password=mypassword;Server=localhost;Database=Northwind; or jdbc:cdata:sql:user=myuser;password=mypassword;Server=localhost;Database=Northwind;
上記の2つ目の形式は、同じURL 形式を使用しているドライバー間でアプリケーションに競合がある場合は、CData ドライバーを使用していることを確認するために常に使用できます。URL は "jdbc:sql:" または"jdbc:cdata:sql:" のいずれかから始まり、任意の接続プロパティの名前と値のペアをセミコロン区切りで入力します。
CData JDBC Driver for SQL Server を使用して、Microsoft SQL Server、Azure SQL Server、またはAzure Data Warehouse の任意のインスタンスに接続できます。
Microsoft SQL Server への接続
SQL Server に接続するには、次の接続プロパティを指定します。
- Server:SQL Server を実行するサーバー名。
- Database:SQL Server データベース名。
SQL Server への認証
本製品 は、SQL Server 認証、またはKerberos 認証を使用するSQL Server への認証をサポートします。SQL Server 認証
SQL Server のユーザーログイン認証情報を使用してMicrosoft SQL Server に認証するには、以下のように設定します。
- AuthScheme:Password に設定。
- User:SQL Server との認証に使われるユーザー名。
- Password:認証ユーザーに関連付けられたパスワード。
Kerberos
Kerberos でSQL Server への認証を行うには、AuthScheme をKERBEROS に設定します。
Kerberos 経由でSQL Server への認証を行うには、認証プロパティを定義し、Kerberos が認証チケットを取得する方法を選択する必要があります。
Kerberos チケットの取得
Kerberos チケットは、依頼者のID を認証するために使用されます。正式なログイン / パスワードの代わりにチケットを使用することで、パスワードをローカルに保存したり、ネットワーク経由で送信したりする必要がなくなります。 ユーザーは、ローカルコンピュータでログインするか、 コマンドプロンプトでkinit USER と入力するたびに、再認証されます(チケットはリフレッシュされます)。本製品 は、 KRB5CCNAME および / またはKerberosKeytabFile 変数が存在するかどうかに応じて、必要なKerberos チケットを取得する3 つの方法を提供します。
MIT Kerberos 資格情報キャッシュファイル
このオプションを使用すると、MIT Kerberos チケットマネージャーまたはkinit コマンドを使ってチケットを取得できます。このオプションでは、User またはPassword 接続プロパティを設定する必要はありません。
このオプションは、KRB5CCNAME がシステムに作成されている必要があります。
MIT Kerberos 資格情報キャッシュファイル経由でチケット検索を有効にするには:
- お使いの環境にKRB5CCNAME 変数が存在することを確認します。
- KRB5CCNAME を資格情報キャッシュファイルを指すパスに設定します。(例えば、C:\krb_cache\krb5cc_0 または/tmp/krb5cc_0 です。)資格情報キャッシュファイルは、MIT Kerberos チケットマネージャーを使用してチケットを生成するときに作成されます。
- チケットを取得するには:
- MIT Kerberos チケットマネージャーアプリケーションを開きます。
- Get Ticket をクリックします。
- プリンシパル名とパスワードを入力します。
- OK をクリックします。
チケットの取得に成功すると、チケット情報がKerberos チケットマネージャーに表示され、クレデンシャルキャッシュファイルに保存されます。
本製品 はキャッシュファイルを使用してSQL Server に接続するためのKerberos チケットを取得します。
Note: KRB5CCNAME を編集したくない場合は、KerberosTicketCache プロパティを使用してファイルパスを手動で設定することができます。この設定後に、本製品 は指定されたキャッシュファイルを使用してSQL Server に接続するためのKerberos チケットを取得します。
Keytab ファイル
お使いの環境にKRB5CCNAME 環境変数がない場合、Keytab ファイルを使用してKerberos チケットを取得できます。
この方法を使用するには、User プロパティを目的のユーザー名に設定し、KerberosKeytabFile プロパティをユーザーに関連付けられたキータブファイルを指すファイルパスに設定します。
User およびPassword
お使いの環境にKRB5CCNAME 環境変数およびKerberosKeytabFile プロパティが設定されていない場合、ユーザーとパスワードの組み合わせを使用してチケットを取得できます。
この方法を使用するには、User およびPassword プロパティを、SQL Server での認証に使用するユーザー / パスワードの組み合わせに設定します。
クロスレルム認証の有効化
より複雑なKerberos 環境では、複数のレルムおよびKDC サーバーが使用されるクロスレルム認証が必要になる場合があります。例えば、1つのレルム / KDC がユーザー認証に使用され、別のレルム / KDC がサービスチケットの取得に使用される場合です。このようなクロスレルム認証を有効にするには、KerberosRealm およびKerberosKDC プロパティをユーザー認証に必要な値に設定します。また、KerberosServiceRealm およびKerberosServiceKDC プロパティを、 サービスチケットの取得に必要な値に設定します。
Azure SQL Server およびAzure Data Warehouse への接続
以下の接続プロパティを設定することで、Azure SQL Server またはAzure Data Warehouse に接続できます。
- Server:Azure を実行しているサーバー。Azure ポータルにログインして、SQL データベース(またはSQL データウェアハウス) -> 自身のデータベースを選択 -> 概要 -> サーバー名に進むと確認できます。
- Database:Azure ポータルのSQL データベース(またはSQL データウェアハウス)ページに表示されるデータベース名。
Azure
Azure がホストするSQL Server の認証には、標準的な認証情報を使用できます。そのためには、次を設定してください。
- AuthScheme: Password(SQL Server 認証情報)またはNTLM(Windows 認証情報)。
- User:Azure で認証するユーザー名。
- Password:認証ユーザーに関連付けられたパスワード。
あるいは、AuthScheme をAzureAd、AzurePassword、AzureMSI のいずれかに設定することで、OAuth の形式を使用することもできます。すべてのOAuth 接続でテナントを設定する必要があります。
- AzureTenant:SQL Server データベースがホストされているテナントのID。
AzureAD
Azure AD
Azure AD は、Microsoft のマルチテナント、クラウドベースのディレクトリおよびID 管理サービスです。これはユーザーベースの認証で、AuthScheme をAzureAD に設定する必要があります。
デスクトップアプリケーション
CData は、デスクトップでの認証を簡単にする埋め込みOAuth アプリケーションを提供します。接続の前に、以下の変数を設定します。
- InitiateOAuth:GETANDREFRESH。OAuthAccessToken を自動的に取得およびリフレッシュするために使用します。
CData は、デスクトップでの認証を簡単にする埋め込みOAuth アプリケーションを提供します。例えば、ユーザーがインターネットに接続されていないローカルサーバーを使用しているような場合に利用できます。
また、SQL Server コンソールで設定および登録するカスタムOAuth アプリケーションを介してデスクトップから認証することもできます。詳しくは、カスタムAzure AD アプリケーションの作成 を参照してください。
- カスタムAzure AD アプリケーションのみ:
- OAuthClientId:カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。
- CallbackURL:カスタムOAuth アプリケーションの登録時に定義されたリダイレクトURI。
接続すると、本製品 はデフォルトブラウザでSQL Server のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。本製品 はこれでOAuth プロセスを完了します。
- コールバックURL からアクセストークンを取得し、リクエストを認証します。
- 古いトークンの期限が切れたときは、新しいアクセストークンを取得します。
- OAuth 値をOAuthSettingsLocation に保存します。これらの値は接続間で永続化されます。
アクセストークンの期限が切れたときは、本製品 は自動でアクセストークンをリフレッシュします。
Web アプリケーション
Web 経由で認証する場合は、カスタムAzure AD アプリケーションの作成 で説明するようにSQL Server にカスタムOAuth アプリケーションを作成および登録する必要があります。それから本製品 を使用してOAuth トークンの値を取得および管理します。このセクションでは、OAuth アクセストークンの取得方法、ドライバーにOAuth アクセストークンを自動的に更新させる方法、OAuth アクセストークンを手動で更新する方法について説明します。
OAuth アクセストークンの取得:
- OAuthAccessToken を取得するには、次の接続プロパティを設定します。
- クライアントシークレットを使用する認証の場合:
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthClientSecret:アプリケーション設定のクライアントシークレット。
- 証明書を使用する認証の場合:
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthJWTCert:JWT 証明書のストア。
- OAuthJWTCertType:OAuthJWTCert で指定された証明書ストアの種類。
- クライアントシークレットを使用する認証の場合:
- ストアドプロシージャを呼び出し、OAuth 交換を完了します。
- GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。AuthMode インプットをWEB に、CallbackURL をアプリケーション設定で指定したリダイレクトURI に設定します。 ストアドプロシージャは、OAuth エンドポイントへのURL を返します。
- ステップ1でストアドプロシージャが返したURL に移動します。ログインしてWeb アプリケーションを認可します。コールバックURL にリダイレクトされます。
- GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。Verifier インプットを、リダイレクトURI のクエリ文字列のcode パラメータに設定します。
アクセストークンとリフレッシュトークンを取得したのち、データに接続してOAuth アクセストークンを自動的にリフレッシュできます。
OAuth アクセストークンの自動リフレッシュ:
本製品 がOAuth アクセストークンを自動的にリフレッシュするようにするには、次のように設定します。
- はじめてデータに接続する際、次の接続プロパティを設定します。
- InitiateOAuth:REFRESH。
- OAuthClientId:カスタムOAuth アプリケーション設定のクライアントId。
- OAuthClientSecret:カスタムOAuth アプリケーション設定のクライアントシークレット。
- OAuthAccessToken:GetOAuthAccessToken によって返されたアクセストークン。
- OAuthSettingsLocation:本製品 がOAuth 値を保存する場所のパス。これは接続間で維持されます。
- その後のデータ接続では、以下を設定します。
- InitiateOAuth
- OAuthSettingsLocation
OAuth アクセストークンの手動リフレッシュ:
OAuth アクセストークンを手動でリフレッシュするために必要な唯一の値は、OAuth リフレッシュトークンです。
- ExpiresIn 期間(GetOAuthAccessToken が返す)が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
- 次の接続プロパティを設定します。
- OAuthClientId:カスタムOAuth アプリケーション設定のクライアントId。
- OAuthClientSecret:カスタムOAuth アプリケーション設定のクライアントシークレット。
- RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
- 新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。これで新規接続が開かれます。
OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。
ヘッドレスマシン
ヘッドレスマシンに置かれているリソースにログインする必要がある場合は、インターネットブラウザに対応した別の端末で認証する必要があります。 以下のいずれかの方法で行います。- 後述のVerifier code を取得および交換に従い、OAuthVerifier 値を取得します。
- 別のマシンに本製品 をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。
いずれかのオプションを実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするようにドライバーを設定します。
Verifier code を取得および交換
Verifier code を取得するには、インターネットブラウザがあるマシンからOAuth 認可URL で認証し、OAuthVerifier 接続プロパティを取得する必要があります。
- 以下のオプションから選択します。
- 埋め込みOAuth アプリケーションを使用する場合は、SQL Server OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
- カスタムOAuth アプリケーションを使用する場合は、以下のプロパティを設定して認可URL を作成します。
- InitiateOAuth:OFF。
- OAuthClientId:アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:アプリケーションの登録時に割り当てられたクライアントシークレット。
- ログインして、本製品 にアクセス許可を与えます。verifier code を含むコールバックURL にリダイレクトされます。
- verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。
OAuth 認証値を取得するには次のプロパティを設定します。
- InitiateOAuth:REFRESH。
- OAuthVerifier:verifier code。
- OAuthSettingsLocation:ドライバーがOAuth トークン値を保存するファイルの場所。これは接続間で維持されます。
- カスタムアプリケーションのみ:
- OAuthClientId:(カスタムアプリのみ)カスタムOAuth アプリケーション設定のクライアントId に設定。
- OAuthClientSecret:(カスタムアプリのみ)カスタムOAuth アプリケーション設定のクライアントシークレットに設定。
OAuth 設定ファイルが生成されたら、以下のように接続プロパティをリセットします。
- InitiateOAuth:REFRESH。
- OAuthSettingsLocation:暗号化されたOAuth 認証値が保存される場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
- カスタムアプリケーションのみ:
- OAuthClientId:アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:アプリケーションの登録時に割り当てられたクライアントシークレット。
OAuth 設定を転送
ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続を作成し、インストールする必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。
「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定された場所に暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。
接続が正常にテストされたら、OAuth 設定ファイルをヘッドレスマシンにコピーします。
ヘッドレスマシンで、次の接続プロパティを設定し、データに接続します。
- InitiateOAuth:REFRESH。
- OAuthSettingsLocation:OAuth 設定ファイルの場所。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。
- カスタムアプリケーションのみ:
- OAuthClientId:アプリケーションの登録時に割り当てられたクライアントId。
- OAuthClientSecret:アプリケーションの登録時に割り当てられたクライアントシークレット。
Azure サービスプリンシパル
Azure サービスプリンシパルは、ロールに基づいたアプリケーションベースの認証です。これは、認証がユーザーごとではなく、アプリケーションごとに行われることを意味します。 アプリで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。 リソースへのアプリケーションのアクセスは、割り当てられたロールの権限によって制御されます。
Azure サービスプリンシパル認証を使用するには、以下を行います。
- 認証アプリケーションにロールを割り当てる機能を設定します。これには、カスタムAzure AD アプリケーションの作成 で説明するように、カスタムOAuth AD アプリケーションを作成します。
- Azure AD テナントにアプリケーションを登録し、ロールベースのアクセス制御で使用できる新しいサービスプリンシパルを作成して、サブスクリプション内のリソースにアクセスします。
以下の手順に従います。
- カスタムAzure AD アプリケーションの作成 での説明のとおりに、カスタムAzure AD アプリケーションを作成します。
- アプリケーションへのロールの割り当て:
- 検索バーを使用してサブスクリプションサービスを検索します。
- サブスクリプションページを開きます。
- アプリケーションを割り当てるサブスクリプションを選択します。
- アクセス制御(IAM)を開きます。
- 追加 -> ロールの割り当ての追加を選択します。SQL Server はロールの割り当ての追加ページを開きます。
- 作成したカスタムAzure AD アプリケーションに所有者ロールを割り当てます。
クライアントクレデンシャル
クライアント資格情報は、直接ユーザー認証が行われないOAuth のフローを指します。代わりに、クレデンシャルはアプリケーション自体のためだけに作成されます。アプリケーションで実行されるすべてのタスクは、デフォルトユーザーコンテキストなしで実行されます。そのため、認証フローが標準フローとは少し違ったものになります。クライアントOAuth フローに関連するすべてのアクセス許可には、管理者の同意が必要です。これは、CData JDBC Driver for SQL Server が埋め込まれたアプリケーションをクライアントOAuth フローでは使用できないことを意味します。クライアント資格情報を使用するには、独自のOAuth アプリケーションの作成が必要になります。詳しくは、カスタムAzure AD アプリケーションの作成 を参照してください。
portal.azure.com の[アプリの登録]で[API のアクセス許可]に移動し、Microsoft Graph アクセス許可を選択します。アクセス許可には2つの異なるアクセス許可セットがあります。委任されたアクセス許可とアプリケーションの許可です。クライアントの資格情報認証時に使用されるアクセス許可は、[アプリケーションの許可]の下にあります。
インテグレーションに必要なアクセス許可を選択します。その後、次の接続プロパティを設定します。
- AuthScheme:AzureServicePrincipal。
- InitiateOAuth:GETANDREFRESH。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
- AzureTenant:接続するテナント。
- OAuthGrantType:CLIENT。
- OAuthClientId:アプリケーション設定のクライアントId。
- OAuthClientSecret:アプリケーション設定のクライアントシークレット。
クライアント資格情報での認証は、他の接続同様に自動的に行われますが、ユーザーにプロンプトするウィンドウは表示されません。ユーザーコンテキストがないため、ブラウザのポップアップは必要ないからです。接続が行われ、内部的に処理されます。
Auth Certificate
Auth Certificate は、証明書を使用してサーバー間認証を可能にするOAuth フローを指します。クライアントOAuth フローに関連するすべてのアクセス許可には、管理者の同意が必要です。これは、CData JDBC Driver for SQL Server が埋め込まれたアプリケーションをクライアントOAuth フローでは使用できないことを意味します。OAuth 証明書を使用するには、独自のOAuth アプリケーションの作成が必要になります。 詳しくは、カスタムAzure AD アプリケーションの作成 を参照してください。portal.azure.com の[アプリの登録]でAPI のアクセス許可に移動し、クライアントのGraph アクセス許可を選択します。アクセス許可には2つの異なるアクセス許可セットがあります。委任されたアクセス許可とアプリケーションの許可です。証明書認証時に使用されるアクセス許可は、[アプリケーションの許可]の下にあります。
自身のインテグレーションに適用させるアクセス許可を選択します。その後、次の接続プロパティを設定します。
- AuthScheme:AzureServicePrincipalCert。
- AzureTenant:接続するテナント。
- OAuthJWTCert:JWT 証明書のストア。
- OAuthJWTIssuer:OAuth クライアントId。
- OAuthJWTCertType:OAuthJWTCert で指定された証明書ストアの種類。
証明書の認証は自動で行われます。ユーザーコンテキストがないため、認証が発生したことを知らせるポップアップはありません。 接続は内部で行われ、処理されます。
Azure Password
AuthScheme をAzurePassword に設定します。
Azure 資格情報を使用して直接接続するには、次の接続プロパティを指定します。
- User:Azure への接続に使用するユーザーアカウントに設定。
- Password:Azure への接続に使用するパスワードに設定。
- AzureTenant:Azure 上のSQL Server への認証に使用するOAuth アプリの概要ページにある、Directory (tenant) ID に設定。
Managed Service Identity (MSI)
Azure VM 上でSQL Server を実行しており、MSI を利用して接続したい場合は、AuthScheme をAzureMSI に設定します。
User-Managed Identities
マネージドID のトークンを取得するには、OAuthClientId プロパティを使用してマネージドID の"client_id" を指定します。VM に複数のユーザーが割り当てられたマネージドID がある場合は、OAuthClientId も指定する必要があります。