公開鍵（RS256）で署名済みメタデータを送信する

最終更新日: 2026年07月07日 09:53

重要:公開鍵による署名付きメタデータ（RS256）は有料機能であり、デフォルトでは有効になっていません。アクセスを希望される場合は、Pendoサポートにご連絡ください。

一般的な Pendo インストールでは、アプリケーションはメタデータを SSL または TLS 経由で JSON オブジェクトとして Pendo に渡します。一部の業界では、このメタデータが輸送中に改ざんされていないことの追加保証を求めています。署名されたメタデータは、オープンスタンダード（RFC 7519）である JSON Web Token（JWT）を追加します。これにより、メタデータがアプリケーションから生成され、Pendo に届く前に変更されなかったことが検証されます。

従来のJWTで署名されたメタデータを送信オプションは、共有シークレットとHMAC SHA・256（HS256）を使用します。Pendoで共有トークンを生成し、その共有シークレットでJWTに署名すると、Pendoは同じシークレットでそれらを検証します。

この記事では、別の選択肢として公開鍵を用いた署名済みメタデータについて説明します。このセットアップでは、RS256 アルゴリズムを使用して独自の RSA キーで JWT に署名し、一致する公開キーを JWKS（JSON Web Key Set）URI で公開します。これにより、Pendo はデータがアプリケーションからのもので、Pendo に届く前に変更されていないことを確認できます。この記事の残りの部分では、この署名付きメタデータを「署名付きメタデータ」と呼びます。

JWT はメタデータを暗号化しません。署名します。署名によってメッセージが変更されていないことが確認されますが、内容は他の当事者が閲覧可能です。標準的なSSLまたはTLS暗号化は機密性を別途扱います。

この機能は複雑さを増し、正しく実装しないとデータが失われる可能性があります。ほとんどの設置では必要ありません。すでに署名済みメタデータと共有シークレット（HMAC SHA-256）をご使用の場合は、「JWTで署名済みメタデータを送信」をご覧ください。公開鍵を含む署名付きメタデータは、独自の署名鍵を管理し、JWKSエンドポイントを通じて公開鍵を公開する必要があるお客様を対象としています。

この記事では、公開鍵付きの署名付きメタデータを利用して Pendo をインストールする手順について説明します。

始める前に

公開鍵付きの署名済みメタデータを使ってインストールするには、以下の条件が必要です：

サブスクリプションの公開鍵付き署名済みメタデータへのアクセス。この機能はすべての有料プランで利用できますが、デフォルトではオフになっています。アクセスを希望される場合は、Pendo サポートにご連絡ください。
Pendoサブスクリプションへの管理者アクセス
Pendoのインストールコードを変更し、JSON Webトークンを生成して送信するためのエンジニアリングリソース。
公開署名鍵をJSON形式で提供する、パブリックアクセス可能なJWKS URI。Pendo が JWT 署名を検証するには、このエンドポイントにアクセスできる必要があります。
RSAキーペア、または回転用の複数のペア。秘密鍵はサーバー上のJWTに署名します。対応する公開鍵がJWKSドキュメントに公開されています。

JWT を有効にする前に、まず署名されたメタデータなしで Pendo をインストールしてセットアップを検証することをお勧めします。

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

ステップ1：公開鍵を使用して署名付きメタデータを有効化し、JWKS URIを設定します。

PendoにJWKS URIを保存する前に、エンジニアリングチームはJWKSエンドポイントで公開署名鍵を公開する必要があります。JWKS URIは、PendoがJWT署名の検証に使用する公開鍵を含む有効なJWK Setドキュメントを返すHTTPSエンドポイントである必要があります。セット内の各キーには、それを一意に識別するキーID（kid）を含める必要があります。

JWKS URIは、以下の要件を満たす必要があります。満たしていない場合、Pendoに保存できません：

HTTPSスキームを使用します。
パブリックアドレスに名前解決します。リンクローカルおよびプライベートIPの範囲は許可されていません。
HTTP 200 レスポンスを返します。Pendoはリダイレクトに従いません。
クエリパラメータやフラグメントは含めません。

警告：プライベートキーはサーバーにのみ保管してください。クライアント側のアプリケーションコードに秘密鍵を埋め込むのは絶対に避けてください。

公開鍵で署名済みメタデータをオンにします

公開鍵付きの署名済みメタデータを受け入れるためのアプリケーション：

