CData 製品で OAuth を使い始める


OAuth 2.0 は、API クライアントが Web サーバー上のユーザーデータに制限付きでアクセスできるようにする認可プロトコルです。Facebook、Google、GitHub をはじめとする多くの著名なアプリケーションの API で使用されています。OAuth は、認証シナリオ（「Grant Type」やフローとも呼ばれます）に基づいており、リソースオーナーやユーザーが認証情報を開示することなく、リソースサーバーの保護されたコンテンツを共有できるようにします。これを実現するために、OAuth 2.0 サーバーはアクセストークンを生成し、クライアントプログラムがリソースオーナーに代わって制限されたリソースにアクセスできるようにします。OAuth 2.0 の詳細については、oauth.net および RFC 6749 をご参照ください。

この記事では、CData 製品を使用して OAuth 認可を行うさまざまなプロセスについて説明します。OAuth 2.0 の Grant Type の中で最も一般的な「Code」または「Authorization Code」Grant Type に焦点を当てています。以下の説明では CData JDBC Driver for Salesforce を例として使用していますが、これらの原則はデータソースやクライアントアプリケーションに関係なく適用できます。一部の OAuth フローをトリガーするには、カスタム SQL クエリを実行できる環境が必要です。

目次

（オプション）Salesforce でカスタム OAuth アプリを作成する

以下は、Salesforce でカスタムアプリケーションを作成する手順です。

  1. Salesforce アカウントにログインします

  2. Salesforce アカウントの右上にある「設定」に移動します
  3. クイック検索ボックスに「Apps」と入力し、ドロップダウンから「アプリケーションマネージャ」を選択して、「新規接続アプリケーション」リンクをクリックしてアプリケーションを作成します

  4. 新規接続アプリケーションセクションで、「接続アプリケーション名」、「API 参照名」、「取引先責任者メール」を入力します

  5. API（OAuth 設定の有効化）チェックボックスを有効にし、「コールバック URL」を入力して、アプリケーションがユーザーにリクエストする必要のある OAuth スコープの権限を選択します。例：「refresh_token」や「offline_access」などのスコープは、リフレッシュトークンを取得し、いつでもリクエストを実行するために必要です。データを取得するには、フルアクセス（full）または API（API 経由でユーザーデータを管理）を使用します

  6. 「保存」をクリックしてカスタム OAuth アプリケーションを作成します
  7. 新規接続アプリケーションの「API（OAuth 設定の有効化）」セクションで、「コンシューマの詳細を管理」をクリックして、「Client ID」（コンシューマキー）と「Client Secret」（コンシューマシークレット）を取得します。これらは後で CData Salesforce JDBC ドライバーでこのアプリケーションに接続する際に使用します

デスクトップアプリケーションで OAuth を実行する

埋め込み OAuth 資格情報を使用する場合

多くのデータソースに対して、CData は OAuth デスクトップ認証を簡素化する埋め込み OAuth 資格情報を提供しています。

Salesforce JDBC ドライバーで埋め込み OAuth 資格情報を使用して接続するには、以下の手順に従います。

  1. CData JDBC ドライバーをダウンロードしてインストールします
  2. インストールパスに沿って Salesforce JDBC ドライバーに移動し、「lib」フォルダを開きます。
    パス（例）：C:\Program Files\CData\CData JDBC Driver for Salesforce 2022\lib
  3. 実行可能な JAR ファイル「cdata.jdbc.salesforce.jar」を開いて、JDBC URL 設定ウィザードを起動します
  4. 「AuthScheme」を OAuth に設定し、「InitiateOAuth」を GETANDREFRESH に設定します
  5. 「Test Connection」をクリックします
  6. ユーザーは Salesforce ログインページにリダイレクトされ、必要な資格情報（ユーザー名とパスワード）を入力します
  7. 正しい資格情報を入力すると、「Salesforce Authorization Successful」画面が表示されます

  8. JDBC ドライバーが接続の成功を通知します（下記参照）。

