CData コネクタでの OAuth 認可コードグラントの実装ガイド


OAuth は、ユーザーの資格情報をサードパーティアプリケーションに公開することなく、トークンベースの安全な認証を実現する仕組みです。 最新の API やクラウドサービスで推奨される認証方式であり、きめ細かい権限スコープによる委任アクセスを可能にします。

このガイドでは、CData コネクタが認可コードグラントフローをデスクトップ、Web、ヘッドレス環境でどのように実装するかを解説します。 ここで紹介する原則は、InitiateOAuth 接続プロパティを備えるすべてのコネクタに適用されます。

目次


OAuth グラントタイプ

OAuth を必要とするサービスへの初回接続では、まず OAuth トークンを取得する必要があります。 トークンの取得方法は、環境やアプリケーションの種類によって異なります。

CData コネクタは、トークン取得のために複数の OAuth グラントタイプに対応しています。 ただし、すべてのデータソースがすべてのオプションをサポートしているわけではありません。

認可コード

この認証スキームでは、ユーザーがインターネットブラウザでデータソースの Web ページに遷移し、ログインを行います。 ログイン完了後、認証コードが呼び出し元のアプリケーションにリダイレクトされます。

このコードは、有効期間の短いアクセストークンと有効期間の長いリフレッシュトークンに交換されます。 リフレッシュトークンを使用すると、追加のユーザー操作なしにアクセストークンを更新できます。

認可コードフローは、コネクタの AuthScheme に OAuth、OAuthPKCE、SharePointOAuth、AzureADPKCE、または AzureAD を指定した場合に実行されます。

クライアント資格情報

この認証スキームでは、コネクタがエンドユーザーのソースシステムに登録された資格情報を使用して、アクセストークンとリフレッシュトークンを取得します。 認可コードフローとは異なり、資格情報と取得されたアクセストークンにはユーザーコンテキストがありません。

このフローでは、Web ブラウザでのユーザー操作は不要です。 クライアント資格情報フローは、AuthScheme に OAuthClient、AzureMSI、AzureServicePrincipal、または AzureServicePrincipalCert を指定した場合に実行されます。

JWT Bearer

この認証スキームでは、コネクタが署名済みの JSON Web Token（JWT）をデータソースのアクセストークンと交換します。 署名には暗号化証明書が使用されます。

これは一般的にサービスアカウントで利用され、Web ブラウザでのユーザー操作は不要です。 JWT Bearer フローは、AuthScheme の値が OAuthJWT の場合に実行されます。

パスワード

この認証スキームでは、コネクタが OAuth アプリ情報とユーザーの資格情報を使用してアクセストークンを取得します。 Web ブラウザでのユーザー操作は不要です。

ユーザーのパスワードを収集してサーバーに送信する必要があるため、このフローはセキュリティが低く、レガシーな方式とされています。 パスワードフローは、AuthScheme に OAuthPassword または AzurePassword を指定した場合に実行されます。


InitiateOAuth プロパティ

InitiateOAuth 接続プロパティは、OAuth をサポートするすべての CData コネクタに用意されています。 このプロパティは、OAuth トークンの開始およびリフレッシュをコネクタがどのように処理するかを制御します。

連携の仕組みに合わせてこのプロパティを正しく設定することが重要です。 以下の3つのオプションがあります：

値 動作
GETANDREFRESH コネクタが初回のトークン取得、および必要に応じたトークンのリフレッシュと保存を管理します。
REFRESH コネクタがトークンのリフレッシュと保存を管理しますが、初回の取得は行いません。アプリケーション側で初回のアクセストークンとリフレッシュトークンを提供する必要があります。
OFF コネクタはトークンの取得やリフレッシュを一切行いません。アクセストークンは OAuthAccessToken プロパティを通じて渡す必要があります。

一般的に、トークンのリフレッシュはコネクタに管理させることを推奨します。 これにより、クエリの実行中にトークンが期限切れになった場合でも、トークンの有効性が維持されます。

OAuth トークン自動リフレッシュの詳細

アクセストークンが取得される際、リフレッシュトークン、「有効期限」の値、およびタイムスタンプも同時に取得されます。 タイムスタンプはアクセストークンの取得日時を示し、有効期限の値はアクセストークンの有効期間を示します（サービスによって異なります）。