「Pendoの右上にある［設定（Settings）］から［サブスクリプション設定（Subscription settings）］に移動します。」
［アプリケーション（Applications）］タブを開き、該当するアプリケーションを選択します。
［インストール設定（Install Settings）］タブを開きます。
［高度なセキュリティ（Advanced security）］で、［公開鍵付き署名済みメタデータを使用（Use signed metadata with public keys）］設定を見つけて有効にします。ウェブアプリについては、［スニペットをカスタマイズ（Customize your snippet）］にあります。モバイルアプリについては、［SDKをカスタマイズ（Customize your SDK）］にあります。
この設定を有効にすると、［JSON Web Key Set（JWKS）URI］フィールドが表示されます。次のステップに進みます：JWKS URIを設定して保存します。

注：［高度なセキュリティ（Advanced security）］設定は、サポートチームがお客様のサブスクリプションで署名付きメタデータを有効にするまで表示されません。詳細については、［始める前に（Before you begin）］を参照してください。

JWKS URIを設定して保存する

共有シークレット付きの署名付きメタデータとは異なり、RS256署名付きメタデータはPendoで生成された署名キーを使用しません。公開鍵を公開する JWKS エンドポイントを登録します：

同じ［インストール設定（Install Settings）］ページで、［JSON Web Key Set（JWKS）URI］フィールドにJWKSエンドポイントのURLを入力します。
［テストURI（Test URI）］を選択します。PendoはURIにアクセスできることを確認し、有効なJWK Setを返します。
テストが成功したら、［URIを保存（Save URI）］を選択します。
- テストと保存の両方の手順を完了する必要があります。テストだけでは、アプリケーションの公開鍵付き署名済みメタデータは有効になりません。JWKS URI を保存せずに署名付きメタデータを送信しようとすると、それらのセッションのデータは破棄されます。
- 保存した URI の横にある編集アイコンを使用して、後で JWKS URI を編集できます。変更を保存する前に、必ずURIを再度テストしてください。
- JWKS URIを保存すると、［署名済みメタデータのみを許可（Only allow signed metadata）］オプションが表示されます。署名済みメタデータを含むイベントを送信していることを確認するまで、［署名済みメタデータのみを許可（Only allow signed metadata）］（ステップ3内）をオンにしないでください。
URIが検証されたら、以下の［ステップ2. 公開鍵付き署名済みメタデータの送信を開始（Step 2. Start sending signed metadata with public keys）］に進んでください。そうでない場合は、［JWKS URI検証エラー（JWKS URI validation errors）］を参照してください。

注：［署名済みメタデータのみを許可（Only allow signed metadata）］が有効な間は、［公開鍵付き署名済みメタデータを使用（Use signed metadata with public keys）］を無効にしたり、JWKS URIを編集できません。変更するには必ずオフにする必要があります。

JWKS URI検証エラー

URIが検証されない場合、Pendoは以下のいずれかのメッセージを表示します：

エラー	考えられる原因
JWKS URI が無効です	URIのフォーマットが不適切になっているか、先に挙げた要件を満たしていない。
指定されたURIにアクセスできませんでした	ネットワーク、DNS、またはファイアウォールの問題が原因でPendoがエンドポイントにアクセスできない。
指定されたURIからJWK Setを取得できません	エンドポイントは応答したが、有効なJWK Setドキュメントを返さなかった。
JWKS URIは空にできません	URI が入力されていない。

ご使用のJWKSエンドポイントがPendoのサーバーからアクセス可能で、有効なJSON Web Key Setを返すことを確認してください。

ステップ2. 公開鍵付き署名済みメタデータの送信を開始する

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

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

アプリケーションコード内で直接JWTの作成、署名を行わないでください。プライベートキーを安全に保つには、initialize（Web の場合）または startSession（モバイルの場合）メソッドを呼び出す前に、署名付き JWT をサーバー上に作成してアプリケーションに渡します。

RS256署名付きJWTを生成する

JWTを生成、署名するためのライブラリは数多くあります。署名付き JWT を生成して Pendo でセッションを開始する場合、考慮すべき点がいくつかあります：