カスタム OAuth アプリケーションに接続する場合（デスクトップ）

  1. デスクトップ認証の「埋め込み OAuth を使用する場合」で説明した手順 1 〜 4 に従います
  2. さらに、「InitiateOAuth」を GETANDREFRESH に設定するとともに、カスタム OAuth アプリケーションから保存した「Client ID」と「Client Secret」の詳細を入力します（上記の「Salesforce でカスタム OAuth アプリを作成する」を参照）

  3. 接続すると、ドライバーはデフォルトのブラウザで OAuth エンドポイントを開きます。ログインしてアプリケーションに権限を付与してください。

  4. その後、ドライバーは以下のように OAuth プロセスを完了します。
    • 「Callback URL」からアクセストークンを抽出します。
    • 古いアクセストークンの有効期限が切れると、新しいアクセストークンを取得します。
    • OAuth の値を「OAuthSettingsLocation」に保存し、接続間で永続化します。

    Web アプリケーションで OAuth を実行する

    Web アプリケーション経由で接続する場合は、Salesforce にカスタム OAuth アプリケーションを登録する必要があります。詳細については、この記事の「Salesforce でカスタム OAuth アプリを作成する」セクションを参照してください。その後、ドライバーを使用して OAuth トークン値を取得および管理できます。

    注意：このプロセスは通常、Web アプリケーションで SQL ストアドプロシージャを使用して実装されますが、ここでは DBeaver でストアドプロシージャを実行します。

    カスタム Web アプリケーションに接続するためのアクセストークンとリフレッシュトークンを取得するには、以下の手順に従います。

    （オプション）DBeaver で接続を作成する

    1. DBeaver（Java ベースのツール）を開き、Database ドロップダウンの「Driver Manager」オプションに移動します

    2. 「New」をクリックし、「Libraries」タブに移動して「Add File」をクリックし、実行可能な Jar ファイル cdata.jdbc.salesforce を選択します。パスを選択し、「Find Class」をクリックして、生成されたドライバーを選択します

    3. 「Settings」タブを選択し、テスト用の新しいドライバー名を追加します（例：CData_WebApp）。「OK」をクリックします。これで「CData_WebApp」という名前のデータベースが DBeaver に作成されました

    4. 再度「Database」ドロップダウンに移動し、「New Database Connection」を選択します。作成したデータベースを選択し、「Next」をクリックします

    5. JDBC URL フィールドに接続 URL を入力し、「Test Connection」をクリックしてから「Finish」をクリックします。 
      jdbc:salesforce:OAuthClientID='XXXX';OAuthClientSecret='XXXX';InitiateOAuth=OFF;

      ClientID と ClientSecret は、カスタム OAuth Web アプリケーションから保存した詳細です

    6. 接続文字列を定義すると、左側のパネルの「General」と DBeaver ツールの「Connections」タブの両方に新しいデータベース接続が表示されます。接続を右クリックし、「SQL Editor」に移動して「Open SQL Script」をクリックします。メニューバーの「SQL Editor」からも同様に選択できます

    ストアドプロシージャを呼び出して OAuth 交換を完了する

    1. GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL 入力を、アプリケーション設定で指定したコールバック URL に設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。このストアドプロシージャは OAuth エンドポイントの URL を返します。 例として、「GetAuthorizationURL」ストアドプロシージャを実行します。 
      EXEC GetoAuthauthorizationURL
  @CallbackUrl='http://localhost:33333',
  @Grant_Type='CODE';
    2. URL を開き、ログインしてアプリケーションを認可します。ブラウザでコールバック URL にリダイレクトされます。取得した URL の「=」演算子の後のコードの内容をコピーし、URL デコーダー（URL Decoder）を使用してこのコードの実際の値をデコードします。デコードされた値が OAuthVerifier です。この verifier をマシンのどこかに保存してください。
    3. GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode 入力を WEB に設定します。Verifier 入力を、コールバック URL のクエリ文字列の「code」パラメータに設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。 上記のように、「GetOAuthAccessToken」ストアドプロシージャを実行します。 
      EXEC GetOAuthAccessToken
  @appmode=WEB,
  @Verifier='XXXX',
  @GrantType='CODE';

    4. 上の図に示すように、アクセストークンとリフレッシュトークンが取得されました。これでデータに接続し、以下の手順で OAuth アクセストークンを自動または手動で更新できます。

    OAuth アクセストークンの自動更新：

    ドライバーに OAuth アクセストークンを自動的に更新させるには、最初のデータ接続で以下を設定します。

    • InitiateOAuth：REFRESH に設定します。
    • OAuthClientId：アプリケーション設定の Client Id に設定します。
    • OAuthClientSecret：アプリケーション設定の Client Secret に設定します。
    • OAuthAccessToken：GetOAuthAccessToken が返したアクセストークンに設定します。
    • OAuthRefreshToken：GetOAuthAccessToken が返したリフレッシュトークンに設定します。
    • OAuthSettingsLocation：ドライバーが OAuth トークン値を保存するパスに設定します。このパスは接続間で永続化されます。

    「Test Connection」をクリックすると、ドライバーが接続の成功を通知します（下図参照）

    以降のデータ接続では、OAuthAccessToken と OAuthRefreshToken の値は OAuthSettingsLocation から取得されます。

    OAuth アクセストークンの手動更新：

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

    GetOAuthAccessToken が返した「ExpiresIn」パラメータ値が経過した後、「RefreshOAuthAccessToken」ストアドプロシージャを実行して新しいトークンを取得します。

    EXEC RefreshOAuthAccessToken
  @OAuthRefreshToken='XXXX'

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

    ヘッドレスマシンで OAuth を実行する

    ヘッドレスマシンとは、UI を持たないマシンのことです。ブラウザをサポートしておらず、ブラウザプロンプトを開くことができません。UI 機能を必要としないデバイスは、ヘッドレスモードに設定できます。この場合、UI スタックが無効になり、UI アプリケーションは起動しません。これにより、使用されるシステムリソースの量が削減されます。

    ヘッドレスマシンの例としては、UNIX、CentOS、Linux などがあります。

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

    1. 以下の2つのオプションのいずれかを選択します。
      • オプション 1：以下の「Verifier コードの取得と交換」で説明されているように「OAuthVerifier」値を取得します。
      • オプション 2：ブラウザを持つマシンにドライバーをインストールし、通常のブラウザベースのフローで認証した後、OAuth 認証値を転送します。
    2. その後、ヘッドレスマシンでアクセストークンを自動的に更新するようにドライバーを設定します。

    オプション 1：Verifier コードの取得と交換

    1. ローカルマシンで DBVisualizer、DBeaver などの JDBC ツール（ここでは DBeaver を使用）を使用して、ドライバー（CData_Headless）との接続を確立します。接続文字列の例は以下のようになります。 
      jdbc:salesforce:OAuthClientID='XXXX';OAuthClientSecret='XXXX';InitiateOAuth=OFF;
      ご覧のとおり、上記の接続文字列では OAuthClientID、OAuthClientSecret、および InitiateOAuth を「OFF」として定義する必要があります

    2. 次に、「GetOAuthAuthorizationUrl」ストアドプロシージャを実行します。 
      EXEC GetOAuthAuthorizationUrl
  @CallbackUrl='http://localhost:33333',
  @Grant_Type='Code';

      ここで、カスタム OAuth アプリで設定した正しい CallbackURL を指定していることを確認してください。アプリの設定で http://localhost:33333 を CallbackURL として使用することもできます。 「GetOAuthAuthorizationUrl」ストアドプロシージャを実行すると、結果として URL が取得されます。この URL フィールドの値をコピーし、マシンの新しいブラウザで実行します。以下のようなエラーメッセージと URL 内のコードが表示されます。

      この新しいブラウザの URL は以下のようになります（下図参照）。 http://localhost:33333/?code=XXXXXX%3D%3D...

      上記のコードの「=」演算子の後の内容をコピーし、URL Decoder を使用してこのコードの実際の値をデコードします。デコードされた値が OAuthVerifier です。この verifier をマシンのどこかに保存してください。

    3. 次に、「GetOAuthAccessToken」ストアドプロシージャを実行します。 
      EXEC GetOAuthAccessToken
  @Verifier = 'XXXX',
  GrantType='CODE'

      OAuthAccessToken フィールドの下にアクセストークンが表示されます。このアクセストークンをコピーし、DBeaver の JDBC URL インスタンスで以下のような新しい接続 URL を作成します。

      jdbc:salesforce:OAuthClientID='XXXX';OAuthClientSecret='XXXX';InitiateOAuth=REFRESH;OAuthAccessToken='XXXX';OAuthRefreshToken='XXXX';

      上記の接続文字列には、OAuthClientID、OAuthClientSecret、「REFRESH」に設定した InitiateOAuth、および「GetOAuthAccessToken」ストアドプロシージャを実行して取得した OAuthAccessToken と OAuthRefreshToken が含まれています。

      この取得した接続文字列を、ヘッドレスマシンで直接コピーして使用し、OAuth カスタムアプリケーションに接続できます。

      また、接続文字列をテストするには、CData Salesforce ドライバーの JAR ファイルに正確な詳細を入力します。接続できれば、接続文字列は準備完了です。

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

      ヘッドレスマシンで接続する前に、インターネットブラウザをサポートするデバイスにドライバーをインストールして接続を作成する必要があります。上記の「デスクトップアプリケーション」で説明したように接続プロパティを設定します。

      「デスクトップアプリケーション」の手順を完了すると、結果として得られた認証値は暗号化され、OAuthSettingsLocation で指定されたパスに書き込まれます。デフォルトのファイル名は OAuthSettings.txt です。 接続のテストが成功したら、OAuth 設定ファイルをヘッドレスマシンにコピーします。

      ヘッドレスマシンでデータに接続するには、以下の接続プロパティを設定します。

      • InitiateOAuth：REFRESH に設定します。
      • OAuthClientId：（カスタムアプリケーションのみ）アプリケーションを登録したときに割り当てられた Client Id に設定します。
      • OAuthClientSecret：（カスタムアプリケーションのみ）アプリケーションを登録したときに割り当てられた Client Secret に設定します。
      • OAuthSettingsLocation：OAuth 設定ファイルのパスに設定します。アクセストークンの自動更新を有効にするために、このファイルがドライバーに読み取りおよび書き込み権限を付与していることを確認してください。

In this article

Related articles