メインコンテンツにスキップ

Messengerでのusers認証にJSON Web Tokens（JWTs）を使用する方法

Messengerとusersセッションをクロスユーザーなりすましやセッション盗難から保護する方法。

対応者：Penny Gray

サイトにログイン済みusers向けにMessengerを設置している場合、不正行為者がusersになりすましたり無許可のデータ送信を防ぐためにセキュリティ対策が必須です。​

セキュリティが不十分なMessengerでは、誰かがIntercom Messengerとやり取りし、メールアドレスやuser_idなど既知の識別子を使って別のusersの身元を偽装する可能性があります。これにより攻撃者は実際のusersになりすまし、チームメンバーに過去の会話や機密データへのアクセスを許してしまいます。

参考になれば、こちらの機能とリスク軽減のビデオ解説をご覧ください。

注意：

  • ログイン済みusersとMessenger連携がある場合は、Messengerのセキュリティ強化を強く推奨します。

  • 複数のusersが同じメールアドレスを共有し、連携がメールのみを識別子として使う場合、Intercomはどのusersを使うか推測せず、競合エラーでリクエストを拒否します。認証成功のためには、JWTペイロードに安定した一意識別子（user_id）を必ず含めてください。JWTの本人確認にはuser_idが必須で、ないトークンは拒否されます。

JSON Web Token（JWT）とは？

JSON Web Token（JWT）はデータに署名する業界標準の方法です。通常3つの部分（header.payload.signature）にドットで区切られています。

  • ヘッダーはトークンタイプ（JWT）と署名アルゴリズム（例：HS256）を指定します。

  • ペイロードにはusersやセッションに関するクレーム（例：user_id、email）が含まれます。

  • 最後に署名は秘密鍵やプライベートキーを使い、トークンが改ざんされていないことを保証します。

MessengerをJSON Web Tokens（JWTs）で保護する利点は？

  • usersの本人確認を強化：Messengerを保護することで、チームメンバーは話しているusersが本物であることを確信できます。

  • usersデータのセキュリティ向上：Messengerを保護することで、Messenger APIを通じてusersのデータ属性を安全に送信できます。

  • 盗まれたセッションのリスク軽減：JWTでMessengerを保護するとトークンの有効期限を設定でき、usersのブラウザからトークンが盗まれた場合のデータ漏洩リスクを大幅に減らせます。短い有効期限を指定することでリスクが軽減されます。

  • 安全なFinとAI workflows：信頼できるusers情報が必要な複雑なプロセス、Actions、WorkflowsをFinに任せられます。

ヒント：Messenger Securityを有効にするとusersのMessenger内の全会話履歴が利用可能になります。有効でない場合、ログイン済みusersは過去14日間の会話のみ閲覧可能で、不正アクセス防止のためのセキュリティ措置です。Messenger Securityがチャネルで有効になると履歴制限は自動的に解除されます。詳細はUser conversation history visibilityをご覧ください。

usersの本人確認とデータを安全に送信し、トークンの有効期限を強制することで、JWTはIntercom Messengerを最も安全な状態に保ちます。

カスタマーエクスペリエンス

Intercom MessengerでJWTを使う場合の体験は以下の通りです：

  • Messenger連携はJWTを含むIntercom('boot')リクエストでログイン済みusersを起動し、送信したいusersデータをすべて含めます。JWTの署名は設定のMessengerシークレットキーで生成されます。

  • その後、IntercomはusersのブラウザにセッションCookieを発行します。このCookieはデフォルトで7日間有効で、ユーザー認証や更新に使用されます。

  • セッションが切れ、新しいJWTが送信されない場合、usersのセッションは終了します。usersはログアウトしたウェブサイト訪問者として新しいMessengerを見ます。会話履歴は含まれません。

  • MessengerがIntercom('boot')と有効なJWTで再起動されると、Messengerはusersを識別し、過去の会話と新しいセッションを表示します。同じデバイスでのログアウト中の活動も認証済みusersのアカウントに統合されます。

usersのセッションCookieの有効期間をデフォルトの7日より短くしたい場合は、session_duration Messenger属性でミリ秒単位のTTLを指定できます。

インストール：JWTの生成と送信

ステップ1：アプリケーションにMessengerをインストールする

ワークスペース固有のセットアップ手順は設定 > Messenger > セキュリティで確認できます。

安全でないMessenger設定と安全な設定の主な違いは、ユーザーリクエストに追加のintercomUserJwtフィールドを含め、それを使ってusersを識別・更新する点です。

注意：Javascriptスニペットにデータ属性を追加するオプションがあります。これはIntercomに送信したいデータを制御します。JWTでデータを送信するため、署名したくない属性（例：フロントエンド固有のデータ）のみここに含めるべきです。

