JDBC Driver for UMSaaSCloud

Build 24.0.9062

接続の確立

JDBC データソースの作成

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

  • ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの［lib］サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
  • ドライバークラスを入力します。次に例を示します。 
    cdata.jdbc.umsaascloud.UMSaaSCloudDriver
  • JDBC URL を入力します。次に例を示します。 
    jdbc:umsaascloud:AuthScheme=Basic;User=myUser;Password=myPassword;Security Token=myToken;

or

jdbc:cdata:umsaascloud:AuthScheme=Basic;User=myUser;Password=myPassword;Security Token=myToken;

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

UMSaaSCloud への接続

デフォルトでは、本製品 は本番環境に接続します。UMSaaSCloud sandbox アカウントを使用するには、UseSandbox をtrue に設定します。ユーザー / パスワード認証を使用している場合は、User にsandbox のユーザー名を設定してください。

UMSaaSCloud への認証

UMSaaSCloud は、Basic、OAuth、OAuthJWT（コンシューマーキー）の3つの認証方式をサポートしています。

Basic

Basic 認証は、セキュリティトークンとユーザー資格情報の使用に基づきます。Basic 認証を使用するには、AuthScheme をBasic に、User とPassword をログイン資格情報に設定し、SecurityToken を設定します。

デフォルトではSecurityToken が必要ですが、UMSaaSCloud で信頼できるIP アドレスの範囲を設定することで、オプションにすることができます。

セキュリティトークンを無効にするには：

  1. UMSaaSCloud にログインして、［設定］セクションの［Quick Find］ボックスにNetwork Access を入力します。
  2. IP アドレスを信頼できるIP アドレスのリストに追加します。

セキュリティトークンを取得するには：

  1. UMSaaSCloud の［私の設定］->［個人用］->［私のセキュリティトークンのリセット］を開きます。
  2. ［セキュリティトークンのリセット］をクリックします。トークンがE メールで送られます。
  3. SecurityToken 接続プロパティでセキュリティトークンを入力するか、Password に追加します。

OAuth

OAuth 認証を使用するには、すべてのユーザーアカウントフローでAuthScheme をOAuth に設定する必要があります。

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

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

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

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

  • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使えば、繰り返しOAuth の交換を行ったり、手動でOAuthAccessToken を設定する必要はなくなります。
  • OAuthClientId：（カスタムアプリケーションのみ）アプリケーション設定のクライアントID に設定。
  • OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーション設定のクライアントシークレットに設定。

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

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

Web アプリケーション

Web アプリケーション経由で接続する場合は、UMSaaSCloud にカスタムOAuth アプリケーションを登録する必要があります。詳しくは、カスタム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. 以下のオプションから選択します。

    • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
    • オプション2：ブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。

  2. 次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

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

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

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

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

    • 埋め込みOAuth アプリケーションを使用する場合は、UMSaaSCloud 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 設定ファイルの場所に設定。アクセストークンの自動リフレッシュを有効にするために、この場所が本製品 に読み書きのアクセス許可を与えることを確認してください。

OAuth パスワードグラント

次の手順に従いパスワードグラントオプションを設定します。

  1. パスワードグラント種別で認証を行う場合は、AuthScheme をOAuthPassword に設定します。
  2. 上記のWeb またはデスクトップ認証セクションで指定されたすべてのプロパティを設定します。
  3. User とPassword をログイン資格情報に設定し、必要に応じてSecurityToken も設定します。

Note：セッションの設定 -> ログイン時のIP アドレスとセッションをロックするを有効にしている場合、本製品 の使用中にIP アドレスが変更されないことを確認してください。本製品 使用中にIP が変更された場合、UMSaaSCloud から"INVALID_SESSION_ID" エラーが返され、本製品 はデータを取得できなくなります。このエラーが表示された場合は、UMSaaSCloud 管理者にこの設定を無効にするよう依頼するか、本製品 を使用するインスタンスに固定IP を必ず設定してください。その後、接続をリセットして本製品 を使い続けます。

OAuthJWT 証明書

AuthScheme をOAuthJWT に設定します。

OAuthJWT

