JWTで署名付きメタデータを送信する

最終更新日: 2024年04月23日 03:53

重要：JWTで署名されたメタデータを使用してインストールする機能は、Pendoの担当者が有効にする必要があります。アクセスを希望される場合は、Pendoサポートにご連絡ください。

通常のPendoインストールでは、アプリケーションはメタデータをJSONオブジェクトとしてPendoサーバーに渡します。アプリケーションとPendoの間でやり取りするデータはすべて、Security Sockets Layer（SSL）プロトコルで暗号化されて転送されます。

一部の業種では、さらに通信中にメタデータが改ざんされていないことを保証する必要があります。Pendoの署名付きメタデータにはJSON Web Tokens（JWT）を使う必要があります。JWTは、二者間での安全なクレームを表すためのオープンな業界標準方式（RFC 7519）です。

この記事では、JWTで署名付きメタデータを使用してPendoをインストールするプロセスについて説明します。これは概ね、以下の手順で実施します。

JWTで署名付きメタデータを有効にする
メタデータに署名するための鍵を生成する
署名付きメタデータの送信を開始する
署名付きメタデータを送信していることを確認する
署名付きメタデータのみを適用する

JSON Web Token（JWT）のインストール

JSON Web Token（JWT）は、当事者間で情報をJSONオブジェクトとして安全に送信するためのコンパクトで自己完結型の方法を定義するオープンスタンダードです。

署名付きメタデータは、メタデータにJWTを添付して、メタデータが変更されていないこと、およびアプリケーション以外のソースから送信されたものではないことを検証するために使用されます。これは任意で、ほとんどのインストールでは不要です。これを使うと複雑になるだけでなく、誤って実装されている場合にデータが失われる可能性があります。

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

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

前提条件

JWTを用いて署名されたメタデータを使用してインストールするには、以下が必要です。

JWTでインストールするサブスクリプションの有効な署名付きメタデータのアクセス権。デフォルトではオフになっている有料機能で、Pendoの担当者が有効にする必要があります。
Pendoサブスクリプションへの管理者ユーザーアクセス権。
Pendoのインストールコードを変更し、JSONウェブトークンを生成して送信するためのエンジニアリングリソース。

JWTを用いたスムーズなインストールを行うには、まずPendoを署名付きメタデータなしでインストールすることをお勧めします。

ウェブでの直接実装の詳細については、インストールスクリプトを使用したPendoの実装に関する開発者ガイドを参照してください。
モバイル実装の詳細については、開発者向けインストールガイド（PendoモバイルSDK）を参照してください。

ステップ1. JWTで署名付きメタデータを有効にする

アプリケーションがJWTでデータを受け入れるようにするには、まずアプリケーションの［インストール設定（Install Settings）］ページの［高度なセキュリティ（Advanced Security）］で［署名付きメタデータを使用する（Use signed metadata）］を有効にする必要があります。この設定を有効にしていない場合、署名付きメタデータを送信してもこれらのセッションのデータはすべて破棄されます。

［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］に移動します。
［アプリケーション（Applications）］タブを開きます。
［アプリケーション］リストから該当するアプリを見つけて開きます。
［インストール設定（Install Settings）］タブを開きます。
［高度なセキュリティ］で［有効化（Enable）］を選択して、署名付きメタデータを許可します。
- ウェブ実装の場合、これは［スニペットをカスタマイズ（Customize your snippet）］の下にあります。
- モバイル実装の場合、これは［SDKをカスタマイズ（Customize your SDK）］の下にあります。

注：アプリケーションの［インストール設定］ページに［高度なセキュリティ］設定が表示されない場合は、Pendoの担当者に連絡して、サブスクリプションで署名付きメタデータを有効にしてください。詳細については、前提条件を参照してください。

［署名付きメタデータを使用する］を有効にすると、別のオプション［署名付きメタデータのみを許可する（Only allow signed metadata）］が表示されます。これは、メタデータに署名するための鍵を少なくとも1つ生成するまでグレーアウトされます。鍵を作成したら、ステップ4. 署名付きメタデータを使用してイベントを送信していることを検証するで説明されているように、署名付きメタデータを使用してイベントを送信していることを確認するまで、［署名付きメタデータのみを許可する］を有効にしないでください。