JWT以外にデータを送信したくない場合は、api_baseとapp_id以外のデータをスニペットからすべて削除できます。app_idはIntercomワークスペースの一意識別子です。

ステップ2：usersのためにJWTを生成し始める

業界標準のJWTライブラリを使い、Messenger API Secretを秘密鍵としてトークンを生成できます。秘密鍵は設定 > ワークスペース > セキュリティ > Messengerで生成可能です。

Messenger設定 > セキュリティに戻り、バックエンドとフロントエンドのフレームワークを選択して、インストール用の関連コード例を取得してください。

Node.jsの例はこちらです：

重要：Messenger APIシークレットキーとJWT生成コードはフロントエンドコードに絶対に入れないでください。必ずサーバー側に置き、秘密鍵を適切に保護してください。

usersについて追加で送信したい属性（例：price_planやnumber_of_songs_added）があれば、それらもJWTに含めます。user_idは唯一必須のフィールドです。カスタムデータ属性についてはこちら。

JWTはいつ含めるべき？

Messengerでusersを起動したり、usersのデータを更新しようとするすべてのリクエストにJWTを送信してください。

どの有効期限を設定すべき？

JWTの有効期限は短く設定し、リクエストが完全に処理されるのに十分な期間だけ有効にしてください。有効期限は必須ではありませんが、トークンのリプレイリスクを減らすため強く推奨されます。

ステップ3：MessengerスニペットにJWTを追加する

ログイン済みusers向けにMessengerを起動する際、署名済みJSON Web Tokenを提供し、Messengerペイロードのintercom_user_jwt属性に割り当てます。