JWT は RS256 アルゴリズム（RSA と SHA-256）で署名されていること。このアルゴリズムで署名されていないJWTの場合、Pendoは署名を検証できず、イベントが処理されません。
JWTヘッダーには、JWKSドキュメント内の公開鍵と一致するキーID（kid）が含まれていること。
JWT ヘッダーには、JWKSドキュメント内のパブリックキーと一致するキーID（kid）が含まれていること。Pendoはこの値を使用して、署名検証用の正しい公開鍵を選択します。
JWTペイロードには、それぞれidプロパティと値を持つvisitor要素とaccount要素の両方が含まれていること。
訪問者IDとアカウントIDは、JWTインストールの文字列として渡すこと。匿名の訪問者を生成するには、訪問者要素のidプロパティの値として空の文字列を使用します。アカウントのIDプロパティは、空の文字列に設定することも可能です。追加の訪問者とアカウントのプロパティはオプションです。
nonceプロパティをクレームに格納すること。クライアントによってランダムに生成されるnonce文字列は、JSONのトップレベルでvisitorまたはaccountと同じ階層のプロパティとして指定する必要があります。visitorまたはaccountの内部に含めることはできません。明示的に値を検証することはないですが、値は必要です。ランダムなnonceを格納することで、同じクレームでも常に異なるトークンにすることができます。
必要に応じて追加の設定をJWTメタデータ内に含めることが可能。
履歴メタデータ値は、すべてのJWTに含める必要があります。

Pendoで訪問者セッションを開始するためのRS256署名付きJWTを生成する擬似コードを次に示します：

