JDBC Driver for Microsoft SharePoint

Build 22.0.8479

接続の確立

JDBC データソースの作成

Java アプリケーションから接続するJDBC データソースを作成できます。CData JDBC Driver for Microsoft SharePoint に基づくJDBC データソースの作成は、3つの基本ステップで構成されます。

  • ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの［lib］サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
  • ドライバークラスを入力します。次に例を示します。 
    cdata.jdbc.sharepoint.SharePointDriver
  • JDBC URL を入力します。次に例を示します。 
    jdbc:sharepoint:User=MyUserAccount;Password=MyPassword;Auth Scheme=NTLM;URL=http://sharepointserver/mysite;

or

jdbc:cdata:sharepoint:User=MyUserAccount;Password=MyPassword;Auth Scheme=NTLM;URL=http://sharepointserver/mysite;

    上記の2つ目の形式は、同じURL 形式を使用しているドライバー間でアプリケーションに競合がある場合は、CData ドライバーを使用していることを確認するために常に使用できます。URL は "jdbc:sharepoint:" または"jdbc:cdata:sharepoint:" のいずれかから始まり、任意の接続プロパティの名前と値のペアをセミコロン区切りで入力します。

Microsoft SharePoint への接続

Microsoft SharePoint は、グローバルなMicrosoft SharePoint サイト内のすべてのリストとドキュメント、および個々のサイトで機能します。URL 接続プロパティをサイトコレクションURL に設定すると、すべてのリストおよびドキュメントで動作し、特定のサイトURL に設定すると、そのサイト内のリストおよびドキュメントでのみ動作します。

URLサンプルURL
サイトコレクションhttps://teams.contoso.com
サイトhttps://teams.contoso.com/teamA or https://teamA.contoso.com

URL の入力に加え、次の接続プロパティセットのいずれかを使ってSharePoint に認証します。次のように、デフォルト値を使用するとほとんどの環境で簡単に接続できます。 SharePoint は、オンライン（クラウドベース）およびオンプレミスアーキテクチャをサポートします。各アーキテクチャは、それぞれ異なる認証スキームをサポートします。

オンライン認証およびオンプレミス認証について、以下で順に説明します。

SharePoint Online への認証

SharePointEdition を"SharePoint Online" に設定し、User およびPassword をSharePoint へのログオンに使用するクレデンシャルに設定します。例えば、Microsoft Online Services アカウントへのクレデンシャルです。

以下の認証スキームがサポートされています。

  • AzureAD
  • シングルサインオン（SSO）スキーム
  • MSI
  • OAuthJWT
次のSSO ID プロバイダーがサポートされています。

  • ADFS
  • OneLogin
  • Okta
  • PingFederate

もしユーザーアカウントのドメインがID プロバイダーに設定されたドメインと異なる場合には、SSODomain を後者に設定します。このプロパティは、すべてのSSO で必要になる可能性があります。

AzureAD

Azure Active Directory（AzureAD）は、OAuth を使用して認証する接続タイプです。OAuth では認証するユーザーにインターネットブラウザでMicrosoft SharePoint との通信を要求します。下記で説明するとおり、本ドライバーはさまざまな方法でこれをサポートします。AuthScheme をAzureAD に設定します。以下で説明するAzure AD フローは、すでに設定済みであることを前提として書かれています。

Azure テナントの新しいAzureAD アプリケーションを承認する際、組織による管理者の同意が必要になる場合があります。すべてのAzureAD フローにおいて、AzureAD アプリケーションの初期インストールと使用の際は、管理者がそのAzure テナントのアプリケーションを承認する必要があります。

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

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

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

次の接続プロパティを設定して、接続してください。

  • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
  • OAuthClientId：（カスタムアプリケーションのみ）アプリケーション設定のクライアントId に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーション設定のクライアントシークレットに設定。
  • CallbackURL：アプリケーション設定のリダイレクトURL に設定。

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

  1. コールバックURL からアクセストークンを取得し、リクエストを認証します。
  2. 古いトークンの期限が切れたときは、新しいアクセストークンを取得します。
  3. OAuth 値をOAuthSettingsLocation に保存します。これらの保存された値は接続間で永続化されます。

Web アプリケーション

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

