1. Pendoヘルプセンター
  2. インストール
  3. その他の設定

JWT署名付きメタデータを使用したスニペットインストール

最終更新日:

重要：この機能は、Pendoの担当者が有効にする必要があります。アクセスを希望される場合は、Pendoサポートにご連絡ください。

概要

通常のスニペットインストールでは、クライアントはメタデータをJSONオブジェクトとして直接Pendoエージェントに渡します。アプリケーション内のエージェントとPendoの間でやり取りするデータはすべて、Security Sockets Layer（SSL）プロトコルで暗号化されます。一部の業種では、さらに通信中にメタデータが改ざんされていないことを保証する必要があります。署名付きメタデータでは、メタデータにJSON Webトークン（JWT）を添付することで、メタデータが変更されていないこと、およびインストールしたエージェント以外から送信されたものではないことを検証できます。これは任意で、ほとんどのインストールでは不要です。これを使うと複雑になるだけでなく、誤って実装されている場合にデータが失われる可能性があります。

スニペットインストールと連動して署名付きメタデータを使用する場合、Pendoエージェントに渡されるメタデータを署名付きトークンに格納して、その中に含まれるクレームの完全性を検証する必要があります。クレームは他の当事者が参照できます。参照できるかどうかは、標準的なデータ暗号化の話です。一方、署名は、メッセージが途中で変更されていないことを確認する目的で使われます。

署名は暗号化ではありません。ホテルの鍵のようなものだと考えてださい。ホテルのフロントでチェックインすると渡されるプラスチック製の電子カードキー（つまりトークン）を使って自分の部屋、プール、駐車場に入ることができますが、他の人の部屋やマネージャーのオフィスに入ることはできません。自分は鍵を使って自分の部屋に入れますが、他の人はその鍵を持っていないのであなたの部屋には入れません。滞在期間が過ぎるとホテルのカードキーが使えなくなるのと同じで、トークンも期限が切れると使えません。

 

要件

  • 有効な署名付きメタデータアクセス
  • サブスクリプションの管理者アクセス
  • インストールしたPendoスニペットを変更できる技術者

署名付きメタデータを許可するアプリケーション設定

表示するにはサブスクリプションの［高度なセキュリティ（Advanced Security）］の設定で署名付きメタデータを有効にする必要があります。［高度なセキュリティ］を利用できない場合は、Pendoの担当者にお問い合わせください。JWT付きのデータを利用可能にするには、アプリケーションで［署名付きメタデータを使用する（Use signed metadata）］を有効にする必要があります。この設定を有効にしていない場合、署名付きメタデータを送信しても破棄されます。

 

1．［サブスクリプション設定（Subscription Settings）］＞［アプリの詳細（App Details）］＞［インストール設定（Install Settings）］に移動します。

 

2．［有効にする（Enable）］をクリックして署名付きメタデータを許可します。

EnableSM.png

 

3．スニペットインストールを更新して署名付きメタデータを送信します。署名付きメタデータを送信できるようになるまで次のステップは行わないでください。

  • ［署名付きメタデータを使用する］が有効の場合、JWTの有無にかかわらずメタデータが許可されます。
  • ［署名付きメタデータのみを許可（Only allow signed metadata）］を有効にすると、検証済みの署名付きJWTが含まれたイベントのみを処理します。
  • ［署名付きメタデータを使用する］が無効の場合、JWTが含まれたイベントは利用できません。

 

4．インストールスニペットを更新して署名付きメタデータを送信する場合、［署名付きメタデータのみを許可］を有効にします。

OnlyAllowSM.png

 

5．署名付きメタデータのみを許可することを確認してください。これにより、署名が無いメタデータを含むイベントはすべて破棄されます。破棄されたデータは復元できません。

ConfirmSMSettings.png

 

鍵の生成

この鍵はメタデータの署名に使われます。1つのアプリケーションにつき、最大5つの有効な鍵を作成することができます。セットアップが完了すると、アプリケーションでは5つの有効な鍵のいずれかと一緒に送信されたデータのみ許可されます。

 

1．［インストール設定］の［有効な鍵（Active Keys）］のテーブルに移動し、［鍵の生成（Generate Key）］をクリックします。

NoActiveKeys.png

 

2．［説明（Description）］を入力して、後で何の鍵か識別できるようにしてください。［作成（Create）］をクリックして新しい鍵を追加します。

GenerateKey.png

 

3．この鍵は［有効な鍵］のテーブルで利用可能になります。鍵はデフォルトでは非表示です。鍵を表示するには、［表示（Show）］をクリックします。

ActiveKeysTable.png

 

Pendoスニペットインストールの更新

Pendoの署名付きメタデータにはJSON Web Tokens（JWT）を使う必要があります。JWTは、二者間での安全なクレームを表すためのオープンな業界標準方式（RFC 7519）です。JWTを生成、署名するためのライブラリは数多くあります。

JWTを生成する際に注意すべき要件がいくつかあります。

  • 「nonce」プロパティをクレームに格納する必要があります。nonceはクライアント側で生成したランダムな文字列で、JSONの上位部に、それらのセクションの1つには含まれていない訪問者またはアカウントと同列のプロパティとして含める必要があります。明示的に値を検証することはないですが、値は必要です。ランダムなnonceを格納することで、同じクレームでも常に異なるトークンにすることができます。
  • JWTに署名するときは、HMAC SHA-256アルゴリズムを使用する必要があります。このアルゴリズムで署名されていないJWTの場合、Pendoは署名を検証できず、イベントが処理されません。