InitiateOAuth を GETANDREFRESH または REFRESH に設定した場合、コネクタはタイムスタンプと有効期限の値を現在のシステム時刻と比較します。 トークンが期限切れでなければ、現在のアクセストークンがそのまま使用されます。 期限切れの場合、コネクタは新しいアクセストークンのリフレッシュまたは取得のリクエストを送信します。

中断を防ぐため、コネクタはアクセストークンの残り有効期間が 10% 未満になった時点でリフレッシュを実行します。 また、クエリ実行中に必要になった場合もトークンをリフレッシュします。

たとえば、長時間実行されるクエリで結果セットのページングを行っている最中にトークンが無効になった場合、コネクタは無効なトークンのレスポンスを受信後、トークンをリフレッシュしてからリクエストを再送信します。 コネクタにトークンを管理させない設定（InitiateOAuth=OFF）の場合は、このようなリトライの必要性をアプリケーション側で考慮する必要があります。


認可コードフロー：Web アプリケーション

Web アプリケーションで認可コードフローを使用して認証を行う場合、エンドユーザーを対象サービスの認可 URL にリダイレクトする必要があります。 認証後、Web アプリケーション内のページにリダイレクトで戻す必要もあります。

CData コネクタはこのフローのリダイレクトを自動化できません。エンドユーザーをアプリケーション内の特定の URL にリダイレクトで戻す必要があるためです。 そのため、まずソースシステムにカスタム OAuth アプリケーションを作成する必要があります。

この「OAuth アプリケーション」はソースシステムにおける資格情報の登録を指すものであり、コネクタを実行する Web アプリケーションとは異なります。 詳細は「カスタム OAuth アプリケーションの作成」セクションを参照してください。

Web アプリケーション用のストアドプロシージャ

コネクタには、Web アプリケーションで OAuth フローを開始・管理するためのストアドプロシージャが用意されています：

  • GetOAuthAuthorizationURL — ユーザーをサービスで認証させるためのリダイレクト先 URL を取得します。
  • GetOAuthAccessToken — ユーザーがサービスでの認証を完了した後、OAuth アクセストークンを取得します。

実行の概要

Web アプリケーションフローの実行概要（アプリケーション／ユーザーの視点）は以下のとおりです：

  1. バックグラウンドで、コネクタを実行するアプリケーションが InitiateOAuth=OFF および OAuthClientId=<YourAppClientId> を指定して新しい接続を作成します。
  2. アプリケーションが以下のストアドプロシージャを呼び出します： 
    EXECUTE GetOAuthAuthorizationURL
    AuthMode='WEB',
    CallbackURL='https://oauth.yourdomain.com',
    State='AppURL=customerhost.app.com:port'
  3. アプリケーションが、上記の呼び出しで返された URL にユーザーをリダイレクトします。 この Web ページでは、ユーザーにサービスへのログインが求められます。
  4. OAuth アプリケーションが https://oauth.yourdomain.com（OAuth アプリ作成時に定義された URL）にリダイレクトします。 oauth.yourdomain.com の小規模な Web アプリが State パラメータを解析し、その値（AppURL）にブラウザをリダイレクトする必要があります。 Verifier の値もアプリケーションに渡す必要があります。

    注意：AppURL にブラウザをリダイレクトする前に、これらの値をエンコードすることを推奨します。プレーンテキストのパラメータとして送信されるのを防ぐためです。
  5. Web アプリケーションが HTTP レスポンスから Verifier を読み取り、以下のストアドプロシージャを呼び出す必要があります： 
    EXECUTE GetOAuthAccessToken
    Verifier='&lt;VerifierFromHTTPResponse&gt;',
    AppMode='WEB'
    このプロシージャの呼び出しにより、OAuthAccessToken、OAuthRefreshToken、および ExpiresIn が返されます。

トークン自動リフレッシュの設定

コネクタがトークンを自動的にリフレッシュするように設定するには、InitiateOAuth=REFRESH を指定して新しい接続を作成します。 あわせて OAuthRefreshToken、OAuthClientId、OAuthClientSecret も設定してください。

この設定により即時リフレッシュがトリガーされ、OAuth 認証情報が設定済みのトークンストアに保存されます。 アプリケーションが直接取得したトークンはすべて破棄できます。

あるいは、Verifier をコネクタに渡してトークンを取得させることもできます。 InitiateOAuth=REFRESH、OAuthVerifier、OAuthClientId、OAuthClientSecret を指定して新しい接続を作成してください。 コネクタが OAuth トークンを取得し、設定済みのトークンストアに追加します。