OAuth アクセストークンの取得

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

  • 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. その後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

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

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

  1. 以下のオプションから選択します。

    • 埋め込みOAuth アプリケーションを使用する場合は、Microsoft SharePoint OAuth endpoint をクリックし、ブラウザでエンドポイントを開きます。
    • カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定し、認証URL を作成します。
      • InitiateOAuth：OFF に設定。
      • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
      • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
      次に、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。

  2. ログインして、本製品 にアクセス許可を与えます。すると、verifier code を含むコールバックURL にリダイレクトされます。
  3. verifier code の値を保存します。後ほどこれをOAuthVerifier 接続プロパティに設定します。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。次のプロパティを設定します。

ヘッドレスマシンでは、次の接続プロパティを設定して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 パスワード

Azure 資格情報を使用して直接接続するには、次の接続プロパティを指定します。

  • AuthScheme：AzurePassword に設定。
  • User：Azure への接続に使用するユーザーアカウントに設定。
  • Password：Azure への接続に使用するパスワードに設定。
  • AzureTenant：Azure 上のMicrosoft SharePoint への認証に使用するOAuth アプリの概要ページにある、Directory (tenant) ID に設定。

OAuth：管理者の同意

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

管理者の同意の付与

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

管理者の同意を付与する最も簡単な方法は、管理者がAzure Portal にログインして、［アプリの登録］で作成したアプリケーションに移動します。API のアクセス許可で、同意の付与をクリックして、アプリが作成されたテナントでアクセス権限を付与します。

組織に複数のテナントがある場合、または組織外の他のテナントにアプリのアクセス許可を与える必要がある場合、GetAdminConsentURL ストアドプロシージャを使用してAdmin Authorization URL を生成します。OAuth アプリケーションが正常に認可されると、アクセス権限が付与されたことを示すBoolean 値が返されます。

管理者がOAuth アプリケーションを承認後、認証を続行できます。

カスタムアプリを使用した資格情報

次の手順に従って、カスタムOAuth アプリを作成し、SharePoint アプリを使用してOAuth 認証用の接続プロパティを取得します。

Add-In を登録

  1. URL にhttps://{sitename}.SharePoint.com/_layouts/15/appregnew.aspx と入力してRegister Add-In ページに移動します。
  2. 「アプリ情報」セクションで、クライアントID およびクライアントシークレットのテキストボックスの横にある生成をクリックし、それぞれの値を生成します。
  3. タイトル、アプリドメイン、リダイレクト先のURI をそれぞれのテキストボックスに入力し、設定します。
  4. 作成をクリックするとアドインが登録され、作成された情報を含む成功メッセージを返します。
Add-In にアクセス権限を付与
  1. SharePoint サイトに移動します。
  2. ブラウザにURL：https://{sitename}.sharepoint.com/_layouts/15/appinv.aspx を入力します。「アクセス許可」ページにリダイレクトされます。
  3. 先ほど生成したクライアントID をアプリID に入力し、［参照］ボタンをクリックします。これにより、タイトル、アプリドメイン、リダイレクト先のURI 以外のテキストボックスに値が読み込まれます。
  4. ここで、以下のアクセス許可要求をXML 形式で入力します。 
        <AppPermissionRequests AllowAppOnlyPolicy="true">
     <AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl"/>
    </AppPermissionRequests>
  5. ［作成］をクリックすると、アクセス許可同意のダイアログが表示されます。［信頼する］をクリックして、アクセス許可を付与します。

ADFS

AuthScheme をADFS に設定します。次の接続プロパティを設定する必要があります。

  • User：ADFS ユーザーに設定。
  • Password：ユーザーのADFS パスワードに設定。
  • SSODomain（オプション）：ADFS のID プロバイダーで設定されたドメイン。
以下は接続文字列の例です。 
AuthScheme=ADFS;User=ADFSUserName;Password=ADFSPassword;URL='http://sharepointserver/mysite';

Okta

AuthScheme をOkta に設定します。Okta への接続には、次の接続プロパティを使用します。

  • User：Okta ユーザーに設定。
  • Password：ユーザーのOkta パスワードに設定。
  • SSODomain（オプション）：Okta のID プロバイダーで設定されたドメイン。

次は接続文字列の例です。 

AuthScheme=Okta;User=oktaUserName;Password=oktaPassword;URL='http://sharepointserver/mysite';

