署名付き値

SDKは署名付きの値を返すAPIを提供しています。

危険

値をサーバーへ送信する際は、必ず署名付きの値を取得するAPIを利用しサーバー側でその検証を行ってください。署名付きでない値を利用した場合や検証を行わなかった場合は、値を偽造される可能性があります。

署名付き値の利用フロー

(1) リソースの取得

SDKのreadResourceWithSignatureやgetSubscriptionIdWithSignatureなど署名付きの値を取得できるWithSignatureのついているAPIを利用して値を取得します。値はJWT形式で保存されています。どのようなclaimが含まれているかは得られるJWTのClaimを参照してください。

(2) リソースのサーバーへの送信

得られた値をサーバーに送信します。

(3) 公開鍵の取得

ポケットサインサーバーから公開鍵を取得します。以下のエンドポイントで取得できます。

環境名	エンドポイント
モック環境	https://api.core.mock.p8n.app/jwks
本番環境	https://api.core.p8n.app/jwks

これらのエンドポイントは、RFC7517のJWK Set Formatで返します。

(4) 署名の検証

取得した公開鍵を用いてミニアプリから送信された値の検証をします。

危険

必ず audクレームの検証もしてください。この検証を怠ると、別のサービスに対して発行された値を受け入れてしまい、値が偽装される可能性があります。具体的には、ユーザーが異なるユーザーに成りすませてしまう可能性があります。

危険

ユーザーリソースの場合は、必ずペイロードのresourceIdキーの値が意図したものであることも検証してください。この検証を怠ると、悪意のあるユーザーによって異なるリソースに紐づく値を渡され、値が偽装される可能性があります。

得られるJWTのClaim

それぞれの関数で得られるJWTは、通常のJWTのclaimに加えて以下のclaimを含みます。

`getSubscriptionIdWithSignature`

subscription_id: Subscription IDを示す文字列

`readResourceWithSignature`

resource_id: そのリソースIDを示す文字列
value: そのリソースの値を文字列化したもの
updated_at: ISO 8601形式 (小数点以下6桁まで含むことあり) の更新日時を示す文字列

`readResourcesWithSignature`

values: 以下のResourcesJWTValue型の配列

type ResourcesJWTValue = {
  /** リソースID */
  resource_id: string
  /** リソースの値 */
  value: string | null
  /** ISO 8601形式 (小数点以下6桁まで含むことあり) の更新日時を示す */
  updated_at: string | null
}

値が存在しない場合は、valueとupdated_atが共にnullになります。

warnings: 以下のResourcesJWTWarning型の配列

type ResourcesJWTWarning = {
  /** リソースID */
  resource_id: string
  /**
   * 値が取得できなかった理由の種類
   */
  warning: string
}

warningはGetUserResourcesResponse.Warningのいずれかの文字列

署名付き値の利用フロー​

(1) リソースの取得​

(2) リソースのサーバーへの送信​

(3) 公開鍵の取得​

(4) 署名の検証​

得られるJWTのClaim​

getSubscriptionIdWithSignature​

readResourceWithSignature​

readResourcesWithSignature​