PKCE を使用した認可コードフロー

PKCE を使用した認可コードフローの手順は類似していますが、アプリケーションが PKCEVerifier（ランダムなシークレット文字列）を生成して含める必要があります。 この値は GetOAuthAuthorizationURL と GetOAuthAccessToken の両方の呼び出しに含めてください。


認可コードフロー：デスクトップアプリケーション

デスクトップアプリケーションでは、InitiateOAuth=GETANDREFRESH を指定することで、CData コネクタがブラウザを起動して認可コードフローを自動化できます。 これにより、ユーザーは対象サービスへのログイン画面に誘導されます。

この処理中、コネクタはログイン試行の HTTP レスポンス（コールバック URL）を処理するためのデーモンを作成し、OAuth トークンを取得します。 この場合、CallbackURL はデーモンがリッスンしているポートの localhost に設定されます。

CData デーモンは、認可が成功したかどうかを示すシンプルなページを表示します。 コネクタには、ログイン成功時と失敗時のカスタム HTML ページを指定するための接続プロパティ OEMAuthSuccess と OEMAuthFailure が用意されています。

これらのプロパティはいずれも HTML ファイルへのファイルパスを受け取り、Other 接続プロパティを通じて指定します。


その他のグラントタイプ

クライアント資格情報、JWT Bearer、パスワードフローを使用する場合、InitiateOAuth プロパティは常に GETANDREFRESH に設定できます。 これらのフローでは、手動でのユーザー操作は不要です。

この設定により、コネクタが OAuth トークンの取得、リフレッシュ、保存を自動的に処理します。 必要な接続プロパティは、グラントタイプと接続先のデータソースによって異なります。

ヘッドレスマシン

ヘッドレスサーバーや Web ブラウザを開けないマシンでは、OAuth トークンを取得するためのいくつかの方法があります。 一部のサービス（Google など）では、サイレント認証を使用するサービスアカウントがサポートされています。

ユーザーアカウントでの認証が必要な場合は、別のマシンにドライバーをインストールする方法があります。 そのマシンで接続を作成してブラウザベースの OAuth フローを開始し、完了後に OAuth トークンをヘッドレスマシンに転送します。

別のマシンにドライバーをインストールせずに OAuthVerifier の値を取得する方法もあります：

  1. ヘッドレスマシンで InitiateOAuth を OFF に設定し、その他の必要な接続プロパティもあわせて設定します。
  2. GetOAuthAuthorizationURL ストアドプロシージャを呼び出し、CallbackURL 入力パラメータにアプリ設定で指定した正確なリダイレクト URI を設定します。
  3. 返された URL をブラウザで開き、ログインしてドライバーに権限を付与します。認証が成功すると、認証コードを含むコールバック URL にリダイレクトされます。

認証コードの値を取得したら、ヘッドレスマシンの OAuthVerifier 接続プロパティに設定します。 InitiateOAuth を REFRESH に設定すると、ドライバーが認証コードを使用して OAuth トークンの取得とリフレッシュを行えるようになります。

サービスアカウント

一部のサービスでは、ブラウザでのユーザー認証を必要としないサイレント認証を使用するサービスアカウントが利用できます。 サービスアカウントを使用して、ドライバーにエンタープライズ全体のアクセススコープを委任することも可能です。

サービスアカウントを使用するには、まずカスタム OAuth アプリを作成する必要があります。 サービスアカウントでは、ブラウザでのユーザー認証の代わりに、JWT 証明書を OAuth アクセストークンと交換します。

ドライバーは OAuthJWT*** 接続プロパティを通じてサービスアカウントをサポートします。 InitiateOAuth プロパティを GETANDREFRESH に設定すると、ドライバーによる OAuth アクセストークンの取得が有効になります。

接続を開くと、ドライバーはドライバーが必要とするクレームセットを含む JWT を作成して署名します。 その後、JWT がアクセストークンと交換されます。 トークンが保存され、トークンの有効期限が切れた際には新しいアクセストークンを取得するために JWT を送信してリフレッシュが行われます。


OAuth トークンの保存

OAuth アクセストークンを取得した後、ドライバーが接続やプロセスをまたいでアクセストークンを保持できるように保存できます。 ドライバーには複数のストレージメカニズムが用意されています。

