テスト環境で製品の PV サービスを設定する

テスト環境で製品に KWS Parent Verification サービスを設定する方法を説明します。

テスト環境を設定するには、以下のように WS 内で 製品 を作成し、PV サービスにリンクします。

製品の設定

  1. KWS Developer Portal の [Dashboard (ダッシュボード)] タブで、右上の [Add product (製品の追加)] ボタンをクリックします。

    2.[Product name (製品名)] を入力して [Add product (製品の追加)] をクリックします。

    これで、テスト環境に製品が追加されました。製品の詳細情報を入力するよう指示されます。 3.基本情報 を入力し、サービス利用規約に同意します。

    • [Product name (製品名)]

    • Product URLs - KWS が保護者に送信する確認要求の電子メールには、次の URL へのリンクが含まれています。

      • プライバシー ポリシー - 組織のプライバシーポリシーの URL。

      • カスタマー サポート / FAQ - 組織のサポート / FAQ の URL。

サービスの設定

サービス利用規約に同意すると、サービスの詳細を編集できるようになります。詳細情報は、リダイレクト URL と webhook 設定で構成されています。

リダイレクト URL の設定

[RedirectURL] を入力します。検証の成功 / 最終的な失敗について、KWS が親にリダイレクトする URL です。リダイレクト URL は以下のような形式になっています。

https://your.domain.com/your/path?status=...&externalPayload=...

この場合、

  • externalPayload is the optional external payload passed into the initiate call.

  • status is a URL encoded JSON object representing the status returned from verification:

    {
    verified: boolean,
    transactionId: string,
    errorCode: string | null,
    }

注記:リダイレクト URL 内の情報は署名されておらず、ユーザーによって変更可能です。この情報は、表示のためだけに用いられており、検証結果を判断するためのものではありません。結果の判断には webhook を使用してください。

URL が設定されていない場合、KWS はウィジェット内に成否のページを表示します。

webhook の設定

KWS は webhook コールを通じてあなたのシステムにイベントを通知します。Webhook は以下の手順で設定します。

  1. [Parent Verification Service] ビューで、[Successful verification webhook address (検証成功の webhook アドレス)] を入力します。これは、KWS が検証に成功したことを示す webhook を送信するアドレスです。

    重要:webhook の URL には、攻撃者が不正操作しやすい情報を含めないでください (簡単に反復処理できるような数字 ID など)。URL はあえてシグネチャ アルゴリズムに含めていません。URL リクエストが変更された際に、reverse-proxies / load-balancers などの背後にあるサービス内でシグネチャ検証を容易にするためです。

    2.Webhook 構成で使用する以下の値をコピーします。

    • [Webhook secret code (Webhook シークレット コード)] - KWS からの正式なコールであることを確認するためにペイロードの署名に使用される webhook 秘密鍵。

    • [Service API host URL (Service API ホスト URL)]

    • [Service widget URL (サービス ウィジェット URL)]

POST ボディ構造体

すべての webhook コールは、イベント固有のペイロードを折り返す共通の構造体を持つ HTTPS POST です。

POST https://www.yourdomain.com/your-webhook-endpoint
x-kws-signature: t=1621535329,v1=f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
Body
{
  "name": "webhook-name",
  "time":"ISO8601 timestamp",
  "orgId": "uuid",
  "productId": "uuid" | null,     // Future webhooks may apply at org level
  "environmentId": "uuid" | null,
  "payload": { ... type-specific payload ... }
}

シグネチャ

シグネチャは、16進数形式 (小文字) の HMAC_SHA256 ハッシュで、秘密鍵は webhook で設定した Webhook シークレット コード です。

x-kws-signature ヘッダー内に以下の形式で送信されます。

x-kws-signature: t=<timestamp>,v1=<signature>[,v1=<signature>]

現状では、v1 シグネチャが 1 つ含まれますが、以下の場合は複数のシグネチャをヘッダーに含めることができます。

  • シグネチャ キー ローテーションに対応しています (移行期間は前回のキーと現在のキーが送信されます)。

  • シグネチャのアルゴリズムは変更します (移行期間は、v2 シグネチャが v1 シグネチャと一緒に送信されます)。

v1 シグネチャを生成するアルゴリズムは、シグネチャ ヘッダに含まれるタイムスタンプの HMAC_SHA256、ピリオド「.」、そして生のリクエスト ボディの順です。HMAC は webhook の秘密鍵で初期化されています。

たとえば、次のように確認します。

const timestamp = /* extracted value of ‘t=' from the header */;
const body = /* raw request body as UTF-8 string */;
const secretKey = /* secret key, as entered in dev portal */;
const signature = crypto
  .createHmac('sha256', secretKey)
  .update(`${timestamp}.${body}`)
  .digest('hex');

注記:生の POST ボディを使用する点が重要です。JSON をパースして再文字化しようとしないでください。JSON ライブラリ実装における不一致が原因でシグネチャのミスマッチが生じる可能性があるためです。

サービス構成レビュー

統合のテストを開始する前に、KWS はサービス構成の詳細を確認します。テスト環境またはプロダクション環境のいずれかで作成された製品はすべて、KWS 管理者によって監督されるレビュー プロセスを受けなければなりません。[Save] をクリックするとレビュー プロセスが開始されます。

構成がレビューされたときに通知し、レビュー プロセスに合格しなかった場合は、拒否の理由を提供します。通常、月曜日から金曜日の 7 営業日以内に 製品 を確認します。レビュー数が多い期間は、さらに長くかかる場合があります。

製品を削除する

KWS 組織から 製品 は、以下の手順で削除します。

  1. KWS Developer Portal の ダッシュボード で必要な製品を探します。 2.[Delete (削除)] をクリックします。

製品 が削除されると、以下のことが起こります。

  • Developer Portal で製品に適用されていたすべてのブランディングが削除されます。

  • 製品にリンクされていたすべてのサービスが無効になります。

タグ