OneLogin

AuthScheme をOneLogin に設定します。OneLogin への接続には、次の接続プロパティを使用します。

  • User：OneLogin ユーザーに設定。
  • Password：ユーザーのOneLogin パスワードに設定。
  • SSODomain（オプション）：OneLogin のID プロバイダーで設定されたドメイン。

次は接続文字列の例です。 

AuthScheme=OneLogin;User=OneLoginUserName;Password=OneLoginPassword;URL='http://sharepointserver/mysite';

PingFederate

AuthScheme をPingFederate に設定します。PingFederate への接続には、次の接続プロパティを使用します。

  • User：PingFederate ユーザーに設定。
  • Password：ユーザーのPingFederate パスワードに設定。
  • SSODomain（オプション）：PingFederate のID プロバイダーで設定されたドメイン。

次は接続文字列の例です。 

AuthScheme=PingFederate;User=PingFederateUserName;Password=PingFederatePassword;URL='http://sharepointserver/mysite';

SharePointOAuth

AuthScheme をSharePointOAuth に設定します。SharePointOAuth への接続には、次の接続プロパティを使用します。

  • InitiateOAuth：GETANDREFRESH に設定。
  • User：SharePointOAuth ユーザーに設定。
  • Password：ユーザーのSharePointOAuth パスワードに設定。

次は接続文字列の例です。 

Schema=REST;InitiateOAuth=GETANDREFRESH;AuthScheme=SharepointOAuth;URL=https://rssbuscrm.sharepoint.com;User=SharePointUserName;Password=SharePointPassword;SharePointEdition='SharepointOnline';

OAuthJWT 証明書

AuthScheme をOAuthJWT に設定します。Microsoft SharePoint への接続には、次の接続プロパティを使用します。

  • OAuthGrantType：CLIENT に設定。
  • AzureTenant：接続するテナントに設定。
  • OAuthJWTCert：JWT 証明書ストアに設定。
  • OAuthJWTIssuer：OAuth クライアントId に設定。

MSI

Azure VM 上でMicrosoft SharePoint を実行している場合は、Managed Service Identity（MSI）の資格情報を利用して接続が可能です。

  • AuthScheme：AzureMSI に設定。

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

SharePoint On-Premises への認証

次の認証タイプを使用するには、SharePointEdition を"SharePoint On-Premises" に設定します。

Windows（NTLM）

これは最も一般的な認証タイプです。そのため、本製品 はNTLM をデフォルトとして使用するように事前設定されています。Windows のUser およびPassword を設定して接続します。

Kerberos

AuthScheme をNEGOTIATE に設定します。Kerberos での接続には、次の接続プロパティを使用します。

  • KerberosKDC：Kerberos KDC マシンのホスト名またはIP アドレスに設定。
  • KerberosRealm：Microsoft SharePoint Kerberos プリンシパルのレルムに設定。これは、principal value（例：MyService/[email protected]）の'@' 記号の後ろの値（例：EXAMPLE.COM）です。
  • KerberosSPN：Microsoft SharePoint のKerberos プリンシパルのサービスとホストに設定。これは、principal value（例：MyService/[email protected]）の'@' 記号の前の値（例：MyService/MyHost）です。

Kerberos で認証する方法についての詳細は、Kerberos の使用 を参照してください。

ADFS

AuthScheme をADFS に設定します。次の接続プロパティを設定します。

  • User：ADFS ユーザーに設定。
  • Password：ユーザーのADFS パスワードに設定。
  • SSOLoginURL：ADFS サーバーのWS-Trust エンドポイントに設定。
ADFS へ認証するには、SSOProperties も設定する必要があります。SharePoint のADFS サーバー上にあるRelyingParty パラメータの値を指定します。 以下は接続文字列の例です。 
AuthScheme=ADFS;User=ADFSUserName;Password=ADFSPassword;SSOLoginURL='https://<authority>/adfs/services/trust/2005/usernamemixed';SSO Properties ='RelyingParty=urn:sharepoint:sp2016;';

匿名アクセス

AuthScheme をURL と一緒にNONE に設定します。

MSI

Azure VM 上でMicrosoft SharePoint を実行している場合は、Managed Service Identity（MSI）の資格情報を利用して接続が可能です。

  • AuthScheme：AzureMSI に設定。

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

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