カスタムトークンストレージが必要な高度なシナリオ（データベースバックエンドのストレージやクラウドネイティブソリューションなど）については、CData JDBC ドライバーが ITokenStore インターフェースをサポートしています。カスタムトークンストレージソリューションの構築方法については、ITokenStore インターフェースの実装ガイドを参照してください。

ローカルファイルストレージ

デフォルトでは、ドライバーは OAuthSettingsLocation で指定されたローカルファイルに OAuth トークンを保存します。 ローカルファイルストレージを使用すると、複数の接続間で認証情報を共有できます。

ドライバーにはレースコンディションを処理するロジックが組み込まれており、ある接続が別の接続のトークンを無効にしないようになっています。 接続を閉じても、ローカルファイルはファイルシステム上に残り、新しい接続を開く際に再利用できます。

OAuthSettings ファイルは、別のマシン（ヘッドレスマシンなど）に転送して、同じ認証情報で接続を作成することもできます。 OAuthSettings ファイルを使用する場合、設定が必要なのは InitiateOAuth と OAuthSettingsLocation のみです。

ローカルファイルに保存されるトークンの値は暗号化されているため、容易に読み取ることはできず、ドライバーによってのみ復号されます。 複数ユーザーのシナリオでは、ユーザーごとにカスタムファイルパスを設定できます。

メモリストレージ

ローカルファイルストレージが利用できないユースケースでは、メモリストレージを使用できます。 メモリロケーションは、OAuthSettingsLocation の値を memory:// で始め、その後に一意の識別子を続けて指定します（例：memory://user1）。

⚠️ セキュリティに関する警告

メモリストレージから取得されたトークンの値は暗号化されていません。トークンが安全に保存され、暗号化されたチャネルでのみ送信されるようにしてください。暗号化が重要な本番環境では、ローカルファイルストレージまたは S3 Blob ストレージの使用を検討してください。

ローカルファイルストレージとは異なり、接続を閉じる際にトークンを手動で保存し、新しい接続を開く際に再利用する必要があります。 OAuth の値は、sys_connection_props システムテーブルへのクエリで取得できます： 

SELECT Name, Value FROM sys_connection_props
WHERE Name IN ('OAuthAccessToken', 'OAuthRefreshToken', 'OAuthExpiresIn', 'OAuthTimestamp')

新しい接続を開く際に、対応する OAuth*** 接続プロパティを使用して同じ値を設定できます。

メモリストレージはスレッド間で共有されますが、プロセス間では共有されません。

S3 Blob ストレージ

CData ドライバーは、S3 Blob に OAuth トークンを保存できます。 この機能は、EC2 インスタンス、または EC2 上で実行される AWS サービス（Glue や Lambda など）で使用する場合にのみ利用可能です。

ドライバーは、実行中の EC2 マシンに割り当てられた IAM ロールを使用して認証を行います。 このストレージメカニズムを有効にするには、OAuthSettingsLocation を s3:// で始まる値に設定し、その後に一意の識別子を続けます（例：s3://user1）。

ドライバーには、空の S3 Blob を使用したレースコンディションを回避するためのロックメカニズムが組み込まれています。


カスタム OAuth アプリケーションの作成

OAuth 認証を行うには、ソースシステムに OAuth アプリケーションを登録する必要があります。 クライアント資格情報、JWT Bearer、パスワードフローでは、エンドユーザーが直接アプリケーションを作成します。

OAuth 認証をサポートする各コネクタのヘルプドキュメントには、カスタム OAuth アプリの作成に関する情報が記載されています。 この情報は「カスタム OAuth アプリの作成」ページに掲載されています。

組み込み認証情報

CData は OAuth アプリケーションを作成し、サービスが許可している場合は OAuth 認証情報をドライバーに組み込んでいます。 これにより、カスタム OAuth アプリケーションを作成することなく、サービスに接続できます。

OAuth フロー中、エンドユーザーには Web ページ上に CData のブランディングが表示されます（権限同意ページやログイン試行後の成功/エラーページなど）。 組み込み OAuth アプリは、ドライバーで利用可能なすべての機能（読み取り、書き込みなど）に関するスコープについて同意を求めます。

エンドユーザー体験やリクエストするスコープをカスタマイズするには、カスタム OAuth アプリを作成する必要があります。 なお、一部のサービスではカスタム OAuth アプリケーションの作成が必須であり、その場合ドライバーには組み込み認証情報が含まれていません。