OAuthJWT コンシューマーキーを取得するには：

  1. UMSaaSCloud にログインします。
  2. ［設定］で［クイック検索］ボックスにApps を入力し、リンクをクリックしてアプリを作成します。表示されたページの［接続アプリケーション］セクションで、［新規］をクリックします。
  3. ユーザーがアプリケーションにログイン認証をする際に表示されるアプリケーション名を入力します。連絡先E メールアドレスも入力します。
  4. ［OAuth 設定の有効化］をクリックし、コールバックURL ボックスに値を入力します。この値は必要に応じて接続アプリケーションを作成する場合にのみ設定します。この種類の認証には、実際には必要ありません。 Callback URL は次の形式になります： 
    http://localhost:8019/src/oauthCallback.rst
  5. ［デジタル署名を使用］を有効にします。
  6. 証明書をアップロードします。
  7. アプリがユーザーに要求するアクセス許可の範囲を選択します。
  8. アプリケーション名をクリックしてアプリケーションの情報ページを開きます。OAuth コンシューマーキーが表示されます。

OAuth アプリケーション作成後、次の接続プロパティを設定します。

  • AuthScheme：OAuthJWT に設定。
  • InitiateOAuth：GETANDREFRESH に設定。
  • OAuthJWTCert：JWT 証明書ストアに設定。
  • OAuthJWTCertType：OAuthJWTCert で指定された証明書ストアのタイプに設定。
  • OAuthJWTCertPassword：JWT 証明書ストアのパスワードに設定。
  • OAuthJWTIssuer：OAuth クライアントID に設定。
  • OAuthJWTSubject：OAuth 接続アプリケーションで設定した許可されたユーザープロファイルのユーザー名（E メールアドレス）に設定。

Note： このフローではリフレッシュトークンは発行されません。

AzureAD

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

  • SSOExchangeUrl：The UMSaaSCloud OAuth 2.0 token endpoint for the identity provider. This can be found in the UMSaaSCloud account settings by navigating to Administration Setup > Security Controls > SAML Single Sign-On Settings and then choosing the desired organization.

この構成には、2つのAAD アプリケーションが必要であることに注意してください：シングルサインオンに使用される"UMSaaSCloud" アプリケーションと、"UMSaaSCloud" アプリケーションに対するuser_impersonation 権限を持つ別の"コネクタ" アプリケーションです。 OAuth 接続プロパティも指定する必要があります。

  • OAuthClientId：アプリ登録の概要セクションにリストされている、コネクタアプリケーションのアプリケーションId。
  • OAuthClientSecret：コネクタアプリケーションのクライアントシークレット値。新しいクライアントシークレットを作成すると、Azure AD にこれが表示されます。

以下のSSOProperties を使用して、AzureAD へ認証します。

  • Resource：アプリ登録の概要セクションにリストされている、UMSaaSCloud アプリケーションのアプリケーションId URI。ほとんどの場合、これはカスタムUMSaaSCloud ドメインのURL です。
  • AzureTenant：アプリケーションが登録されているAzure AD テナントのId。

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

AuthScheme=AzureAD;InitiateOAuth=GETANDREFRESH;OAuthClientId=3ea1c786-d527-4399-8c3b-2e3696ae4b48;OauthClientSecret=xxx;SSOProperties='Resource=https://example.my.salesforce.com;AzureTenant=6ee709df-9de0-4cdf-10e6b7a51d95';

Okta

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

  • User：Okta ユーザーに設定。
  • Password：ユーザーのOkta パスワードに設定。
  • SSOLoginURL：SSO プロバイダーが使用するログインURL に設定。
  • SSOExchangeUrl：The UMSaaSCloud OAuth 2.0 token endpoint for the identity provider. This can be found in the UMSaaSCloud account settings by navigating to Administration Setup > Security Controls > SAML Single Sign-On Settings and then choosing the desired organization.
SSOProperties で、必要に応じて以下の入力パラメータを設定します。
  • APIToken（オプション）：顧客がOkta org から作成したAPI Token に設定。Okta クライアントリクエストコンテキストをオーバーライドする、信頼されたアプリケーションまたはプロキシ経由でユーザーを認証する場合には、これを使用する必要があります。
  • MFAType（オプション）：MFA フローを設定した場合にのみ設定。現時点では、次のタイプのみをサポートしています：OktaVerify、Email、およびSMS。
  • MFAPassCode（オプション）：MFA フローを設定した場合にのみ設定。 空 / 無効に設定されている場合、ドライバーは最初にMFA チャレンジを発行し、設定されたMFA タイプに基づいてプラットフォームがデバイスまたはE メールでワンタイムパスワードを送信するようにトリガーします。 取得したワンタイムパスワードの値をMFAPassCode 接続プロパティに渡す別の接続を再発行する必要があります。

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

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