```javascriptconst payload = {
    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 Listen, or NPS Email
        // full_name:   // Recommended if using Pendo Listen
        // 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 Listen; must be a string. Pass an empty string if not applicable.
        // name:         // Optional
        // is_paying:    // Recommended if using Pendo Listen
        // monthly_value:// Recommended if using Pendo Listen
        // 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: 'ランダムに生成した値'  // 使用するたびに異なる値にする必要があります
};

const jwt = JWT.sign(
payload,
 PRIVATE_RSA_KEY, // RSA秘密鍵です。クライアントコードには絶対に含めないでください。
{
        algorithm: 'RS256',
        keyid:     'YOUR-KEY-ID'  // Must match a kid in your JWKS document
    }
）;

警告：アプリケーションのコードに秘密鍵の値を含めることはできません。作成する 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, PRIVATE_RSA_KEY, { algorithm: 'RS256', keyid: 'YOUR-KEY-ID' });
pendo.initialize({
     jwt: jwt
})

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

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

ウェブ実装

Web 実装の場合は、initialize メソッドの一部として、アプリケーションの Pendo インストールスクリプトに JWT を渡します。

pendo.initialize（{
    jwt: 'JWT-SIGNED-TOKEN'   // obtained from your server
}）;

モバイル実装

モバイル実装の場合は、startSession メソッドの一部として JWT を渡します。

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

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

String jwt = "JWT-SIGNED-TOKEN";   // obtained from your server
Pendo.jwt.startSession(jwt);

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

PendoManager.shared（）.setup（pendoAppKey,nil);

let jwt = "JWT-SIGNED-TOKEN";      // obtained from your server
PendoManager.shared().jwt.startSession(jwt);

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

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

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

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

インストールスクリプトが更新され、署名付きメタデータを送信している場合、セキュアなメタデータのないセッションからのデータを今後確実に破棄するように強制することができます。この時点では、保存済みのJWKS URIとともに［公開鍵付き署名済みメタデータを使用（Use signed metadata with public keys）］のみが有効になっています。そのため、Pendoは設定に応じて、有効なJWTを含むメタデータと含まないメタデータの両方を受け入れます。

［署名付きメタデータのみを許可（Only allow signed metadata）］を有効にすると、検証済みの署名付きJWTが含まれたイベントのみが処理されます。この設定をオンにするには：

「Pendoの右上にある［設定（Settings）］から［サブスクリプション設定（Subscription settings）］に移動します。」
［アプリケーション（Applications）］タブを開き、該当するアプリケーションを選択します。
［インストール設定（Install Settings）］タブを開きます。
［署名付きメタデータのみを許可］を有効にします。
確認チェックリストを確認し、 「理解しました」と入力して確定します。これにより、署名がないメタデータを含むイベントはすべて破棄されます。署名された JWT がクライアントまたはモバイルデバイスで生成および取得された後、JWT は Pendo のサーバーに送信されます。Pendo は、設定された JWKS URI からパブリックキーを取得し、JWT ヘッダーの kid を使用して JWT 署名を検証します。Pendoは無効なJWTで送信されたイベントは処理しません。破棄されたデータは復元できません。

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

Pendoリプレイ保護

JWT を使用する署名付きメタデータでは、同じトークンの再生を防止するためによく使用される jti クレーム（各 JWT に割り当てられた一意の識別子）は使用されません。代わりに、Pendo は受け取った重複イベントをすべて削除します。これにより、同じイベントが複数回処理されるのを防ぐことができます。トークンが漏洩した場合の影響を軽減するために、署名キーを定期的にローテーションすることもできます。

署名キーのローテーション

署名されたメタデータ JWT は、署名が有効で、対応する公開鍵が JWKS ドキュメントに存在する限り有効です。長期間使用される JWT が侵害された場合に悪用されないようにするには、定期的にキーをローテーションすることが最善の方法です。

署名キーをローテーションするには：

新しい RSA キーペアを生成します。
新しいkidを持つ新しい公開鍵をJWKSエンドポイントに追加します。
10 日以上待ってから、新しい秘密鍵で JWT に署名するようにサーバーを更新してください。JWT ヘッダーの kid フィールドを、新しいキーの ID と一致するように設定します。待機すると、新しいキーが使用される前に Pendo のキーキャッシュを更新する時間が与えられます。
すべてのアクティブなセッションで新しいキーが使用されるようになったら、JWKSドキュメントから古い公開鍵を削除します。

警告：対応する新しい秘密鍵でJWTに署名するようにアプリケーションが更新される前に、JWKSドキュメントから公開鍵を削除した場合、Pendoに送信されたJWTがPendoが検証できる鍵で署名されるまでデータは処理されません。

共有シークレットを使用した署名付きメタデータとは異なり、RS256キーローテーションはJWKSエンドポイントを通じてユーザー側で完全に管理されます。Pendoは、RS256署名付きメタデータの署名鍵を生成または取り消しません。

公開鍵で署名済みメタデータをオフにする

アプリケーションの公開鍵による署名付きメタデータ（RS256を使用）を無効にする必要がある場合は、インストール設定ページから無効にできます。

警告：署名付きメタデータをオフにすると、保存されている JWKS URI が削除され、現在署名付き JWT を送信しているセッションのデータが失われます。破棄されたデータは復元できません。オフにする前に、アプリケーションが署名されていないメタデータを送信できる準備ができているか確認してください。

「Pendoの右上にある［設定（Settings）］から［サブスクリプション設定（Subscription settings）］に移動します。」
アプリケーションタブ
該当するアプリを見つけて開きます。
［インストール設定（Install Settings）］タブを開きます。
公開鍵で署名済みメタデータを使用をオフにします。
確認チェックリストを確認し、 「理解しました」と入力して確定します。

保存した JWKS URI はすぐに削除されます。署名付き JWT で送信されたイベントは、この設定をオフにすると処理されなくなります。

注：署名付きメタデータのみを許可する設定が有効になっている場合、公開鍵で署名付きメタデータを使用するを無効にすることはできません。署名付きメタデータのみを許可するを先にオフにしてください。

トラブルシューティング

症状	チェックすべき事項
公開鍵で署名されたメタデータを有効にした後、イベントの生データにデータが表示されません。	JWKSのURIがテストだけでなく、保存されていることを確認してください。JWTがRS256で署名されていることと、JWTヘッダーの`kid`がJWKSドキュメント内のキーと一致していることを確認しましょう。
署名済みメタデータを強制した後、データは停止しました	すべてのアプリケーションバージョンが有効な JWT を送信することを確認してください。クライアントがまだ署名されていないメタデータを送信しているか確認しましょう。
JWKS URIテストの失敗	エンドポイントがパブリックにアクセス可能であり、HTTPSを使用し、有効なJSONを返し、リダイレクトなしでHTTP 200レスポンスを返し、クエリパラメータやフラグメントがないことを確認してください。
キー回転後にドロップされたイベント	新しい公開鍵が JWKS ドキュメントにあり、新しい JWT のヘッダーに一致する `kid` が含まれていることを確認します。

JWTで署名済みメタデータを送信（レガシーHMAC・SHA-256共有秘密署名）
インストールスクリプトを使用したPendoの実装に関する開発者ガイド
開発者向けインストールガイド（PendoモバイルSDK）