新しいJavascript APIとJWTトークンを使用して、ページが読み込まれるたびに訪問者を認証するようにウィジェットを設定できます。
この記事は、次のバージョンのZendesk Chatをお使いの方を対象としています。
- Zendesk Chatフェーズ3(Chat単体)
以下のいずれかのバージョンをご使用の場合は、「認証済み訪問者をWeb Widget(従来版)で有効にする方法」を参照してください。
- Zendesk Chatフェーズ4(Chat単体またはSupportとChatの併用)
- Zendesk Chatフェーズ3(Web Widget(従来版)のオンラインチャットを使用)
ご使用のChatのバージョンを確認する方法が不明な場合は、「Zendesk Chatアカウントのバージョンを確認する」を参照してください。
この記事では、次のトピックについて説明します。
概要
Chatウィジェットの使用を認証済み訪問者のみに許可するように構成すると、次のような利点があります。
-
エージェントが対話している訪問者/カスタマーを信頼し、セキュリティを維持できる。
-
クロスドメイントラフィックのサポート。ウィジェットを複数のドメインに埋め込む場合、または外部でホストされているサービス(Shopifyなど)にリンクする場合、訪問者を認証することで、ドメインをまたがるChatプラットフォームへの訪問者を一意に識別できます。これにより、エージェントが多くの背景情報を得ることができます。
-
クロスデバイス・クロスブラウザ識別のサポート。認証呼び出しでカスタムIDが特定されているときに訪問者が別のデバイスまたはブラウザを使用することを選択した場合、訪問者を同一人物と見なすことができます。
Chatの共有シークレットを新規作成する
訪問者認証を要求するようウィジェットを設定するには、共有シークレットが必要です。共有シークレットはセキュリティ設定なので、生成したら間をおかずに、エンジニアリングチームとのコミュニケーションまたはコードベースに直接貼り付けてください。ブラウザに入力してはなりません。
Chat管理者のみが訪問者認証を設定できます。
認証された訪問者に必要な共有シークレットを生成するには
- Chatダッシュボードを開き、「設定」>「ウィジェット」に移動します。
- 「ウィジェットのセキュリティ」タブをクリックします。
- 下にスクロールして「訪問者の認証」セクションを表示し、「生成」ボタンをクリックします。
新しい共有シークレットを再生成すると、前回のトークンは無効になります。共有シークレットにセキュリティ侵害の懸念がある場合は、新しいシークレットを再生成する必要があります。キーを回転させる必要がある場合は、Chatがオフラインのときにスケジュールを設定してください。シークレットを再生成すると、訪問者が5分程度ウィジェットから切断される可能性があるためです。
共有シークレットを生成したら、それを使用してWeb Widgetスニペットに追加するJWTトークン(JWTの詳細はこちらを参照)を作成します。
JWTトークンを作成する
JWTトークンを作成してChatスタンドアローンスニペットにコードを追加するには
- JWTトークン用にサーバー側のデータペイロードを構築します。これには以下の情報が必要です。
- name:カスタマーの名前
- email:カスタマーのメールアドレス
- external_id:カスタマーに固有の英数字による文字列。いったん設定したら、このIDは変更できません。このフィールドには、システム内で一意のユーザーIDを使用することをお勧めします。たとえば、「user-123456」と指定します。
- iat:現在のタイムスタンプの整数値(秒単位)。言語によっては、たとえばJavaScript's Date.now()のようにミリ秒を返す関数があるので、秒単位に換算する必要があります。Chat認証用のiatで許可されるクロックスキューは最大2分です。
- exp:現在のタイムスタンプの整数値(秒単位)。この値は、このJWTトークンがいつ期限切れになるかを示します。この値は、iat値から最大7分まで許容されています。
- JWTペイロードのヘッダーにJWTアルゴリズムとして、次のようにHS256を指定します。
{ "typ":"JWT", "alg":"HS256" }
HS256は、HMAC SHA 256を表します。これは、アメリカ国家安全保障局によって開発された256ビットの暗号化アルゴリズムです。
メモ:Zendeskは、RS256とES256のJWTアルゴリズムをサポートしていません。 - 下のコードサンプルの中から言語の要件に合ったテンプレートを探してください。
- $zopim.livechat.authenticate Javascript APIを使用して、呼び出されるたびに新しいJWTを提供する関数を提供します。以下はコードサンプルです。
上記のサンプルでは、JWT_TOKEN_ENDPOINTは、独自のサーバーに実装して新しいJWTを取得できるエンドポイントです。$zopim(function() { $zopim.livechat.authenticate({ jwtFn: function(callback) { fetch('JWT_TOKEN_ENDPOINT').then(function(res) { res.text().then(function(jwt) { callback(jwt); }); }); } }); });
メモ:チャットセッションの有効期間中は、jwtFnをチャットセッション中に複数回呼び出して、新しいJWTを取得して訪問者の身元を確認できます。 - $ zopim.livechat.clearAll() APIを使用して、ユーザーがホストアプリ/Webサイトからログアウトしたときにウィジェットからユーザーをログアウトさせることができます。
シングルページアプリの場合、$ zopim.livechat.clearAll() APIを使用した後で訪問者を再認証することはできません。訪問者を再認証できる状態にするには、ページをリロードする必要があります。
コードサンプル
トークンは、ページの読み込み時にサーバー側から動的に生成される必要があります。言語の要件に合ったテンプレートを以下のサンプルから見つけます。必要に応じてサンプルをカスタマイズし、#{details}をご自分の情報で置き換えてください。
これらのサンプルのどれも要件に合致しない場合は、JWTライブラリの広範なリストで探してみてください。
Ruby
まず、ruby-jwtをインストールします。
Rubygemsを使用している場合:
gem install jwt
Bundlerを使用している場合は、gemファイルに次の行を追加します。
gem 'jwt'
次に、共有シークレットを使用してトークンを生成します。
require 'jwt'
payload = {
:name => "#{customerName}",
:email => "#{customerEmail}",
:iat => timestamp,
:external_id => "#{externalId}"
}
token = JWT.encode payload, "#{yourSecret}"
NodeJS
jsonwebtokenをインストールします。
npm install jsonwebtoken --save-dev
次に、共有シークレットを使用してトークンを生成します。
var jwt = require('jsonwebtoken');
var payload = {
name: '#{customerName}',
email: '#{customerEmail}',
iat: #{timestamp},
external_id: '#{externalId}'
};
var token = jwt.sign(payload, '#{yourSecret}');
Python
python-joseをインストールします。
pip install python-jose
共有シークレットを使用してトークンを生成します。
from jose import jwt
var payload = {
'name': '#{customerName}',
'email': '#{customerEmail}',
'iat': #{timestamp},
'external_id': '#{externalId}'
}
token = jwt.encode(payload, '#{yourSecret}'
PHP
PHP-JWTをダウンロードします。
composer require firebase/php-jwt
共有シークレットを使用してトークンを生成します。
use \Firebase\JWT\JWT;
$payload = {
'name' => '#{customerName}' ,
'email' => '#{customerEmail}',
'iat' => #{timestamp},
'external_id' => '#{externalId}'
};
$token = JWT::encode($payload, '#{yourSecret}');
Elixir
`json_web_token_ex`を`mix.exs`ファイルに追加します。
defp deps do
[{:json_web_token, "~> 0.2"}]
end
共有シークレットを使用してトークンを生成します。
data = %{
name: "#{customerName}",
email: "#{customerEmail}",
iat: "#{timestamp}",
external_id: "#{externalId}"
}
options = %{ key: "#{yourSecret}" }
jwt = JsonWebToken.sign data, options
認証済み訪問者とのエージェントエクスペリエンスについて
認証済み訪問者とエージェントがチャットを開始すると、Chatダッシュボードでいくつかの項目が更新されます。
まず、エージェントは訪問者のアバターに緑色のチェックマークを重ねて表示し、認証済みであることを示すことができます。
エージェントはまた、訪問者の名前やメールアドレスを編集できないことに気付くでしょう。なぜなら、これらの情報はJavascript APIを介して送信されたものだからです。
最後に、認証済み訪問者を出入り禁止すると、その訪問者は別のデバイスやブラウザからもChatウィジェットにアクセスできなくなります。
認証済み訪問者とのウィジェットエクスペリエンスについて
Chatウィジェットでは、認証済み訪問者のエクスペリエンスは少し異なります。まず、情報は読み取り専用であり、ウィジェットやJavascript APIを介してこれらの情報を変更することはできません。
次に、訪問者が認証されると、進行中のチャットセッションがデバイス間で同期されます。これにより、訪問者はコンピューターまたはブラウザを切り替えて(たとえばデスクトップWebブラウザのChatウィジェットとモバイルWebブラウザのChatウィジェットの間を)移動しても、やりとりしているチャットセッションを継続できます。
最後に、ポップアウト経由でIDを確認する手段がないため、認証済み訪問者はチャットのポップアウト機能を利用できません(この機能は当社のドメインzopim.comでホストされます)。