CData の連携ソリューションでOAuth を利用する方法

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

この記事では、OAuth 2.0 のグラントタイプの中で最も一般的である「コード」（または「認可コード」）に焦点を当て、CData の連携ソリューションを使用してOAuth 認証を利用するためのさまざまなプロセスについて説明します。以下の説明ではCData JDBC Driver for Salesforce を使用していますが、使用するデータソースやクライアントアプリケーションに関係なく同様に設定できます。OAuth フローの一部をトリガーするために、カスタムSQL クエリを使用する必要があります。

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

このセクションでは、Salesforce でカスタムアプリケーションを作成する方法を順を追って説明します。

Salesforce アカウントにログインします。
Salesforce アカウントページの右上にある「設定」をクリックして移動します。
クイック検索ボックスに「アプリケーション」と入力して、ドロップダウンから「アプリケーションマネージャ」に移動し、「新規接続アプリケーション」リンクをクリックしてアプリケーションを作成します。
新規接続アプリケーションセクションで、「接続アプリケーション名」、「API 参照名」、「取引先責任者メール」を入力します。
「API（OAuth 設定の有効化）」チェックボックスを有効にし、「コールバックURL」を入力、さらにアプリケーションがユーザーに要求するOAuth のアクセス許可の範囲を選択します。例：refresh_token、offline_access などのスコープは、リフレッシュトークンを取得していつでもリクエストを実行するために必要な権限です。データを取得するには、フルアクセス（full）またはデータへのアクセスと管理（api）を使用します。
「保存」をクリックしてカスタムOAuth アプリケーションを作成します。
新しく作成した接続アプリケーションのAPI（OAuth 設定の有効化）セクションで、「コンシューマの詳細を管理」をクリックし、後でCData Salesforce JDBC Driver を使ってこのアプリケーションに接続するために使用する、「Client ID」（Consumer Key）と「Client Secret」（Consumer Secret）を取得します。

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

埋め込みOAuth クレデンシャルを使用する場合

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth クレデンシャルを多くのデータソースに提供しています。

Salesforce JDBC Driver に埋め込みOAuth クレデンシャルで接続するには、次の手順を実行します。

CData JDBC Driver をダウンロードしてインストールします。
Salesforce JDBC Driver のインストールパスにある「lib」フォルダを開きます。
パス（例）：C:\Program Files\CData\CData JDBC Driver for Salesforce 2022\lib
「cdata.jdbc.salesforce.jar」（実行可能なJAR ファイル）を開き、JDBC URL の設定ウィザードを開きます。
「AuthScheme」をOAuth に、「InitiateOAuth」をGETANDREFRESH に設定します。
「接続テスト」をクリックします。
Salesforce のログインページにリダイレクトされるので、要求される認証情報（ユーザー名とパスワード）を入力します。
正しい認証情報を入力すると、Salesforce の認証が成功したことを知らせる画面が表示されます。
JDBC ドライバーは、接続に成功すると以下のメッセージを表示します。

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

はじめに、デスクトップ認証の「埋め込みOAuth クレデンシャルを使用する場合」の手順1～4を実行します。
さらに、「InitiateOAuth」をGETANDREFRESH に設定し、カスタム OAuth アプリケーションの「Client ID」および「Client Secret」を入力します（前述の「Salesforce でカスタムOAuth アプリケーションを作成する」を参照）。
接続すると、ドライバーはデフォルトブラウザでOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。
その後、ドライバーは次の手順でOAuth プロセスを完了します。
- 「Callback URL」からアクセストークンを取得。
- 古いトークンの期限が切れたときは、新しいアクセストークンを取得。
- 「OAuthSettingsLocation」にOAuth 値を保存し、接続間で永続化。
Web アプリケーションでOAuth を利用する

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

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

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

（オプション）Dbeaver で接続を作成する
1. DBeaver（Java ベースのツール）を開き、「データベース」のドロップダウンから「ドライバーマネージャー」を選択します。
2. 「新規」ボタンをクリックし、「ライブラリ」タブで「ファイルを追加」をクリックして、実行可能なJar ファイルであるcdata.jdbc.salesforce を選択します。パスを選択して「クラスを見つける」をクリックし、生成されたドライバーを選択します。
3. 「設定」タブを選択し、テスト用の新しいドライバー名を追加します（例：CData_WebApp）。「OK」をクリックします。「CData_WebApp」という名前のデータベースがDBeaver に作成されました。
4. 再度「データベース」のドロップダウンから「新しい接続」を選択します。作成されたデータベースを選択し、「次へ」をクリックします。
5. JDBC URL フィールドに接続URL を入力し、「テスト接続」をクリックして接続を確認できたら「終了」をクリックします。jdbc:salesforce:OAuthClientID='XXXX';OAuthClientSecret='XXXX';InitiateOAuth=OFF;
  ClientID とClientSecret は、カスタムOAuth Web アプリケーションで保存された情報です。