認可コードフロー：Web アプリケーションのパターン

認可コードフローでは、パブリック OAuth アプリケーションの登録を許可するサービスがあります。 この OAuth アプリケーションは、コネクタを組み込んでいるアプリケーションが作成します。 エンドユーザーをサービスへのログインにリダイレクトする際、OAuth アプリを登録した企業への権限付与が求められます。

このフロー用の OAuth アプリケーションを作成する際、コールバック URL の定義ルールはデータソースによって異なります。 複数のコールバック URL を定義できるサービスもあれば、HTTPS を必須とするサービスや、明示的なポート指定が必要なサービスもあります。

すべての OAuth プロバイダーに対してこのプロセスを汎用化する場合は、HTTPS とポートが明示的に定義された URL が必要であると想定するのがベストです。 Web アプリケーションでは、以下の2つのパターンのいずれかに従う必要があります：

  1. （非推奨） Web アプリケーションの各インスタンスに、コールバック URL がそのインスタンスを指す専用の OAuth アプリケーションが必要です。 この方法では、デプロイメントごと、顧客ごとに別々の OAuth アプリケーションが必要となるため、推奨されません。
  2. （推奨） 中間コールバック URL を定義し、そこから適切な Web アプリケーションにリダイレクトします。 これは CData が localhost コールバックを許可しない一部の組み込み OAuth アプリケーションで使用している方法です。

推奨されるプロセスでは、一般公開されているドメインの Web サイトにリダイレクト URI をホストします（例：CData は oauth.cdata.com を使用しています）。 OAuth アプリケーションにこの URI を設定し、実際のコールバック URL は GetOAuthAuthorizationURL ストアドプロシージャ呼び出しの State パラメータで指定します。

OAuth は、State パラメータで渡された値を認証完了後にそのまま返すように設計されています。 これにより、OAuth アプリケーションがリダイレクトした後、oauth.yourdomain.com のアプリケーションがその値を読み取って、適切なアプリケーション URL にユーザーをリダイレクトできます。


カスタムブランディング

カスタム OAuth アプリケーションを作成すると、カスタマイズされた同意ページを作成できます。 カスタムの文言やアイコンを含めることが可能です。 この機能は OAuth アプリ自体に含まれるもので、ドライバーの機能の範囲外です。

デスクトップアプリケーションでは、ドライバーにログイン成功時と失敗時のカスタム HTML ページを指定するための接続プロパティが用意されています：

プロパティ 説明
OEMAuthSuccess ログイン成功時に表示される HTML ファイルへのファイルパスです。
OEMAuthFailure ログイン失敗時に表示される HTML ファイルへのファイルパスです。

これらのプロパティはいずれも Other 接続プロパティを通じて指定します。 デフォルトでは、ドライバーが認可の成功または失敗を示すシンプルなページを表示します。

組み込み認証情報を使用している場合、CData ブランディングが表示されます。 カスタム OAuth アプリを使用している場合（OAuthClientId と OAuthClientSecret が指定されている場合）、CData ブランディングは削除され、汎用的な HTML ページが使用されます。

よりカスタマイズされた HTML ページが必要な場合は、OEMAuthSuccess と OEMAuthFailure オプションで指定できます。

まとめ

CData 組み込みコネクタでの OAuth 実装では、アプリケーションの種類、環境、ユーザーシナリオを慎重に検討する必要があります。 重要なポイントは、適切なグラントタイプの選択、InitiateOAuth プロパティの正しい設定、そして適切なトークンストレージメカニズムの選択です。

Web アプリケーションでは、GetOAuthAuthorizationURL と GetOAuthAccessToken ストアドプロシージャを使用して OAuth フローを管理してください。 デスクトップアプリケーションでは、InitiateOAuth=GETANDREFRESH を設定してコネクタにフローを自動的に処理させることができます。

ヘッドレスマシンやサービスアカウントのシナリオでは、ユーザー操作が不要な JWT Bearer またはクライアント資格情報フローの使用を検討してください。


CData コネクタを使ってみる

CData コネクタは、JDBC、ODBC、ADO.NET 環境全体で OAuth の実装をシンプルにします。 CData を活用したコネクティビティの組み込みについて詳しくはこちらをご覧いただくか、コネクティビティの専門家との打ち合わせで OAuth 連携のニーズをご相談ください。

In this article

Related articles