JSONウェブトークン（JWT）は第三者がログイン中のusersになりすまし、その会話を覗くのを防ぎます。すべてのFin顧客にJWT認証の強制を強く推奨します。
サイトにログイン中のusers向けにFin Messengerを設置している場合、悪意ある者がusersになりすましたり不正なデータを送信するのを防ぐために、必ずセキュリティを強化してください。
セキュリティが不十分なMessengerでは、誰かがFin Messengerとやり取りし、メールアドレスやuser_idなどの既知の識別子を使って別のuserの身元を偽装する可能性があります。これにより攻撃者は実際のuserになりすまし、チームメイトにアクセスし、過去の会話や機密データにアクセスできる恐れがあります。
JSONウェブトークン（JWT）とは何ですか？
JWTはデータに署名する業界標準の方法です。通常、ドットで区切られた3つの部分から成り、典型的なJWTはheader.payload.signatureの形をしています。
ヘッダーはトークンタイプ（JWT）と署名アルゴリズム（例：HS256）を指定します。
ペイロードにはuserやセッションに関するクレーム（例：user_id、email）が含まれます。
最後に、署名は秘密鍵やプライベートキーを使ってトークンが改ざんされていないことを保証します。
JSONウェブトークン（JWT）でMessengerを保護する利点は何ですか？
安全なuser識別: Messengerを保護することで、チームメイトは話しているuserが本当にそのuserであることを確信できます。
強化されたuserデータのセキュリティ: Messengerを保護することで、Messenger APIを通じてuserに関するデータ属性を安全に送信できます。
盗まれたセッションによるリスクの軽減: JWTでMessengerを保護すると、トークンの有効期限を設定でき、usersのブラウザからトークンが盗まれた場合のデータ漏洩リスクを大幅に減らせます。短い有効期限を指定することでリスクが軽減されます。
より安全なFinとAI workflows: 複雑なプロセス、Actions、Workflowsに信頼できるuser情報が必要な場合でもFinに任せられます。
userの識別情報とデータを安全に送信し、トークンの有効期限を強制することで、JWTはFin Messengerを最も安全な状態に保ちます。
カスタマーエクスペリエンス
Fin MessengerでJWTを使う場合の体験は以下の通りです：
Messengerの統合は、JWTを含む
Intercom('boot')リクエストでログイン中のuserを起動します。JWTの署名は設定のMessenger秘密鍵を使って生成されます。その後、workspaceはuserのブラウザにセッションクッキーを提供します。このクッキーのデフォルト有効期間は7日間で、ユーザー認証と更新に使用されます。
セッションが期限切れで新しいJWTが送信されない場合、userのセッションは終了します。userはログアウトしたウェブサイト訪問者として新しいMessengerを見ます。会話履歴は含まれません。
Messengerが
Intercom('boot')と有効なJWTで再起動されると、Messengerはuserを識別し、過去の会話と新しいセッションを表示します。同じデバイスでのログアウト中の活動も認証済みuserのアカウントに統合されます。
ヒント:
userのセッションクッキーの有効期間をデフォルトの7日より短くしたい場合は、session_duration Messenger属性でミリ秒単位のTTLを指定できます。
Fin MessengerからZendesk ticketsを作成し、特定の組織にticketsをルーティングしたい場合は、JWTにcompanyフィールドを含めることができます。
idの値はZendesk組織の外部ID（内部Zendesk IDではありません）と一致する必要があります。
インストール：JWTの生成と送信
ステップ1：アプリケーションにMessengerをインストールする
workspace固有のセットアップ手順は設定 > Messenger > セキュリティで確認できます。
安全でないMessengerセットアップと安全なセットアップの主な違いは、ユーザーリクエストに追加のintercomUserJwtフィールドを含め、それがuserの識別と更新に使われる点です。
Javascriptスニペットにデータ属性を追加するオプションがあります。これはFin workspaceに送信したいデータを制御します。JWTでデータを送信するため、署名したくない属性（例：フロントエンド固有のデータ）のみをここに含めるべきです。
JWT以外にデータを送信したくない場合は、api_baseとapp_id以外のデータをスニペットからすべて削除できます。app_idはFin workspaceの固有識別子です。
user_idやemailなどのuser固有識別子がない訪問者には、App IDのみを含むログアウト状態のMessengerスニペットを設定してください。匿名訪問者向けに軽量で安全な構成を維持するため、user属性は追加しないでください。
ステップ2：usersのためにJWTを生成し始める
業界標準のJWTライブラリを使い、Messenger API Secretを秘密鍵としてトークンを生成できます。秘密鍵はworkspaceのセキュリティ設定のMessengerタブで生成可能です。
注意：JWTトークンは各userセッションごとに一意に生成する必要があります。トークンにはuser_idなどの識別クレームを含め、Messenger API Secretで署名して正しいuserに安全に紐付けられるようにしてください。
インストールに適したコード例を得るために、バックエンドとフロントエンドのフレームワークを選択してください。
Node.jsの例はこちらです：
usersに関する追加属性（例：price_planやnumber_of_songs_added）を送信したい場合は、それらもJWTに追加します。user_idは唯一必須のフィールドです。JWTペイロードと属性内のフィールド名は大文字小文字を区別します。例えば「user_id」は小文字の'i'で書く必要があり、「user_Id」では正しい識別ができません。
注意：Fin生成のJWKを使ってJWTトークンに署名する場合、subクレームはFinが割り当てたUser IDがデフォルトで一意のuser識別子として機能します。JWK機構を使うとsub値は固定されカスタマイズ不可で、互換性と誤設定防止を保証します。
ステップ3：MessengerスニペットにJWTを追加する
ログイン中のuser向けにMessengerを起動する際、署名済みJSON Web Tokenを提供し、Messengerペイロードのintercom_user_jwt属性に割り当てられます。あるいは、ログイン前にIntercom.setUserJwt(jwt)を使ってJWTトークンを割り当て、データの安全な帰属を行うことも可能です。
クライアント側設定の例
window.Intercom("boot", {
api_base: "https://api-iam.intercom.io",
app_id: "APP_ID_CODE",
intercom_user_jwt: <YOUR_USER_JWT_TOKEN>,
};
このJWTにはuserに安全に送信したい任意のuserデータ属性を含められます。有効なJWTが受信されると、userのブラウザにデフォルト7日間のセッションクッキーが作成されます。
MessengerセッションクッキーのTTLを制御するには、Messengers一般設定の「Keep your Messenger secure」ドロップダウンで最大値を設定できます。
ステップ4：属性の更新を無効にすることを確認する
Messenger APIのデータ属性に対して安全でない更新を有効にすることが可能で、Messenger経由のその属性の更新はすべて成功します。
JWTで安全に送信しているデータがある場合、それらの属性に対して安全でないMessenger更新を無効にし、有効なJWT経由のみで更新されるようにしてください。注：この切り替えはbotでleadsから直接データ収集することは妨げません。
JWTで送信している属性にはこの切り替えを有効にすることを推奨します。
ステップ5：ログアウト時にuserセッションを終了する
所有する公開サイト（マーケティングサイト、ドキュメントサイト、開発者ハブなど）にFin Messengerを設置できます。usersがログイン中に異なるサブドメイン間で会話の継続性を保つため、userのブラウザにクッキーを設定します。このクッキーは1週間で期限切れになります。
共有コンピュータとブラウザを他のusersと共有している場合、cookieが期限切れになるまで直近にログインしたuserの会話履歴が見られます。そのため、ユーザーのセッションが終了した際（手動または自動ログアウト時）には、Fin Messengerを適切にシャットダウンすることが非常に重要です。
Fin Messengerのシャットダウン方法は以下の通りです：
Intercom JSスニペットまたは“boot”メソッドを使って、すでにuserのトラッキングを開始しているはずです。
userがFin Messengerからログアウトする（またはアプリによって自動的にログアウトされる）際には、JavaScript APIのIntercom('shutdown');を呼び出してセッションを終了し、cookieをクリアしてください。
最終ステップ：ワークスペースのMessengerセキュリティを強制する
integrationがuser向けに正しくJWTを送信している場合は、Messenger設定でMessengerセキュリティをオンにして強制してください。これにより、Fin Messengerはワークスペースのusersからのリクエストに対し、有効なJWTまたは有効なuser_hashのいずれかでの認証を要求します。
注意：JWT認証は現在、Fin MessengerのiOSおよびAndroid SDKではサポートされていません。モバイル実装の場合は、SDKのサポートが利用可能になるまでJWTの代わりにIdentity Verification（HMAC-SHA256）を使用し続けてください。
トラブルシューティングガイダンス
インストールのデバッグに役立つ2つのツールがあります。1つは最近のエラーログを確認する方法、もう1つはトークンデバッガーです。
インストールログを確認する
設定 > チャンネル > Messenger > セキュリティのステップ6でインストールログを確認できます。ここにはJWTインストールに関連するすべての失敗ログが表示されます。JWTが無効、期限切れなどのエラーが記録されます。「ログを見る」をクリックすると、リクエストID、タイムスタンプ、リファラー、userデータを含む完全なログが表示されます。これにより、リクエスト失敗の原因を理解し、自分のアプリに遡って追跡できます。
よくあるエラーメッセージ
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に提供されたuser IDが、アクティブなintercomセッションcookieに関連付けられたuserと一致しません。これは2つの競合するセッションを開始しようとしていることを示します。新しいuserを起動する前に必ずIntercom('shutdown')を呼び出してください。HTTP 400 - "Invalid intercom_user_jwt": 有効なuserを正しく起動していることを確認してください。JWTトークンの検証に失敗した場合（例えば、クレームの不一致や不適切な署名のため）、会話は自動的に終了され、問題のデバッグに役立つAPIエラーログにエラーが記録されます。
JWTデコーダー
当社のデコーダーツールはJSON web tokenの検証も可能です。設定 > Messenger > セキュリティのサイドバーで見つけられます。
ツールで生成したuser JWTの有効性を確認できます。JWT生成に使用した関連する秘密鍵を選択し、デコードをクリックしてください。
デコード後、JWTのペイロードからuserの詳細、ヘッダー、および有効か無効かの注記が表示されます。
この例では無効な秘密鍵を使用し、user_idフィールドを含めていません。どちらも失敗の原因となります。
よくある質問
なぜJWTにuser_idが必要なのですか？
現在、user_idをusersの主な識別子として提供する必要があります。これまではuser_idまたはemailのいずれかを識別子としてサポートしていましたが、基本的なIdentity Verificationで大きな混乱を招いていました。emailだけでusersを識別する場合は、ペイロードのuser_idとemail属性の両方にemailアドレスを入れてください。
user_idがない非ログインusers向けにはどう設定すればよいですか？
Messengerセキュリティ機能は、usersに一意のuser IDを提供することを要求します。leads向けにMessengerを使用している場合は、この方法で識別できません。ただし、他のintegration（REST API、CSVなど）からworkspaceにuser_idを持つusersがいる場合は、JWT Messengerセキュリティを有効にして、誰かがそれらのusersのMessengerを起動しようとするのを防ぐべきです。ログアウトした訪問者向けには、認証なしで動作する軽量版Messengerを設定できます。App IDのみでMessengerスクリプトを読み込み、userデータやJWTトークンを渡さないようにしてください。これにより、ユーザーフレンドリーさを保ちつつ、システムの機能性とデータの整合性を維持できます。
要するに、workspaceに推測可能な識別子（email、user_id）を持つusersがいる場合は、Messengerセキュリティを有効にすべきです。ログイン済みとログアウト済みのusersの両方をサポートする場合は、セキュリティと使いやすさのために混合戦略を採用してください。ログイン済みuserセッションにはJWT認証を使用して機密情報を保護し、ログアウト済み訪問者にはuser固有のトークンやデータなしで簡易Messenger設定を許可します。
有効期限はどのように設定すればよいですか？
Messengerが起動されるたびに新しいJWTを送信すべきであり、トークンの有効期間はMessengerの起動間の時間をサポートすれば十分です。アプリの動作に適した最小期間を選択してください。ウェブページが頻繁にリロードされる場合はJWTは短命であるべきですが、予期せぬ期限切れを防ぐために最低5分を推奨します。常にJWTに有効期限（exp）クレームを含めて、盗まれたトークンの影響を減らしセキュリティを確保してください。
どの署名アルゴリズムが使えますか？
以下をサポートしています：
HS256（SHA-256を用いたHMAC）。このアルゴリズムは共有秘密鍵でトークンを署名・検証し、トークン内のデータが改ざんされていないことを保証します。
JWT用のRS256は非対称鍵ペアを使用します。署名は秘密鍵、検証は公開鍵で行い、強化されたセキュリティの代替手段を提供します。
JSON Web Key（JWK）構成は、Fin生成の鍵とシームレスに統合でき、トークン管理を効率化します。
user_hashとintercom_user_jwtの両方を送信できますか？
いいえ、user_hashはJWTに置き換えられるべきため、user_hashとintercom_user_jwtの両方を送信することはサポートしていません。ただし、移行中の顧客はuser_hashとintercom_user_jwtの値を交互に送信することがあります。
JWTが有効で正常に動作しているかどうかはどう確認できますか？
上記のトラブルシューティングセクションを参照してください。
workspaceでJWTの必須化をどのように強制しますか？
Messenger設定で強制トグルを有効にしてください。
どの属性を保護すべきですか？
すべての識別属性は保護マークを付け、可能であればJWTで安全に送信すべきです。これにはemail、電話番号、顧客がUserレコードに保存する可能性のあるaccount_idsが含まれます。属性は設定 > People Dataで確認できます。
FinがActionやWorkflowの重要部分で使用する属性は、悪意のあるuserが値を上書きできないよう保護すべきです。
JWT外でデータを送信したい場合は、Messengerの更新を許可していれば可能ですが、user自身がこのフィールドを更新できることに注意してください。
window.intercomSettings = {
app_id: <APP_ID_CODE>,
intercom_user_jwt: <TOKEN>,
unsigned_data_attribute: 'data'
};
userが何か操作中にセッションが期限切れたらどうなりますか？
cookieが期限切れた後にuserがMessengerで操作を行うと、ユーザー体験への悪影響を避けるために1時間の短期cookieが新たに発行されます。ユーザー体験への意図しない影響を防ぐため、cookieのセッション期間はアプリのセッションタイムアウトに合わせることを推奨します。
なぜペイロード全体の署名を要求しないのですか？
ユーザーがアプリケーションで操作を行っている間に、ユーザーに関する低精度のデータを送信する必要がある場合に対応するため、署名されていない属性を送信できるようにしています。この機能が不要な場合は、すべてのUser Data Attributesを「Messengerの更新から保護」に設定し、署名済みペイロードのみを送信できます。
Messengerの秘密鍵はどのように管理およびローテーションしますか？
秘密鍵はワークスペースのMessengerセキュリティ設定で生成できます。
JWT設定ページの右側サイドバーで既存の鍵を見つけてコピーできます。
Workspace > Security > Messengerで鍵をローテーションできます。
Identity Verificationはどうなりましたか？JWTがそれに代わるものですか？
Identity Verificationは、ユーザーリクエストがあなたの統合から送信されたことを識別するためにHMACユーザーハッシュを使用するMessenger Securityの以前のバージョンです。
user_hashesは引き続き受け入れられますが、より多くのセキュリティ利点があるため、すべてのユーザーにJWTへのアップグレードを強く推奨します。Identity Verificationは今後更新されません。
JWTページからIdentity Verificationのインストールを管理する必要がある場合は、まだ可能です。手順はJWT設定に合わせて更新されており、変更を行う場合はJWTへの移行を強く推奨しますが、機能を無効にしたりMessenger APIの秘密鍵をローテーションしたりする必要がある場合は、Settings > Security > Messengerから引き続き実行できます。
JWTに会社データを含めて、ユーザーを会社に関連付けることはできますか？
はい。JWTペイロードにcompany_idやその他の会社属性を含めて、ユーザーを会社に関連付けてください。これにより、起動時に会社が自動的に作成および関連付けられ、追加の遅延は発生しません。
重要：JWTの外で渡された会社データ（例えば、Intercom('boot')呼び出しのcompanyオブジェクトとして）は、JWTが存在する場合は無視されます。会社は更新されず、会社のlast_seen値も更新されません。会社データが正しく更新されるように、JWTペイロードに含めてください。