重要：この機能は、Pendoの担当者が有効にする必要があります。アクセスを希望される場合は、Pendoサポートにご連絡ください。
通常のPendoインストールでは、クライアントはメタデータをJSONオブジェクトとして直接Pendoエージェントに渡します。アプリケーション内のエージェントとPendoの間でやり取りするデータはすべて、Security Sockets Layer（SSL）プロトコルで暗号化されます。
一部の業種では、さらに通信中にメタデータが改ざんされていないことを保証する必要があります。署名付きメタデータでは、メタデータにJson Web Token（JWT）を添付することで、メタデータが変更されていないこと、およびエージェント以外から送信されたものではないことを検証できます。これは任意で、ほとんどのインストールでは不要です。これを使うと複雑になるだけでなく、誤って実装されている場合にデータが失われる可能性があります。
Pendoのインストールスクリプトと連動して署名付きメタデータを使用する場合、Pendoエージェントに渡されるメタデータを署名付きトークンに格納して、その中に含まれるクレームの完全性を検証する必要があります。クレームは他の当事者が参照できます。クレームを参照できるかどうかは標準的なデータ暗号化の問題ですが、署名はメッセージが途中で変更されていないことを確認する目的で使われます。
署名は暗号化ではありません。ホテルの鍵のようなものだと考えてださい。ホテルのフロントでチェックインすると渡されるプラスチック製の電子カードキー（トークン）を使って自分の部屋、プール、駐車場に入ることができますが、他の人の部屋やマネージャーのオフィスに入ることはできません。自分の鍵を使って自分の部屋に入れますが、他の人はその鍵を持っていないためあなたの部屋には入れません。滞在期間が過ぎるとホテルのカードキーが役に立たないプラスチック片になるのと同じで、トークンも期限が切れると使えません。
要件
- 有効な署名付きメタデータのアクセス権
- サブスクリプションの管理者アクセス権
- Pendoインストールスクリプトを変更できるエンジニア
署名付きメタデータを許可するアプリケーション設定
表示するにはサブスクリプションの［高度なセキュリティ（Advanced Security）］の設定で署名付きメタデータを有効にする必要があります。［高度なセキュリティ］を利用できない場合は、Pendoの担当者にお問い合わせください。
JWT付きのデータを利用可能にするには、アプリケーションで［署名付きメタデータを使用する（Use signed metadata）］を有効にする必要があります。この設定を有効にしていない場合、署名付きメタデータを送信しても破棄されます。
-
［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］に移動します。
-
［アプリケーション（Applications）］タブを開きます。
-
［アプリケーション］リストから該当するアプリを見つけて開きます。
- ［インストール設定（Install Settings）］タブを開きます。
- ［スニペットをカスタマイズ（Customize your snippet）］で［有効化（Enable）］を選択して、署名付きメタデータを許可します。
- インストールスクリプトを更新して、署名付きメタデータを送信します。署名付きメタデータを送信するまで次のステップは行わないでください。
- ［署名付きメタデータを使用する］を有効にすると、JWTの有無にかかわらずメタデータが許可されます。
- ［署名付きメタデータのみを許可（Only allow signed metadata）］を有効にすると、検証済みの署名付きJWTが含まれたイベントのみが処理されます。
- ［署名付きメタデータを使用する］を無効にすると、JWTが含まれるイベントは許可されません。
-
インストールスクリプトを更新して署名付きメタデータを送信する場合、［署名付きメタデータのみを許可］を有効にします。
- 署名付きメタデータのみを許可することを確認します。これにより、署名が無いメタデータを含むイベントはすべて破棄されます。破棄されたデータは復元できません。
鍵の生成
この鍵はメタデータの署名に使われます。1つのアプリケーションにつき、最大5つの有効な鍵を作成することができます。セットアップが完了すると、アプリケーションでは5つの有効な鍵のいずれかと一緒に送信されたデータのみ許可されます。
- ［インストール設定］の［有効な鍵（Active Keys）］テーブルに移動し、［鍵を生成（Generate Key）］を選択します。
- ［説明（Description）］を入力して、後で何の鍵か識別できるようにします。［作成（Create）］を選択して、新しい鍵を追加します。
- これで、この鍵は［有効な鍵］テーブルで利用可能になります。なお鍵は、デフォルトでは非表示です。［表示（Show）］を選択すると、鍵が表示されます。
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 bodyとして送信するのではなく、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, must be a string
// 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が無効な場合はイベントを処理しません。
訪問者IDとアカウントIDは、JWTインストールの文字列として渡す必要があります。
JWT秘密鍵の交換と無効化
以前に使用したJWT秘密鍵を無効にするには、［インストール設定］ページで新しい鍵を生成します。新しい鍵が正しく生成されたら、前の鍵は無効にします。
警告：インストールスクリプトを新しい鍵に更新する前に有効な鍵を無効化してしまうと、新しい鍵で署名したJWTをPendoに送信するまでデータは処理されません。
鍵を無効化するには、鍵の上にカーソルを合わせて［鍵を無効化（Revoke Key）］アイコンを選択します。確認が終わると、その鍵は永久に無効になります。一度無効にすると元に戻すことはできません。
［無効化した鍵（Revoked Keys）］のすべてのログは、［有効な鍵］セクションの下部で確認できます。
追加の設定
署名付きメタデータを使用して匿名の訪問者を追跡できますか？
訪問者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トークンが侵害された場合に悪用を防ぐには、トークンを定期的に無効化して交換することが一番良い方法です。