JWT署名付きメタデータを使用したモバイルインストール

最終更新日: 2023年11月21日 14:48

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

通常のモバイルアプリケーションのインストールでは、モバイルデバイスはメタデータをJSONオブジェクトとして直接Pendoエージェントに渡します。アプリケーションとPendoの間でやり取りするデータはすべて、Security Sockets Layer（SSL）プロトコルで暗号化されて転送されます。一部の業種では、さらに通信中にメタデータが改ざんされていないことを保証する必要があります。署名付きメタデータでは、メタデータにJSON Web Token（JWT）を添付することで、メタデータが変更されていないこと、および特定のモバイルデバイス以外から送信されたものではないことを検証できます。

備考：これは任意で、ほとんどのインストールでは不要です。これを使うと複雑になるだけでなく、誤って実装されている場合にデータが失われる可能性があります。

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

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

要件

有効な署名付きメタデータアクセス
サブスクリプションの管理者アクセス
Pendo SDKを含むモバイルアプリケーションを修正できる技術者
JSON Web Token（JWT）を生成し、モバイルアプリケーションを搭載した端末に送信できる技術者

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

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

［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］に移動します。
［アプリケーション（Applications）］タブを開きます。
［アプリケーション］リストから該当するアプリを見つけて開きます。
［インストール設定（Install Settings）］タブを開きます。
［署名付きメタデータを使用する］の横にある［有効化（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 = JWT.sign({

   visitor:{
        id:             'VISITOR-UNIQUE-ID' // Required field, 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 field, 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をサーバー側から取得する必要があります。メタデータを含むJWTは、鍵IDに対応する生成された鍵で署名する必要があります。署名付きJWTを生成してモバイルデバイスで取得すると、メタデータを生のJSON bodyとして送信せずに、JWTと鍵IDをPendoサーバーに送信します。PendoはJWTが改ざんされていないことを確認し、無効なJWTで送信されたイベントを処理しないようにします。モバイルアプリケーションでJWTと鍵IDを送信するには、Pendo.jwt.startSessionの呼び出しに、jwtとsigningKeyName引数プロパティとして渡します。Pendo.jwt.startSessionの呼び出しは、Pendo.setupを呼び出した後に行う必要があります。

AndroidモバイルデバイスがPendoにJWTを送信する例（Java）：

Pendo.setup(this, pendoAppKey, null, null);

String jwt = “JWT-SIGNED-TOKEN”; // サーバから取得
String signingKeyName = “SECRET-KEY-ID” // サーバから取得
Pendo.jwt.startSession(jwt, signingKeyName);

iOSモバイルデバイスがPendoにJWTを送信する例（Swift）：

PendoManager.shared().setup(pendoAppKey, nil);

let jwt = “JWT-SIGNED-TOKEN”; // サーバから取得
let signingKeyName = “SECRET-KEY-ID” // サーバから取得
endoManager.shared().jwt.startSession(jwt, signingKeyName);

JWT秘密鍵の交換と無効化

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

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

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

無効化した鍵のログは、［アクティブな鍵（Active Keys）］セクションで確認できます。

Screen_Shot_2022-02-17_at_12.44.25.png

Screen_Shot_2022-02-17_at_12.44.37.png

追加の設定

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

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

サーバー側で生成された匿名訪問者のJWTの例：

const jwt = JWT.sign({
nonce: "abcdefg78910xyz",

訪問者: { 
         id: "SESSION-VISITOR-UNIQUE-ID",
         existingVisitorField: "some value"
    },

 アカウント: {
         id: "",
         otherAccountField: "some other value"
    }
},
'SECRET KEY'
);

匿名の訪問者の識別

匿名IDで初期化した後に、訪問者を一意の訪問者IDで識別する場合は、更新された訪問者IDと必要に応じてメタデータを含むJWTでPendo.jwt.startSessionを再度呼び出してください。この機能は、従来のPendoインストールと同じように機能します。

セッション中に訪問者データを更新できますか？

Pendo.setVisitorDataおよび／もしくはPendo.setAccountDataを呼び出すことで、セッション中に訪問者データを蓄積／更新することができます。これらの呼び出しを行う際は、Pendo.startSessionと同様にJWTと鍵IDを渡します。ただし、これらの呼び出しのJWTペイロードは、以下の条件を満たしている必要があります。

ペイロードには、訪問者プロパティもしくはアカウントプロパティのいずれかを含める必要がありますが、両方を含めることはできません。
訪問者IDまたはアカウントIDは、Pendo.jwt.startSessionを呼び出す際に渡されたJWTで使用されたID値と同一である必要があります。

訪問者データを更新するために生成されたJWTの例：

const jwt = JWT.sign({
nonce: "abcdefg78910xyz",

visitor: { 
         id: "SESSION-VISITOR-UNIQUE-ID",
         newVisitorField: "new value",
         existingVisitorField: "updated value"
   }
},
'SECRET KEY'
);

アカウントデータを更新するために生成されたJWTの例：

const jwt = JWT.sign({
nonce: "abcdefg78910xyz",

account: {
         id: "SESSION-ACCOUNT-UNIQUE-ID",
         newAccountField: "new value",
         existingAccountField: "updated value"
    }
},
'SECRET KEY'
);

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

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

要件