署名付きのメタデータを送信する場合、クライアントアプリケーションはメタデータを含むJWTを作成し、生成した鍵で署名します。署名付きのJWTを生成した後は、メタデータを生データとしてJSONのボディ部に格納して送信するのではなく、JWTと鍵IDをPendoエージェントに送信します。JWTと鍵IDは、お客様アプリケーション用のPendoスニペットにpendo.initialize呼び出しの一部として格納して送ることができます。initializeに渡されたJSONオブジェクトはjwtプロパティとsigningKeyNameプロパティが格納されている必要があります。

必要に応じて追加の設定をjwtプロパティとsigningKeyNameプロパティとともに格納することができます。

 

JWTを使ったスニペットの例

jwt = JWT.sign({

    visitor:{
        id:             'VISITOR-UNIQUE-ID' // Required if user is logged in, must be a string
        // email:       // Recommended if using Pendo Feedback, or NPS Email
        // full_name:   // Recommended if using Pendo Feedback
        // role:        // Optional
        // You can add any additional visitor level key-values here,
        // as long as it's not one of the above reserved names.
    },

    account: {
        id:           'ACCOUNT-UNIQUE-ID' // Required if using Pendo Feedback
        // name:         // Optional
        // is_paying:    // Recommended if using Pendo Feedback
        // monthly_value:// Recommended if using Pendo Feedback
        // planLevel:    // Optional
        // planPrice:    // Optional
        // creationDate: // Optional
        // You can add any additional account level key-values here,
        // as long as it's not one of the above reserved names.
    },

    nonce: 'randomly generated value'  // 毎回、異なる値を使います
},
'JWT-SECRET-KEY' // この鍵を生成します
)

 

エージェントは処理イベント送信時にJWTと鍵IDを格納します。Pendoは、JWTが改ざんされていないことを確認し、もしJWTが無効な場合はイベントを処理しません。

 

JWT秘密鍵の交換と無効化

以前に使用したJWT秘密鍵を無効にするには、［インストール設定］ページで新しい鍵を生成する必要があります。新しい鍵が正しく生成されたら、前の鍵は無効にします。

警告：スニペットを新しい鍵に更新する前に有効な鍵を無効化してしまうと、新しい鍵で署名したJWTをPendoに送信するまでデータは処理されません。

鍵を無効化するには、鍵の上にカーソルを置いて［鍵の無効化（Revoke Key）］アイコンをクリックします。確認が終わると、その鍵は永久に無効になります。一度無効にすると元に戻すことはできません。

Screen_Shot_2020-04-06_at_3.09.51_PM.png

無効化した鍵のログは、［アクティブな鍵（Active Keys）］セクションで確認できます。Screen_Shot_2020-04-06_at_3.02.58_PM.png

追加の設定

署名付きメタデータを使用して匿名の訪問者を追跡できますか？

訪問者IDに割当てられたメタデータがない状態でPendo.initialize()が呼び出されると、匿名の訪問者には訪問者IDとしてランダムな文字列が自動的に割り当てられます。匿名の訪問者IDを生成するこの方法は、従来のPendoインストールまたは署名付きメタデータのPendoインストールでも同じです。匿名の訪問者がイベントデータをPendoに渡すときにも、JWTを使用する必要があります。

JWTを使用した匿名の訪問者の初期化に使用するペイロードの例

let payload = {
     nonce: "abcdefg78910xyz",
     visitor: { // notice there is no "id" field
          otherVisitorField: "hi"
     },
     account: {
          otherAccountField: "hello world"
     }
}
const jwt = JWT.sign(payload,'SECRET KEY');
pendo.initialize({
     jwt: jwt,
     signingKeyName: 'SIGNING KEY NAME'
})

匿名の訪問者の識別
匿名IDで初期化した後に訪問者を一意の訪問者IDで識別する場合は、pendo.UpdateOptions(...)を呼び出し、必要に応じてメタデータを更新します。この機能は、従来のPendoインストールと同じように機能します。

 

ログアウト時にユーザーメタデータを消去

保存されたユーザーメタデータは、セッションの終了時に消去するのがベストプラクティスです。複数のユーザーがパソコンを共用する場合は消去することを推奨します。また複数の匿名の訪問者が同じパソコンを使用する場合は、消去することを強く推奨します。保存されたメタデータを消去しない場合、新しい匿名ユーザーとして識別されるべき別のユーザーが、保存されたメタデータによって偶然識別される可能性があり、そのユーザーの動作は以前に識別された訪問者のものとして認識されます。

この問題を解決するには、ユーザーがログアウトしたとき、またはログイン画面のように次のユーザーを識別する前に、アプリケーションでpendo.clearSession()を呼び出します。期限切れのCookieが検出されたときに読み込まれるログイン画面では、想定通りにログアウトやタイムアウトせずにブラウザを閉じた時に終了したユーザーセッションを捕捉するため特に重要です。

 

署名付きメタデータを使用するとリプレイ攻撃を防止できますか？

Pendoは、重複して受信したイベントをすべて破棄し、悪意のあるユーザーによる同一イベントのリプレイを防止します。JWTを使用した署名付きメタデータでは、リプレイ攻撃を防ぐ方法として一般的に知られている「jti」クレームはサポートしていません。署名付きメタデータJWTは、署名が有効である限り有効です。長期間有効なJWTトークンが侵害された場合に悪用を防ぐには、トークンを定期的に無効化して交換することが一番良い方法です。

 

関連記事