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

最終更新日: 2026年05月12日 07:14

重要：JWTを用いた署名付きメタデータを使用してインストールする機能は有料です。アクセスを希望される場合は、Pendoサポートにご連絡ください。

通常のPendoインストールでは、アプリケーションはメタデータをJSONオブジェクトとしてPendoに渡します。一部の業界では、このメタデータが転送中に改ざんされていないことをさらに保証する必要があります。署名付きメタデータには、オープンスタンダード（RFC 7519）であるJSON Web Token（JWT）が追加され、メタデータがアプリケーションから生成されたものであり、Pendoに到達する前に変更されていないことを検証します。

JWTはメタデータを暗号化せず、署名します。署名によってメッセージの内容が変更されていないことが証明されるが、その内容は他の第三者にも依然として読み取れる状態にあります。標準的なSSL暗号化では、機密性は別途処理されます。
この機能は複雑さを増し、正しく実装しないとデータが失われる可能性があります。ほとんどのインストールでは必要ありません。

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

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）］タブを開きます。
署名付きメタデータを受け入れるには、［高度なセキュリティ（Advanced Security）］で［有効にする（Enable）］を選択します。
- ウェブ実装の場合、これは［スニペットをカスタマイズ（Customize your snippet）］の下にあります。
- モバイル実装の場合、これは ［SDKをカスタマイズ（Customize your SDK）］ の下にあります。

注：［高度なセキュリティ］設定は、Pendoサポートがサブスクリプションの署名付きメタデータを有効にするまで表示されません。詳細については、前提条件を参照してください。

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

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

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

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

通常、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” // サーバーから取得
PendoManager.shared().jwt.startSession(jwt, signingKeyName);

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

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

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

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

インストールスクリプトが更新され、署名付きメタデータを送信している場合、セキュアなメタデータのないセッションからのデータを今後確実に破棄するように強制することができます。このステップまでは、［署名付きメタデータを使用する（Use signed metadata）］のみが有効になっていました。つまり、JWTの有無にかかわらずメタデータを受け入れることになります。

［署名付きメタデータのみを許可（Only allow signed metadata）］を有効にすると、検証済みの署名付き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に送信するまでデータは処理されません。

キーを無効化するには、アクティブキーの表でそのキーにカーソルを合わせ、キーの無効化アイコンを選択し、確認を受け入れてキーを永久に無効化します。一度無効にすると元に戻すことはできません。

Screen_Shot_2020-04-06_at_3.09.51_PM.png

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

署名付きメタデータをオフにする

アプリケーションの署名付きメタデータを無効にする必要がある場合は、［インストール設定］ページから設定できます。署名付きメタデータを無効にすると、すべての有効なキーが取り消され、Pendoは署名付きJWTを含むイベントの処理を停止します。

警告：署名付きメタデータを無効にすると、現在署名付きJWTを送信しているすべてのセッションでデータが失われます。破棄されたデータは復元できません。無効にする前に、アプリケーションが署名なしのメタデータを送信できる状態になっていることを確認してください。

［設定（Settings）］>［サブスクリプション設定（Subscription Settings）］の順に進みます。
［アプリケーション］タブを開きます。
該当するアプリを見つけて開きます。
［インストール設定］タブを開きます。
［高度なセキュリティ］で［署名付きメタデータを使用する］をオフにします。
選択を確認してください。

有効なキーはすべて即座に失効します。この設定をオフにすると、署名付きJWTで送信されたイベントは処理されなくなります。