ステップ2. メタデータに署名するための鍵を生成する

JWTのインストールでは、すべてのリクエストをJWT共有シークレットを使用して署名する必要があり、署名しないとデータが削除されます。

サブスクリプションのJWTで署名付きメタデータを有効にすると、メタデータに署名するための鍵が必要になります。この鍵は、［アプリの詳細（App Details）］>［基本設定（Basic settings）］と進んだときに表示されるAPIキーとは異なります。APIキーは、Pendoとアプリケーションを接続するために使用するものです。

通常、有効な鍵は1つで十分ですが、1つのアプリケーションごとに、同時に最大5つの有効な鍵を持つことができます。

［インストール設定（Install Settings）］から、［有効な鍵（Active Keys）］テーブルに移動し、［+ 鍵を生成（+ Generate Key）］を選択します。
鍵にわかりやすい説明を入力します。
［作成］を選択します。これで、この鍵は［有効な鍵］テーブルで利用可能になります。

鍵はデフォルトでは非表示です。［表示（Show）］を選択すると、鍵が表示されます。

ステップ3. 署名付きメタデータの送信を開始する

署名付きメタデータをPendoに送信するには、メタデータを保持するJWTを作成し、Pendoに送信するための技術リソースまたはエンジニアリングリソースが必要です。まだインストールしていない場合は、続行前にまずメタデータなしでPendoをインストールすることをお勧めします。

ウェブでの直接実装の詳細については、インストールスクリプトを使用したPendoの実装に関する開発者ガイドを参照してください。
モバイル実装の詳細については、開発者向けインストールガイド（PendoモバイルSDK）を参照してください。

アプリケーションコード内で直接JWTを作成したり、署名したりしないでください。秘密鍵を安全に保ち、自分とPendoだけに分かるようにするには、サーバー側で署名付きJWTを作成し、initializeメソッド（ウェブの場合）またはstartSessionメソッド（モバイルの場合）を呼び出す前に、署名鍵の名前とともにアプリケーションに渡す必要があります。

署名付きJWTを生成する

JWTを生成、署名するためのライブラリは数多くあります。Pendoでセッションを開始するために必要な署名付きJWTを生成する場合、いくつかの注意点があります。

JWTは、鍵IDに対応する生成した鍵で署名する必要があります。
JWTペイロードには、それぞれidプロパティと値を持つ訪問者要素とアカウント要素の両方が含まれている必要があります。
訪問者IDとアカウントIDは、JWTインストールの文字列として渡す必要があります。匿名の訪問者を生成するには、訪問者要素のidプロパティの値として空の文字列を使用します。アカウントのidプロパティは、空の文字列に設定することもできます。追加の訪問者とアカウントのプロパティはオプションです。
nonceプロパティをクレームに格納する必要があります。nonceはクライアント側で生成したランダムな文字列で、JSONの上位部に、それらのセクションの1つには含まれていない訪問者またはアカウントと同列のプロパティとして含める必要があります。明示的に値を検証することはないですが、値は必要です。ランダムなnonceを格納することで、同じクレームでも常に異なるトークンにすることができます。
JWTに署名するときは、HMAC SHA-256アルゴリズムを使用する必要があります。このアルゴリズムで署名されていないJWTの場合、Pendoは署名を検証できず、イベントが処理されません。
必要に応じて追加の設定をJWTメタデータ内に含めることができます。
履歴メタデータ値は、すべてのJWTに含める必要があります。

次の擬似コードは、Pendoで訪問者セッションを開始するためのJWTを生成しています。