OneLogin

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

  • User：OneLogin ユーザーに設定。
  • Password：ユーザーのOneLogin パスワードに設定。
  • SSOExchangeUrl：The UMSaaSCloud OAuth 2.0 token endpoint for the identity provider. This can be found in the UMSaaSCloud account settings by navigating to Administration Setup > Security Controls > SAML Single Sign-On Settings and then choosing the desired organization.
OneLogin へ認証するには、以下のSSOProperties が必要です。

  • OAuthClientId：［Developers］->［API Credentials］->［Credential］->［ClientId］を選択して取得できるOAuthClientId に設定。
  • OAuthClientSecret：［Developers］->［API Credentials］->［Credential］->［ClientSecret］を選択して取得できるOAuthClientSecret に設定。
  • Subdomain：SSO アプリにアクセスするOneLogin ユーザーのサブドメインに設定。例えば、OneLogin URL がsplinkly.onelogin.com の場合、サブドメインの値としてsplinkly を入力します。
  • AppId：SSO アプリのId に設定。
  • リージョン（オプション）：OneLogin アカウントで使用しているリージョンに設定。OneLogin API は複数のリージョンで動作し、このプロパティは正しいドメインを見つけるために使用されます。次の値の1つを取ります。
    • US（デフォルト）
    • EU

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

AuthScheme=OneLogin;User=OneLoginUserName;Password=OneLoginPassword;SSOProperties='OAuthClientID=3fc8394584f153ce3b7924d9cd4f686443a52b;OAuthClientSecret=ca9257fd5cc3277abb5818cea28c06fe9b3b285d73d06;Subdomain=OneLoginSubDomain;AppId=1433920';

PingFederate

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

  • User：PingFederate ユーザーに設定。
  • Password：ユーザーのPingFederate パスワードに設定。
  • SSOLoginURL：SSO プロバイダーが使用するログインURL に設定。
  • SSOExchangeUrl：The UMSaaSCloud OAuth 2.0 token endpoint for the identity provider. This can be found in the UMSaaSCloud account settings by navigating to Administration Setup > Security Controls > SAML Single Sign-On Settings and then choosing the desired organization.
SSOProperties のうちPingFederate への認証には以下があります。

  • AuthScheme（オプション）：IdP エンドポイントに使われる認可スキーム。IdP にはNone またはBasic が使用可能です。
追加で次のSSOPropertiesを使って、SSOLoginURL 用の相互SSL 認証（WS-Trust STS エンドポイント）の設定が可能です。
  • SSLClientCert
  • SSLClientCertType
  • SSLClientCertSubject
  • SSLClientCertPassword
以下は接続文字列の例です。 
AuthScheme=PingFederate;User=pingFederateUser;Password=pingFederatePassword;SSOLoginURL='https://<authority>/idp/sts.wst';SSOExchangeUrl='https://domain.my.salesforce.com/services/oauth2/token?so=00D3000006JDF';

ADFS

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

  • User：ADFS ユーザーに設定。
  • Password：ユーザーのADFS パスワードに設定。
  • SSOLoginURL：SSO プロバイダーが使用するログインURL に設定。
  • SSOExchangeUrl：The UMSaaSCloud OAuth 2.0 token endpoint for the identity provider. This can be found in the UMSaaSCloud account settings by navigating to Administration Setup > Security Controls > SAML Single Sign-On Settings and then choosing the desired organization.

ADFS へ認証するには、以下のSSOProperties が必要です。

  • RelyingParty：この属性は、UMSaaSCloud のADFS サーバー上のRelying Party Identifier の値です。
以下は接続文字列の例です。 
AuthScheme=ADFS;User=username;Password=password;SSOLoginURL='https://sts.company.com';SSOProperties='RelyingParty=https://saml.salesforce.com';

ADFS 統合

ADFS 統合フローでは、現在ログインしているWindows ユーザーの資格情報で接続します。 ADFS 統合フローを使用するには、User およびPassword を指定せず、それ以外の設定は上記のADFS ガイドと同じ手順を実行してください。

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 24.0.9062