Viedoc Web API

  • Published by Viedoc System 2023-03-27
  • Print

はじめに

Viedoc Security Token Service (STS)は、Viedoc eClinical suite の API で使用するアクセストークンの発行と検証を一元的に行うサービスである。つまり、Viedoc STS はいわゆるプリンシパル（またはセキュリティ・プリンシパル）に対して認証サービスを提供するアイデンティティ・プロバイダ（IdP）です。プリンシパルは、コンピュータ、サービス、プロセスやスレッドなどの計算エンティティ、あるいはそのようなもののグループです。

Viedoc STSは、Viedoc REST APIとは別物である。

注意! Viedoc STSはViedoc WCF APIには使用されません。

Viedoc STSは、トークンの取得と検証のためのエンドポイントを持つWebサービスから構成されています。また、Viedoc STSはメタデータを（JSON文書として）公開します。このメタデータは、クライアントやAPIがサービスと通信する際に自己設定するために利用されます。

Viedoc STSは、Webアプリケーションやモバイルアプリケーションの認証・認可のための業界標準であるOAuth 2.0規格に準拠しています。詳しくは、The OAuth 2.0 Authorization Frameworkをご覧ください。

Viedoc STSは一般に公開されています。

Viedoc REST APIにおける認証

Viedoc REST APIは、リクエストごとに認証と認可を必要とします。これを実現するためには、アクセストークンをHTTP認証ヘッダーとしてリクエストに含める必要があります。このトークンは、Bearer認証HTTPスキームで提供されなければなりません。

Viedoc REST APIは、Viedoc STSが発行したトークンのみを受け付けます。

Viedoc STSからのトークンの受信

Grant types付与の種類

Viedoc STSはClient Credentialsという非インタラクティブなグラントタイプを使用します。この認可タイプは使いやすく、特にユーザーIDが存在しないシナリオのために作られている。言い換えれば、この認可タイプでは、マシン間通信のためのトークンを取得することができます。

クレデンシャル認証情報

Viedoc STSへのトークン発行リクエストでは、HTTP POSTリクエストのフォームデータとして、一連のクレデンシャル、つまりキーと値を提供する必要があります。以下は、そのようなクレデンシャルの例です。

Key Value Description
client_id viedoc-web トークンを発行するクライアントID。
client_secret viedoc-secret 指定されたクライアントIDのクライアントシークレット（＝パスワード）。
grant_type client_credentials 認証の種類。

注意! Web APIクライアントに関する情報（クライアントID、クライアントシークレットの取得方法）については、APIの設定を参照してください。

アプローチ1：プレーンなHTTPクライアント

アクセストークンを取得するには、http://<base-url>/connect/tokenにあるViedoc STSの「トークンエンドポイント」にPOSTリクエストを行い、POSTリクエストボディの上にキーと値（詳細はクレデンシャル情報を参照）を記述してください。

アプローチ2: Identity Modelライブラリ

.NET Frameworkまたは.NET CoreでIdentity Modelを使用する場合、HttpClientの拡張メソッドを使用することができます。次の例は、Client Credentialsグラントタイプを扱うのに適した方法を示しています。

var client = new HttpClient();

var response = await client.RequestClientCredentialsTokenAsync(new ClientCredentialsTokenRequest
{
   Address = "http://<base-url>/connect/token",
   ClientId = "viedoc-web",
   ClientSecret = "viedoc-secret",
   Scope = "<scope names that you want to access>",
   Parameters =
   {
      { "meta", "study_guid:<guid>;user_guid:<guid>;license_feature:<feature_name>" }
   }
});

上記のコードを実行すると、エラーまたは成功した場合に Viedoc API へのリクエストで使用するアクセストークンを含む強い型付けされたレスポンスが生成されます。

詳細については、.NET 統合ライブラリ IdentityModel のドキュメントを参照してください。

トークンの検証

トークン改竄されていないことをアプリケーションが信頼できるようにするには、いくつかのパラメータでトークンを検証する必要があります。主な検証項目は以下のとおりです。

  • オーディエンスクレーム
  • スコープの主張
  • 発行者の主張
  • 暗号化された署名

トークンの検証は、次の2つの方法のいずれかで行うことができます。

  • オフライン - 受信側のアプリケーション/APIが行う。この方法は、パフォーマンス上の理由から強く推奨されます。
  • オンライン - トークンをSTSに返送して検証する方法（いわゆるイントロスペクション）。この方法は、他の選択肢がない場合にのみ使用する必要があります。

検証は、便利なライブラリを使用することで自動的に行うことができる。以下の.NETとJavaScriptの例を参照してください。