jwt = JWT.sign({

    visitor:{
        id:             'VISITOR-UNIQUE-ID' // Required if user is logged in; must be a string. Pass an empty string for an anonymous visitor.
        // 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. Pass an empty string for an anonymous visitor.
        // 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は、アプリケーション上で作成しないでください。これらは、サーバーからアプリケーションに送信する必要があります。アプリケーションは、JWTが既に署名されているサーバーから収集する必要があります。

匿名の訪問者による署名付きメタデータ

訪問者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'
})

アプリケーションのインストールコードを更新する

署名付きメタデータを送信するには、アプリケーションがサーバーからJWTと署名鍵名を取得し、セッションの開始時にPendoに渡す必要があります。

ウェブ実装

ウェブ実装の場合、JWTと鍵IDは、アプリケーションのPendoインストールスクリプトにinitializeメソッドの一部として含めることで、送信できます。initializeに渡されたJSONオブジェクトには、jwtプロパティとsigningKeyNameプロパティが格納されている必要があります。

モバイル実装

モバイル実装の場合、JWTと鍵IDは、アプリケーションのモバイルSDKインテグレーションにstartSessionメソッドの一部として含めることで、送信できます。jwtとsigningKeyNameプロパティの両方をstartSessionメソッドに直接渡す必要があります。

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);

ステップ4. 署名付きメタデータを送信していることを確認する

次の手順では、テスト対象の訪問者を把握している必要があります。通常、これには特定の訪問者としてのアプリケーションへのサインインが含まれます。

［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］>［アプリケーション（Applications）］に移動します。
アプリケーションを見つけて開きます。
［イベントの生データ］タブを開きます。
テスト対象の訪問者からPendoに新しいデータが流れ込んでいることを確認します。

ステップ5. 署名付きメタデータのみを適用する

インストールスクリプトが更新され、署名付きメタデータが送信されるときに、安全なメタデータのないセッションからのデータが今後破棄されるように実施することができます。このステップまでは、［署名付きメタデータを使用する］のみが有効になっており、JWTの有無にかかわらずメタデータを受け入れます。

［署名付きメタデータのみを許可］を有効にすると、検証済みの署名付きJWTが含まれたイベントのみが処理されます。この設定を有効にするには、次の手順を実行します。

アプリケーション設定から、［インストール設定］タブを開きます。
［高度なセキュリティ］の下で、［署名付きメタデータのみを許可］を有効にします。
- ウェブ実装の場合、これは［スニペットをカスタマイズ（Customize your snippet）］の下にあります。
- モバイル実装の場合、これは［SDKをカスタマイズ（Customize your SDK）］の下にあります。
チェックリストを確認して「理解しました（I understand）」と入力し、［署名付きメタデータを有効にする］を選択して、署名付きメタデータのみを許可することを確定します。

これにより、署名がないメタデータを含むイベントはすべて破棄されます。署名付きJWTが生成され、クライアントまたはモバイルデバイスによって取得されると、JWTと鍵IDがPendoのサーバーに送信されます。Pendoは、あなたのサーバーとPendoのサーバーだけが知っている秘密鍵とJWTを照合し、改ざんされていないことを確認します。Pendoは無効なJWTで送信されたイベントは処理しません。破棄されたデータは復元できません。

重要事項：公開アプリケーションが安全なメタデータなしでPendoを使用している場合、またはモバイル訪問者がJWTを使用してアプリケーションのバージョンを更新する時間がなく、このセクションの手順を使用して署名付きメタデータを適用しようとすると、データが失われる可能性があります。

リプレイ攻撃

JWTを使用した署名付きメタデータは、通常、リプレイ攻撃を防ぐために一般的に使用される「jtiクレーム」（各JWTに割り当てられた一意の識別子）をサポートしていません。代わりに、Pendoは、重複して受信したイベントをすべて破棄し、悪意のあるユーザーによる同一イベントのリプレイを防止します。さらに、リプレイ攻撃を軽減する方法として、JWT秘密鍵を交換および無効化することができます

JWT秘密鍵の交換と無効化

署名付きメタデータJWTは、署名が有効である限り有効です。長期間有効なJWTが侵害された場合に悪用を防ぐには、トークンを定期的に交換して無効化することが一番良い方法です。これはリプレイ攻撃への対策として重要です。

以前に使用したJWT秘密鍵を交換するには、［インストール設定］ページで新しい鍵を生成してください。手順については、ステップ2. メタデータに署名するための鍵を生成するを参照してください。無効化させたい鍵に代わる新しい鍵を、JWTの署名に使い始める必要があります。古い鍵を無効化する前に、JWTと共にアプリケーションに送信される鍵IDを更新してください。その後、古い鍵を無効化することができます。

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

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

Screen_Shot_2020-04-06_at_3.09.51_PM.png

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