6. 接続文字列を定義すると、DBeaver ツールの「接続」タブに加え、左パネルの「一般」にも新しいデータベース接続が表示されるようになります。接続を右クリックし、「SQL エディタ」から「SQL スクリプトを開く」をクリックします。メニューバーの「SQL エディタ」からも選択できます。
ストアドプロシージャを呼び出してOAuth 交換を完了する
1. GetOAuthAuthorizationUrl ストアドプロシージャを呼び出します。CallbackURL インプットをアプリケーション設定で指定したコールバックURL に設定します。必要に応じて、Scope パラメータを設定してカスタム権限をリクエストします。ストアドプロシージャがOAuth エンドポイントのURL を返します。例として、「GetAuthorizationURL」ストアドプロシージャを実行します。EXEC GetoAuthauthorizationURL @CallbackUrl='http://localhost:33333', @Grant_Type='CODE';
2. 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 トークン値を保存するパスに設定。これは接続間で永続化します。
「接続テスト」をクリックすると、下図のように接続が成功したことを知らせるメッセージが表示されます。

次回のデータ接続では、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. 以下のオプションから選択します。
  - オプション1：後述の「Verifier コードを取得および交換する」に従って、OAuthVerifier 値を取得します。
  - オプション2：ブラウザに対応したマシンにドライバーをインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。
2. 次に、ヘッドレスマシンでアクセストークンを自動的にリフレッシュするようにドライバーを設定します。
オプション1：Verifier コードを取得および交換する
1. ローカルマシンのドライバー（CData_Headless）で正常に接続を確立するには、DBVisualizer やDBeaver などのJDBC ツール（ここではDBeaver を使用）に次のサンプルのような接続文字列を入力します。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'
  
  AccessToken はOAuthAccessToken フィールドの下に表示されます。このAccessToken をコピーし、Dbeaver JDBC URL インスタンスで次のように新しい接続URL を作成します。
  jdbc:salesforce:OAuthClientID='XXXX';OAuthClientSecret='XXXX';InitiateOAuth=REFRESH;OAuthAccessToken='XXXX';OAuthRefreshToken='XXXX';
  上の接続文字列には、OAuthClientID、OAuthClient Secret、「REFRESH」に設定されたInitiateOAuth、「GetOAuthAccessToken」ストアドプロシージャを実行して取得したOAuthAccessToken およびOAuthRefreshToken が含まれます。
  
  取得したこの接続文字列をコピーしてヘッドレスマシンで直接使用することで、OAuth カスタムアプリケーションで接続することができます。
  
  接続文字列をテストするには、CData Salesforce Driver のJAR ファイルに詳細を入力してください。接続テストが成功すれば、接続文字列の準備は完了です。
  
  オプション2：OAuth 設定を転送する
  
  ヘッドレスマシンでの接続の前に、インターネットブラウザに対応したデバイス上のドライバーで、接続をインストールおよび作成する必要があります。上記の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。
  
  「デスクトップアプリケーション」の手順が完了すると、OAuthSettingsLocation で指定されたパスに生成された認証値が暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。接続テストに成功したら、OAuth 設定ファイルをヘッドレスマシンにコピーします。
  
  ヘッドレスマシンで、次の接続プロパティを設定してデータに接続します。
  - InitiateOAuth：REFRESH に設定。
  - OAuthClientId：（カスタムアプリのみ）アプリケーションの登録時に割り当てられたClient Id に設定。
  - OAuthClientSecret：（カスタムアプリのみ）アプリケーションの登録時に割り当てられたClient Secret に設定。
  - OAuthSettingsLocation：OAuth 設定ファイルのパスに設定。アクセストークンの自動リフレッシュを有効にするために、このファイルがドライバーに読み書きのアクセス許可を与えることを確認してください。