ユーザーコンテキスト付きサービスに対する認証の概要

認証には、認証情報と権限が含まれています。サービスの認証情報は JWT 内に指定されており、これらの JWT からの情報がログに記録されます。

認証情報

サービスによって API 呼び出しが行われると、サービスによってクライアント ID およびシークレットが Guidewire Hub に送信されます。Guidewire Hub でクライアントシークレットが正しいことを確認して、サービスを認証します。これは、スタンドアロン型サービス、ユーザーコンテキスト付きサービス、およびサービスアカウントマッピング付きサービスの場合に当てはまります。

サービスがユーザーコンテキストを用いて認証される場合、ユーザーに関する情報が提供されます。ただし、ユーザーレベルの認証はありません。認証は、サービスレベルでのみ行われます。

Guidewire Hub でのクライアント ID およびシークレットの登録方法の詳細については、Guidewire Hub への呼び出し元アプリケーションの登録を参照してください。

承認

ユーザーコンテキスト付きサービスに対するエンドポイントアクセス権

エンドポイントのアクセス権では、呼び出し元で使用できるエンドポイントの動作のさまざまな側面を定義します。これには、以下が含まれます。

  • 呼び出し元が使用できるエンドポイントとリソースの種類。
  • 呼び出し元が使用可能なエンドポイントで呼び出せる操作。
  • 呼び出し元が要求ペイロードで指定できたり応答ペイロードで取得できるフィールド。

エンドポイントアクセス権は API 役割によって制御されます。API 役割は、エンドポイント、操作、およびフィールドのリストであり、API 呼び出しで一連の呼び出し元が使用できます。API 役割は、許可リストとして機能します。デフォルトでは、呼び出し元はエンドポイントのアクセス権を持っていません。呼び出し元が 1 つ以上の API 役割と関連付けられている場合、それらの API 役割それぞれの許可リストに含まれているエンドポイント、操作、およびフィールドへのアクセス権を取得します。

service-with-user-context 呼び出しでは、システム API によって、以下の 2 つのセットの API 役割が確認されます。

  • サービスに割り当てられている API 役割
  • ユーザーに割り当てられている API 役割

呼び出しに付与されるエンドポイントアクセス権は、これらの 2 つのセットによって付与されるエンドポイントアクセス権の共通する部分です。つまり、エンドポイント、操作、またはフィールドにアクセスするために、アクセス権に付与される必要がある API 役割は、サービスに割り当てられている API 役割が 1 つ以上と、ユーザーアカウントに割り当てられている API 役割が 1 つ以上です。

例えば、ACME External Document Manager サービスには以下の API 役割があり、以下のエンドポイントアクセス権を持つとします。

  • acme_externaldocumentmanager
    • GET /documents
    • POST /documents

そして、Ray Newton さんが以下の API 役割と以下のエンドポイントアクセス権を持っているとします。

  • Insured
    • GET /documents
    • GET /coverages

ACME External Document Manager サービスが、Ray Newton さんのユーザーアカウントを使用してユーザーアカウント付きサービスとして呼び出しを行うとします。このエンドポイントは、そのサービスとそのユーザーの両方に付与されているため、この呼び出しは、GET /documents へのアクセス権を持ちます。これらのエンドポイントのどちらも、サービスとユーザーの両方に付与されていないため、呼び出しは、POST /documents と GET /coverages のいずれに対してもアクセス権を持ちません。

API 役割のコンフィギュレーション方法の詳細については、エンドポイントアクセス権を参照してください。

ユーザーコンテキスト付きサービスに対するリソースアクセス権

リソースのアクセス権では、特定の種類のリソースに対して呼び出し元がアクセスできるインスタンスを定義します。例えば、保険契約者、引受担当者、担当者、およびサービス業者が使用できる GET /claims エンドポイントがあるとします。これらの呼び出し元はすべて、種類がクレームのリソースにアクセスするエンドポイントを使用できますが、呼び出し元のいずれもすべてのクレームにアクセスできません。次に例を示します。

  • 保険契約者は、保持する保険契約と関連するクレームのみを表示できます。
  • 引受担当者は、割り当てられた保険契約のクレームのみを表示できます。
  • 担当者は、割り当てられたクレームのみを表示できます。
  • サービス業者は、サービス要求が割り当てられたクレームのみを表示できます。

リソースアクセス戦略は一連のロジックであり、呼び出し元がアクセスできるリソースを特定します。ベースコンフィギュレーションには、ユーザーおよびサービスのリソースアクセス戦略が含まれています。

  • ユーザーのリソースアクセス戦略は通常、呼び出し元をユーザー所有オブジェクトのみに制限します。例えば、アカウント名義人は、アカウント所有（直接的または間接的に所有）オブジェクトを表示できます。
  • 一般的に、どのような方法でも、サービスのリソースアクセス戦略によって、呼び出し元が制限されません。