クライアント側設定例：

  window.Intercom("boot", {
   api_base: "https://api-iam.intercom.io",
   app_id: "APP_ID_CODE",
   intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
    };

このJWTにはusersの安全に送信したい任意のデータ属性を含められます。有効なJWTを受け取ると、usersのブラウザにデフォルト7日間有効のセッションCookieが作成されます。

MessengerセッションCookieのTTLを制御するには、設定 > チャンネル > Messenger > 一般 > Messengerのセキュリティを保つで最大値を設定できます。

ステップ4：属性の更新が無効になっていることを確認する

Messenger APIのデータ属性に対して安全でない更新を有効にすることが可能で、これによりMessenger経由のその属性の更新はすべて成功します。

JWTで安全にデータを送信する場合は、これらの属性に対して安全でないMessengerの更新を無効にすることで、有効なJWT経由でのみ更新されるようにしてください。注：このトグルは、botを使ってleadsから直接データを収集することを妨げるものではありません。

JWTで送信している属性には、このトグルを有効にすることをお勧めします。

ステップ5：ログアウト時にユーザーセッションをシャットダウンする

Intercomは、あなたが所有する公開サイト（マーケティングサイト、ドキュメントサイト、開発者ハブなど）にIntercom Messengerを設置できます。ユーザーがログインしている間、これらの異なるサブドメイン間で会話の連続性を維持するために、ユーザーのブラウザにクッキーを設定します。このクッキーは1週間で期限切れになります。

共有コンピュータとブラウザを他の誰かと使うユーザーは、クッキーが期限切れになるまで直近にログインしたユーザーの会話履歴を見ることができます。そのため、ユーザーのセッションが終了した際（手動または自動ログアウト時）にIntercomを適切にシャットダウンすることが非常に重要です。

Intercomをシャットダウンする方法は以下の通りです：

  1. すでにIntercom JSスニペットまたは“boot”メソッドでユーザーのトラッキングを開始しているはずです。

  2. ユーザーがIntercomからログアウトした（またはアプリによって自動的にログアウトされた）場合、JavaScript APIのIntercom('shutdown');を呼び出してIntercomセッションを終了し、クッキーをクリアしてください。

最終ステップ：ワークスペースのMessengerセキュリティを強制する

統合がユーザーのJWTを正しく送信している場合、Messenger設定 > セキュリティでトグルをオンにしてMessengerセキュリティを強制してください。これにより、Intercomはワークスペースユーザーのリクエストに対して有効なJWTまたは有効なuser_hashのいずれかでの保護を要求します。

トラブルシューティングガイド

インストールのデバッグに役立つ2つのツールがあります。1つは最近のエラーログを確認する方法、もう1つはトークンデバッガーです。

インストールログを確認する

設定 > チャンネル > Messenger > セキュリティのステップ6でインストールログを確認できます。ここにはJWTインストールに関連するすべての失敗ログが表示されます。JWTが無効、期限切れなどのエラーが表示されます。「ログを見る」をクリックすると、リクエストID、タイムスタンプ、リファラー、ユーザーデータを含む完全なログが表示されます。これにより、リクエストが失敗した理由を理解し、自分のアプリに遡って追跡するのに役立ちます。

一般的なエラーメッセージ

  • HTTP 400 - "user_hash and intercom_user_jwt cannot be provided simultaneously": リクエストにJWTとuser_hashの両方が含まれていました。顧客はこれらのいずれか一方を含めるべきで、両方を含めるべきではありません。

  • HTTP 400 - “Missing user_id in payload”: すべてのJWTはペイロードにuser_idを含むことが期待されています。顧客が“email”を主な識別子と考える場合、emailの値をペイロードのuser_idとemailフィールドの両方に入れるべきです。

  • HTTP 400 - “Invalid intercom_user_jwt payload”: JWTのペイロードが無効です。顧客はペイロードが正しく形成され、エンコードされ、api_secret値を署名秘密鍵として使用してSHA256 HMACで署名されていることを確認する必要があります。

  • HTTP 400 - “Intercom_user_jwt expired”: JWTの‘exp’は過去のタイムスタンプです。顧客は将来の有効期限を提供する必要があります。

  • HTTP 400 - “JWT identity mismatch": JWTに提供されたユーザーIDが、アクティブなintercomセッションcookieに関連付けられたユーザーと一致しません。これは2つの競合するセッションを開始しようとしていることを示します。新しいユーザーを起動する前にIntercom('shutdown')を呼び出していることを確認してください。

  • HTTP 400 - "Invalid intercom_user_jwt": 有効なユーザーを正しく起動していることを確認してください。

JWTデコーダー

このデコーダーツールではJSON web tokenをチェックできます。インストールページのサイドバーで見つけられます。

ツールで生成したユーザーJWTの1つを有効性チェックできます。JWTを生成するために使用した関連する秘密鍵を選択し、「デコード」をクリックしてください。

デコード後、JWTのペイロード、ヘッダー、そして有効か無効かのメモが表示されます。ペイロードを見ることで、属性を送信しているかどうかのトラブルシューティングに役立ちます。

この例では無効な秘密鍵を使い、user_idフィールドを含めていません。どちらも失敗の原因になります。

よくある質問

なぜJWT内にuser_idが必要なのですか？私のusersはメールアドレスだけです。

現在、usersの主な識別子としてuser_idを提供する必要があります。これまではuser_idかemailのどちらかを識別子としてサポートしていましたが、基本的なIdentity Verificationで製品の混乱を招いていました。

usersを識別するためにemailしかない場合、ペイロードのuser_idとemail属性の両方にemailアドレスを入れることができます。ただし、すでにIntercomにemailだけでusersがいる場合は、JWTを使う前にuser IDを追加する必要があります。これはuser IDがemailよりも上位の識別子だからです。

usersにuser IDを追加するには、まずユーザーのIntercom IDでユーザーを特定します。これはAPIの"Get a contact"エンドポイントで行えます。次に"Update a Contact"エンドポイントを使ってuser_idを追加します。詳細はこちら

user_idがない非ログインusers向けにはどう設定すればいいですか？

Messengerのセキュリティ機能は、usersに一意のuser IDを提供することを要求します。leads向けにMessengerを使うだけの場合は、この方法で識別できません。Messenger APIはusersのトラフィックに対して無効にするべきです。
​
これはMessenger > インストールで設定できます。使用しているインストール方法（web、iOS、Android）を選択し、「メッセンジャーへの接続を有効にする」トグルがusersに対してオフになっていることを確認してください。

有効期限はどのように設定すればいいですか？

Messengerが起動するたびに新しいJWTを送信する必要があります。トークンの有効期間はMessengerの起動間隔をサポートするだけで十分です。アプリの動作に適した最小期間を選択してください。ウェブページが頻繁にリロードされる場合、JWTは短命にすべきですが、予期しない期限切れを防ぐために最低5分を推奨します。

どの署名アルゴリズムが使えますか？

HS256（SHA-256を使ったHMAC）をサポートしています。このアルゴリズムは共有秘密鍵でトークンに署名・検証し、トークン内のデータが改ざんされていないことを保証します。

user_hashとintercom_user_jwtの両方を送信できますか？

いいえ、user_hashはJWTに置き換えられるべきなので、user_hashとintercom_user_jwtの両方を送信することはサポートしていません。ただし、移行中の顧客はuser_hashとintercom_user_jwtの送信を交互に行うことがあります。

現在Identity Verificationを使ってuser hashesを送信している場合は、JWT送信に切り替えるためのこのガイドを参照してください。

JWTが有効で正常に動作しているかどうかはどう確認できますか？

上記のトラブルシューティングセクションを参照してください。

ワークスペースでJWTの使用を強制するにはどうすればいいですか？

Messenger設定で強制トグルを有効にしてください。

どの属性を保護すべきですか？

すべての識別属性は保護マークを付け、可能であればJWTで安全に送信すべきです。これにはemail、電話番号、ユーザーレコードに保存されている可能性のあるaccount_idsが含まれます。属性は設定 > データ > Peopleで確認できます。

FinがActionやWorkflowの重要な部分で使用する属性は保護すべきです。悪意のあるユーザーがその値を上書きできないようにするためです。

JWTの外でデータを送信したい場合は、Messengerの更新を許可している限り可能ですが、ユーザー自身がこのフィールドを更新できることに注意してください。

    window.intercomSettings = {
      app_id: <APP_ID_CODE>,
      intercom_user_jwt: <TOKEN>,
      unsigned_data_attribute: 'data'
    };

ユーザーが何かをしている途中でセッションが期限切れになったら？

クッキーが期限切れた後にユーザーがMessengerでアクティビティを行うと、Intercomはユーザー体験に悪影響を与えないように1時間の短命クッキーを新たに発行します。ユーザー体験への意図しない影響を防ぐため、アプリのセッションタイムアウトに合わせたクッキーのセッション期間を選択することをお勧めします。

私のモバイルMessengerはどうなりますか？

iOSの手順はこちら、Androidはこちらでご覧いただけます。React Nativeも含まれます。

なぜペイロード全体の署名を必須にしないのですか？

お客様がアプリケーションでユーザーが操作している間に低精度のデータを送信する必要がある場合に対応できるよう、署名されていないAttributesの送信を許可しています。この機能が不要な場合は、すべてのUser Data Attributesを「Messengerの更新から保護」に設定し、署名済みペイロードのみを送信できます。

Messengerの秘密鍵はどのように管理・ローテーションしますか？

秘密鍵はワークスペースのMessengerセキュリティ設定で生成できます。

JWT設定ページの右側サイドバーで既存の鍵を見つけてコピーできます。

ワークスペース > セキュリティ > Messengerで鍵をローテーションできます。

JWTに含まれる属性は単一のticketまたは会話にのみ適用されますか？

いいえ。JSON Web Token（JWT）に含まれる属性は常にIntercomのユーザープロフィールを更新します。JWT属性は単一のticketや会話にのみ適用されるデータを追加するためには使用できません。

Identity Verificationはどうなりましたか？これがそれに代わるものですか？

Identity VerificationはMessenger Securityの以前のバージョンで、HMACユーザーハッシュを使ってユーザーリクエストが統合から送信されたことを識別します。
​
user_hashesは引き続き受け入れられますが、より多くのセキュリティ利点があるJWTの使用へのアップグレードを強く推奨します。Identity Verificationは今後更新されません。


JWTページからIdentity Verificationの管理も可能です。手順はJWT設定に合わせて更新されており、変更を行う場合はJWTへの移行を強く推奨しますが、機能の無効化やMessenger API秘密鍵のローテーションはJWT設定ページから引き続き行えます。

JWTに会社データを含めてユーザーを会社に関連付けることはできますか？

はい。JWTペイロードにcompany_idやその他の会社属性を含めて、Intercomでユーザーを会社に関連付けることができます。存在する場合、Intercomは起動時に会社を自動的に作成・関連付けします（ping/bootリクエスト中にインラインで作成されるため、追加の遅延はありません）。

これは、複数のユーザーが提出したticketsが共有会社ビューに集約されるTickets Portalなどの会社レベル機能を使用する設定で特に重要です。ユーザーが会社に関連付けられていない場合は、JWTペイロードにcompany_idが含まれているか確認してください。

重要：JWTの外で渡された会社データ（例えば、Intercom('boot')呼び出しのcompanyオブジェクト）はJWTが存在する場合は無視されます。会社は更新されず、会社のlast_seen値も更新されません。会社データを正しく更新するには、JWTペイロードに含めることを推奨します。これはすべての安全なMessenger設定に推奨される方法です。

または、ユーザーがログインする前にサーバーサイドAPIを使って会社を作成し、ユーザーを関連付けることもできます。これは、テナント作成時に会社レコードを事前に用意するなど、最初のユーザーセッション前に会社データが必要な場合に適した方法です。

注意：JWTにcompany_idを渡しているのにIntercomで会社が作成されない場合は、bugの可能性があるためサポートチームにお問い合わせください。

関連記事
こちらの回答で解決しましたか？