接続の確立

JDBC データソースの作成

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

ドライバーのJAR ファイルをクラスパスに追加します。JAR ファイルはインストールディレクトリの［lib］サブフォルダ内にあります。.lic ファイルはJAR ファイルと同じフォルダ内に配置される必要があることに注意してください。
ドライバークラスを入力します。次に例を示します。
```
cdata.jdbc.fhir.FHIRDriver
```
JDBC URL を入力します。次に例を示します。
```
jdbc:fhir:URL=http://test.fhir.org/r4b/;ConnectionType=Generic;ContentType=JSON;AuthScheme=None;

or

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

FHIR への接続

Url をFHIR サーバーのService Base URL に設定します。これは接続したいFHIR サーバーでリソースが定義されているアドレスです。

汎用、Azure ベース、AWS ベース、およびGoogle ベースのFHIR サーバー実装がサポートされます。

各実装についてのサンプルUrl は以下のとおりです。

汎用：http://my_fhir_server/r4b/
Azure：https://MY_AZURE_FHIR.azurehealthcareapis.com/
AWS：https://healthlake.REGION.amazonaws.com/datastore/DATASTORE_ID/r4/
Google：https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/

FHIR への認証

汎用FHIR インスタンス

本製品はFHIR のカスタムインスタンスへの接続をサポートします。

カスタムFHIR サーバーへの認証はOAuth で行います。

カスタムFHIR インスタンスに接続する前に、ConnectionType をGeneric に設定する必要があります。

OAuth

AuthScheme をOAuth に設定します。

OAuth では認証するユーザーにブラウザでFHIR との通信を要求します。次のセクションで説明するとおり、本製品はさまざまな方法でこれをサポートします。

次の手順に従う前に、サービスにOAuth アプリを登録してOAuthClientId およびOAuthClientSecret を取得する必要があります。

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

OAuth アクセストークンの取得およびリフレッシュ

次を設定して、接続してください。

InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
OAuthClientId：アプリの登録時に割り当てられたクライアントId に設定。
OAuthClientSecret：アプリの登録時に割り当てられたクライアントシークレットに設定。
CallbackURL：アプリの登録時に定義されたリダイレクトURL に設定。例：https://localhost:3333
OAuthAuthorizationURL：これは、ユーザーがサービスにログインして、アプリケーションにアクセス許可を与えるURL です。
OAuthAccessTokenURL：これは、アクセストークンがリクエストされるURL です。
OAuthRefreshTokenURL：古いトークンの期限が切れたときは、このURL でリフレッシュトークンを新しいアクセストークンと交換します。データソースによっては、アクセストークンと同じURL の場合がありますので、留意してください。

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

本製品はFHIR からアクセストークンを取得し、それを使ってデータをリクエストします。
OAuth 値はOAuthSettingsLocation で指定された場所に保存され、接続間で永続化されるようにします。

本製品はアクセストークンの期限が切れると自動的にリフレッシュします。

Web アプリケーション

Web アプリケーションから接続する場合、または本製品にブラウザウィンドウを開く権限がない場合は、提供されたストアドプロシージャを使用してOAuth トークン値を取得および管理します。

Note：ストアドプロシージャスキーマを拡張して、OAuth URL またはその他の接続文字列プロパティのデフォルトを設定できます。

OAuth フローの設定

Web フローで認証するOAuth URL を指定します。

OAuthAuthorizationURL：OAuth 2.0 に必要です。これは、ユーザーがサービスにログインして、アプリケーションにアクセス許可を与えるURL です。
OAuthAccessTokenURL：OAuth 2.0 に必要です。これは、アクセストークンがリクエストされるURL です。
OAuthRefreshTokenURL：OAuth 2.0 に必要です。OAuth 2.0 では、古いトークンの期限が切れたときは、このURL でリフレッシュトークンを新しいアクセストークンと交換します。データソースによっては、アクセストークンと同じURL である場合がありますので、注意してください。

アクセストークンの取得

OAuth URL に加えて、次の追加の接続プロパティを設定し、OAuthAccessToken を取得します。

OAuthClientId：アプリケーション設定のクライアントId に設定。これはコンシューマーキーとも呼ばれます。
OAuthClientSecret：アプリケーション設定のクライアントシークレットに設定。これはコンシューマーシークレットとも呼ばれます。
OAuthVersion：OAuth バージョン2.0 に設定。

続いてストアドプロシージャを呼び出し、OAuth 交換を完了します。

GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。CallbackURL インプットをアプリ設定で指定したリダイレクトURI に設定します。ストアドプロシージャがOAuth エンドポイントのURL を返します。
ログインして、アプリケーションを認可します。コールバックURL にリダイレクトされます。
GetOAuthAccessToken ストアドプロシージャを呼び出します。AuthMode インプットをWEB に設定します。
OAuth 2.0 では、Verifier インプットを、コールバックURL のクエリ文字列のcode パラメータに設定します。

データに接続してトークンをリフレッシュ

GetOAuthAccessToken によって返されたOAuthAccessToken の有効期限は限られています。トークンを自動的にリフレッシュするには、最初のデータ接続で次のように設定します。あるいは、RefreshOAuthAccessToken ストアドプロシージャを使って、手動でトークンをリフレッシュします。

OAuth エンドポイント

OAuthAuthorizationURL
OAuthAccessTokenURL
OAuthRefreshTokenURL

OAuth トークンおよびキー

OAuthClientId
OAuthClientSecret
OAuthRefreshToken
OAuthAccessToken

OAuth 認証の開始

OAuthVersion：2.0 に設定。
InitiateOAuth：REFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
OAuthSettingsLocation：本製品がOAuth 値を保存する場所に設定し、接続間で維持されるようにします。

その後のデータ接続では、以下を設定します。

InitiateOAuth
OAuthSettingsLocation
OAuthRequestTokenURL
OAuthAuthorizationURL
OAuthAccessTokenURL
OAuthRefreshTokenURL

ヘッドレスマシン

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

以下のオプションから選択します。
- オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
- オプション2：インターネットブラウザに対応したマシンに本製品をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品を設定します。

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

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

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

以下のオプションから選択します。
- 以下のプロパティを設定し、認証URL を作成します。
  - InitiateOAuth：OFF に設定。
  - OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
  - OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
ログインして、本製品にアクセス許可を与えます。すると、verifier code を含むリダイレクトURL にリダイレクトされます。
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 FHIR インスタンス

本製品はMicrosoft Azure がホストするFHIR インスタンスへの接続をサポートします。

Azure Active Directory、Azure サービスプリンシパル、およびAzure MSI を利用して認証できます。

Azure がホストするFHIR インスタンスに接続する前に、ConnectionType をAzure に設定する必要があります。

Azure Active Directory

Azure Active Directory に登録されたOAuth アプリを使用して、Azure がホストするFHIR インスタンスに接続できます。

AuthScheme をAzureAD に設定します。

埋め込みアプリ

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。埋め込みOAuth アプリを使用して認証する場合、ほかの接続プロパティは設定せずに接続します。

カスタムアプリ

代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成を参照してください。

OAuth アプリが作成できたら、以下を設定して接続します。

OAuthClientId：OAuth アプリの概要ページにある、アプリケーション（クライアント）ID に設定。
OAuthClientSecret：OAuth アプリの証明書とシークレットページで生成されたクライアントシークレットの値に設定。
AzureTenant（シングルテナントアプリのみ）：OAuth アプリの概要ページにある、ディレクトリ（テナント）ID に設定。
CallbackURL：カスタムOAuth アプリの作成時にリダイレクトURI に指定した値に設定。

Azure MSI

Azure VM 上でFHIR を実行している場合は、AuthScheme をAzureMSI に設定し、Managed Service Identity（MSI）の資格情報を利用して認証します。

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

Azure サービスプリンシパル

Azure サービスプリンシパルを使用して、Azure がホストするFHIR インスタンスを認証できます。

カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリの作成を参照してください。

OAuth アプリが作成できたら、以下を設定して接続します。

AuthScheme：AzureServicePrincipal に設定。
OAuthClientId：Azure 上のFHIR への認証に使用するOAuth アプリの概要ページにある、アプリケーション（クライアント）ID に設定。
OAuthClientSecret：認証するOAuth アプリの証明書とシークレットページで生成されたクライアントシークレットの値に設定。
CallbackURL：カスタムOAuth アプリの作成時にリダイレクトURI に指定した値に設定。
OAuthJWTCert：サービスプリンシパルの証明書のパスに設定。
OAuthJWTCertType：サービスプリンシパルの証明書のタイプに設定。

AWS FHIR インスタンス

本製品はAWS がホストするFHIR インスタンスへの接続をサポートします。

AWS ルートキー、AWS EC2 ロール、およびAWS IAM ロールで認証できます。

AWS がホストするFHIR インスタンスに接続する前に、ConnectionType をAWS に設定する必要があります。

AWS ルートキー

AWS のルートユーザーのアクセスキーを使って認証することができます。以下を設定します。

AuthScheme：AwsRootKeys に設定。
AWSAccessKey：AWS アカウントのアクセスキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。
AWSSecretKey：AWS アカウントのシークレットキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。

AWS IAM ロール

IAM ロールを使用してAWS がホストするFHIR に認証するには、以下を設定します。

AuthScheme：AwsIAMRoles に設定。
AWSAccessKey：AWS アカウントのアクセスキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。
AWSSecretKey：AWS アカウントのシークレットキーに設定。この値には、［AWS セキュリティ認証情報］ページからアクセスできます。
AWSRoleARN：認証時に使用したいロールのAmazon リソースネームに設定。

AWS EC2 ロール

EC2 インスタンスから本製品を使用していて、そのインスタンスにIAM ロールが割り当てられている場合は、認証にIAM ロールを使用できます。

AuthScheme をAwsEC2Roles に設定します。

認証にIAM ロールも使用している場合は、さらにAWSRoleARN を認証したいロールのRole ARN に指定する必要があります。これにより、本製品は指定されたロールの資格情報を取得しようと試みます。

Google FHIR インスタンス

本製品はGoogle Cloud Platform がホストするFHIR インスタンスへの接続をサポートします。

標準的なOAuth またはサービスアカウント認証（JWT を使用）で認証できます。

Google Cloud Platform がホストするFHIR インスタンスに接続する前に、ConnectionType をGoogle に設定する必要があります。

OAuth

AuthScheme をOAuth に設定。

埋め込みアプリ

カスタムアプリ

Generic の接続タイプとは異なり、ConnectionType をGoogle に設定した場合、OAuthAuthorizationURL、OAuthRefreshTokenURL、およびOAuthAccessTokenURL は設定する必要がありません。

Google Cloud Platform がホストするFHIR インスタンスに接続する場合、これらのプロパティは本製品にデフォルト値が埋め込まれているためです。

これらのプロパティを省略する以外は、FHIR の汎用の実装と同じ手順でOAuth 認証を設定します（上記の「汎用FHIR インスタンス」セクションの「OAuth」セクションを参照してください）。

サービスアカウント（OAuth JWT）

サービスアカウントを使用して認証するには、新しいサービスアカウントを作成し、アカウント証明書のコピーを用意する必要があります。

Google JSON 証明書

JSON ファイルを証明書として使用したい場合は、以下のプロパティを設定する必要があります。

AuthScheme：OAuthJWT に設定。
InitiateOAuth：GETANDREFRESH に設定。
OAuthJWTCertType：GOOGLEJSON に設定。
OAuthJWTCert：Google が提供する.json ファイルへのパスに設定。
OAuthJWTSubject（オプション）：この値は、サービスアカウントがGSuite ドメインの一部で、委任を有効にする場合にのみ設定します。このプロパティの値は、データにアクセスしたいユーザーのE メールアドレスでなければなりません。

PFX ファイル証明書

PFX ファイルを証明書として使用したい場合は、代わりに以下のプロパティを設定する必要があります。

AuthScheme：OAuthJWT に設定。
InitiateOAuth：GETANDREFRESH に設定。
OAuthJWTCertType：PFXFILE に設定。
OAuthJWTCert：Google が提供する.pfx ファイルへのパスに設定。
OAuthJWTCertPassword（オプション）：.pfx ファイルのパスワードに設定。Google はPFX 証明書を暗号化するため、ほとんどの場合、これを設定する必要があります。
OAuthJWTCertSubject（オプション）：複数の証明書を格納するOAuthJWTCertType を使用している場合にのみ設定します。Google によって生成されたPFX 証明書には設定しないでください。
OAuthJWTIssuer：サービスアカウントのE メールアドレスに設定。このアドレスには、通常iam.gserviceaccount.com ドメインが含まれます。
OAuthJWTSubject（オプション）：この値は、サービスアカウントがGSuite ドメインの一部で、委任を有効にする場合にのみ設定します。このプロパティの値は、データにアクセスしたいユーザーのE メールアドレスでなければなりません。