エンドポイントアクセス権と同様に、service-with-user-context 呼び出しのリソースアクセス権は、サービスのリソースアクセス権とユーザーのリソースアクセス権の共通部分です。ベースコンフィギュレーションでは、サービスはすべてのリソースへのアクセス権を付与されます。したがって、service-with-user-context 呼び出しのリソースアクセス権は、論理的にはユーザーのリソースアクセス権と同等です。

例えば、ACME External Document Manager サービスが、以下のドキュメントへのアクセス権を持っているとします。

  • （すべてのドキュメント）

そして、Ray Newton さんは、以下のドキュメントへのアクセス権を持っているとします。

  • 保険契約 55-123456 に関連するドキュメント
    • ドキュメント xc:127
    • ドキュメント xc:356
  • アカウント C000324667 に直接関係するドキュメント
    • ドキュメント xc:888

ACME External Document Manager サービスが Ray Newton さんのために service-with-user-account 呼び出しを行う場合、ドキュメント xc:127、xc:356、および xc:888 へのアクセス権が呼び出しに付与されます。これらのリソースはサービスとユーザーの両方からアクセスできるからです。この呼び出しに、他のドキュメントに対するアクセス権はありません。サービスとユーザーの両方がアクセス権を持つドキュメントが他にないからです。

リソースアクセスの動作方法の詳細については、リソースアクセス権を参照してください。

ユーザーコンテキスト付きサービスに対するプロキシユーザーアクセス権

すべての Cloud API 呼び出しは、セッションのコンテキスト内で行われます。ClaimCenter データベース内にリストされているユーザーを、このセッションにアタッチする必要があります。 ClaimCenter は、この「セッションユーザー」をさまざまな方法で使用できます。

  • 呼び出しによってオブジェクトが作成または変更される場合、セッションユーザーがそのオブジェクトの CreateUser または UpdateUser として記録されます。
  • 呼び出しによって権限制限チェックがトリガされる場合、セッションユーザーの権限制限が確認されます。
  • 特定のドメインレベルのシステム権限（アクティビティを所有する権限など）を呼び出し元が持っているかどうかのチェックを行う必要があるロジックが、呼び出しでトリガされることはほとんどありません。しかし、トリガされた場合、セッションユーザーのシステム権限が確認されます。

サービスによってユーザーコンテキスト付き呼び出しが行われる場合、関連ユーザーが内部ユーザーであることがあります。内部ユーザーは、ClaimCenter 運用データベースにユーザーとしてリストされている個人です。この場合、その内部ユーザーは、セッションユーザーとして使用されます。

サービスによってユーザーコンテキスト付き呼び出しが行われる場合、関連ユーザーが外部ユーザーであることがあります。外部ユーザーは、保険会社にとって既知である個人ですが、ClaimCenter 運用データベース内にユーザーとしてリストされていない個人です。例えば、保険契約者、業者、またはアカウント名義人の場合があります。ユーザーコンテキストが外部ユーザーを指定している場合、プロキシユーザーをセッションに割り当てる必要があります。

「プロキシユーザー」はセッションに割り当てられる内部ユーザーですが、外部ユーザーやサービスによって行われた API 呼び出しに対して割り当てられます。プロキシユーザーは、RestAuthenticationSourceCreatorPlugin プラグインによって割り当てられます。このプラグインによって、4 人のプロキシユーザーが指定されます。そのうちの 1 人のプロキシ外部ユーザーを呼び出しで使用する際、外部ユーザーによる呼び出しか、ユーザーのコンテキストで外部ユーザーを指定するユーザーコンテキスト付きサービスによる呼び出しで使用します。

プロキシユーザーに関する詳細については、プロキシユーザーアクセスを参照してください。

ユーザーコンテキスト付きサービスの JWT

JSON Web Tokens（JWT）には、トークンクレームが含まれています（標準 JWT 用語では、これらは単に「クレーム」と呼ばれます。損害保険におけるクレームとの混同を避けるため、このドキュメントでは、JWT クレームを「トークンクレーム」と呼びます）。トークンクレームは、ベアラーの名前などトークンのベアラーに関してアサートされた情報です。ベアラートークン認証の場合、認証情報はトークンクレームに保存されます。

サービスによってユーザーコンテキスト付きで呼び出しが行われる場合、Cloud API 認証に固有の情報は JWT 内の一部のみです。以下のトークンクレームは JWT にあり、service-for-user-context 呼び出しに対するもので、Cloud API 認証に関係します。