.NET の IdentityModel を使用したオフライン検証

ASP.NET Core をベースに Web API を構築する場合、リクエストパイプラインの拡張によりトークン検証を行うことができます。リクエスト パイプラインは、ASP.NET Core に組み込まれている認証システム、つまり「プリンシパル」と自動的に連動します。Startup.cs ファイルでパイプラインを設定するとき、次の例のように JWT Bearer 認証を追加することができます。

この例の最初のステップでは、NuGet パッケージ Microsoft.AspNetCore.Authentication.JwtBearerを追加しています。

public void ConfigureServices(IServiceCollection services)
{
   services.AddAuthentication("Bearer")
      .AddJwtBearer("Bearer", options =>
      {
         options.Authority = "http://<base-url>";
         options.TokenValidationParameters = new TokenValidationParameters
         {
            ValidateAudience = true
            //More validation options here
         };
      });

   services.AddAuthorization(options =>
   {
      //Adding a policy to validate the scope claim of the incoming token
      options.AddPolicy("ApiScope", policy =>
      {
         policy.RequireAuthenticatedUser();
         policy.RequireClaim("scope", "<your required scope name here>");
      });
   });
}

public void Configure(IApplicationBuilder app)
{
   app.UseAuthentication();
   app.UseAuthorization();
}

詳しくは、Overview of ASP.NET Core Authentication | Microsoft Docsをご覧ください。

JavaScriptによるオフライン検証

oidc-clientJavaScript ライブラリを使用すると、以下のことが可能です。

  • STSからのメタデータのダウンロード
  • トークンの検証
  • クレームの抽出

このライブラリは NPM packageとして提供されており、主に JavaScript クライアントで使用することを目的としています。詳細については、oidc-client のドキュメントを参照してください。

ウェブ検証

Web サイト https://jwt.io では、トークンを検証することができます。トークンを Encoded フィールドに貼り付けるだけで、Decoded フィールドにトークンに関する情報が表示されます。

STSによるオンライン検証(introspection)

トークンをSTSに送信して検証するのは、何らかの理由でオフラインでの検証が不可能な場合の最後の手段と考えてください。

詳細については、 Introspection Endpointを参照してください。

Viedoc Web API ドキュメント

Viedoc Web APIは、Viedoc API swaggerページで文書化されています。Viedoc.APIのswaggerページには、以下の場所でアクセスできます。
<API URL>/swagger、ここでAPI URLは環境に依存します。たとえば、次のリンクを参照してください。
https://v4apitraining.viedoc.net/swagger/
お使いの環境のAPI URLにアクセスする方法の詳細について、以下の説明をご覧ください。
Viedoc Web APIのswaggerページを表示するには、Viedoc AdminでAPI URLが必要です。
注意! API設定フィールドを表示するには、API Managerユーザー・ロールを持つ必要があります。
API URL in Viedoc Adminでを表示する方法。

1 Viedocのランディングページで、以下を選択します。アドミン アイコンをクリックすると、Viedoc Adminが開きます。
2

作業したいスタディーを開き、API設定欄の編集ボタンを選択すると、API設定ダイアログが開きます。
3

Web APIクライアントタブで、アクセスしたいAPIクライアントの変更ボタンをクリックします。
4

Web API クライアントを編集ダイアログが開きます。

上記の例を参考に、API URL: https://v4apitraining.viedoc.net/swaggerに /swagger を追加すると、swagger ページが表示されます。

Viedoc Web API バージョン

Viedoc Web APIのswaggerページには、メソッド、パラメータ、応答メッセージなど、Viedoc Web APIを使用してViedocに接続し、対話する方法についての情報が含まれています。

破壊的変更とみなされるViedoc Web APIの更新は、常に新しいAPIバージョンで導入されます。後方互換性を維持するために、使用する API バージョンを指定する必要があります。

重要! APIバージョンが api-versionクエリまたはAccept-Versionヘッダのいずれかで指定されていない場合、エンドポイントに利用可能な最新のバージョンが使用されることになります。また、エンドポイントによって異なるバージョンも利用可能です。

api-versionクエリフィールドまたはAccept-Versionヘッダーフィールドで、Viedocへの接続と対話に使用するAPIバージョンを指定できます。

APIバージョンを指定するには、dataexport/startエンドポイントについて以下の例に示すように、必要なバージョンの日付を api-version クエリフィールドまたはAccept-Versionヘッダーフィールドに入力してください。

利用可能なバージョン
Viedoc Web API バージョン
前バージョンからの変更点: N/A- 初期バージョン。		 2022-01-01

その他の情報