"sub": "<clientId>",
"cid": "<clientId>", 
"scp": [
  "cc.service",
  "scp.cc.<serviceAPIRole>",
  "cc.allowusercontext"
]
  • sub は、トークンのサブジェクトです。これは、サービスのクライアント ID に設定されます。
  • cid はサービスのクライアント ID です。これも、サービスのクライアント ID に設定されます。
  • scp トークンクレームには、少なくとも以下のエントリがあります。
    • cc.service 値：呼び出し元がサービスであることを指定します。
    • 1 つ以上の API 役割のリスト：API 役割はサービスに関連付けられています。これらの役割には scp.cc. の接頭辞が付いています。
    • cc.allowusercontext 値：呼び出しではヘッダーに追加のユーザーコンテキストを指定できます。（ヘッダーに GW-User-Context ヘッダーが含まれている場合、これは、スタンドアロン型サービスではなく service-with-user-context 呼び出しとして扱われます）。

cc.allowusercontext 値は、呼び出しでユーザーコンテキストも提示していることを示します。ユーザーに関する情報は、GW-User-Context ヘッダー内に指定されます。内部ユーザーの場合、ユーザー名、リソースアクセス戦略、およびリソースアクセス ID を、ヘッダーで指定する必要があります。外部ユーザーの場合、ユーザー名、ユーザーの役割、リソースアクセス戦略、およびリソースアクセス ID を、ヘッダーで指定する必要があります。ヘッダーは、Base64 でエンコードされている必要があります。

ヘッダーは、次の段落で説明する形式の JSON ペイロードである必要があります。

内部ユーザーの場合、GW-User-Context ヘッダーの構文は以下のとおりです。

{
  "sub": "<userName>",
  "cc_username" : "<userName>"
}

次の点に注目します。

  • ユーザー名は sub トークンクレーム内に指定されています。
  • リソースアクセス戦略は、cc_username トークンクレームの存在によって指定されています。
  • リソースアクセス ID は、ユーザーの名前であり、cc_username トークンクレーム内で指定されています。

保険契約者である外部ユーザーの場合、GW-User-Context ヘッダーの構文は以下のとおりです。

{
  "sub": "<userName>",
  "groups": [
    "<userAPIroleList>"
  ],
  "cc_policyNumbers" : [
    "<policyNumbers>"
  ]
}

次の点に注目します。

  • ユーザー名は sub トークンクレーム内に指定されています（これはログのために使用されますが、それ以外の機能的影響はありません）。
  • ユーザーの API 役割は、groups トークンクレームにリストされています。すべての役割名に gwa.<planet_class>.cc. の接頭辞を付ける必要があります。
  • リソースアクセス戦略は、cc_policyNumbers トークンクレームの存在によって指定されています。
  • リソースアクセス ID は、保険証券番号のリストであり、cc_policyNumbers トークンクレーム内で指定されています。

サービス提供者（業者とも呼ぶ）である外部ユーザーの場合、GW-User-Context ヘッダーの構文は以下のとおりです。

{
  "sub": "<userName>",
  "groups": [
    "<userAPIroleList>"
  ],
  "cc_gwabuid" : "<addressBookUniqueIdentifier>"
}

次の点に注目します。

  • ユーザー名は sub トークンクレーム内に指定されています（これはログのために使用されますが、それ以外の機能的影響はありません）。
  • ユーザーの API 役割は、groups トークンクレームにリストされています。すべての役割名に gwa.<planet_class>.cc. の接頭辞を付ける必要があります。
  • リソースアクセス戦略は、cc_gwabuid トークンクレームの存在によって指定されています。
  • リソースアクセス ID は、Guidewire アドレス帳で一意の識別子であり、cc_gwabuid トークンクレーム内で指定されています。
注: cc.allowusercontext トークンクレーム付きの JWT が呼び出しに含まれている場合、要求オブジェクトのヘッダーにユーザーコンテキストヘッダーが含まれていないと、Cloud API では呼び出しを、スタンドアロン型サービスからのものであるかのように扱います。つまり、サービスに提供されるアクセス権のみに呼び出しは制限されます。ユーザーベースの制限は適用されません。ユーザーを指定するユーザーコンテキストヘッダーがないからです。

ログ

呼び出しごとに、呼び出し元に関する情報がログに記録されます。以下の表に記載されているフィールドの情報は、ログに記録された値の取得元と呼び出し元に関する情報です。

フィールド 値
sub JWT からの sub トークンクレームの値
clientId JWT からの cid トークンクレームの値
user

ユーザーコンテキストのユーザーが内部ユーザーである場合、内部ユーザーのユーザー名。

ユーザーコンテキストのユーザーが外部ユーザーである場合、ユーザーコンテキストの sub 値。