ASAPアドオンでの認証ユーザー用のJWT

はじめに

エンドユーザーが、ASAPアドオンにサインインするかどうかによって、ゲストユーザーや認証済みユーザーに分類できます。サインインしなかったユーザーはゲストユーザー、サインインしたユーザーは認証済みユーザーと呼ばれます。ASAPアドオンでは、表示するコンポーネントとコンテンツを、ユーザーの種類別に設定できます。

ゲストユーザーは、ナレッジベースへのアクセス/問い合わせの送信/ユーザーコミュニティの投稿の閲覧/カスタマーサポート担当者とのチャットを行うことができます。

一方、認証済みのユーザーは、ナレッジベースへのアクセス/問い合わせの送信/送信した問い合わせの閲覧/カスタマーサポート担当者とのチャット/ユーザーコミュニティへの積極的な参加（トピックのフォロー/トピックの追加/既存トピックへコメントの投稿など）を行うことができます。

JWTが必要な理由とは？

ASAPアドオンは、Zohoから提供されていますが、スタンドアローン（単独で機能する）アプリケーションではありません。主要なアプリと連携して機能し、ヘルプセンターの機能を活用できます。エンドユーザーは、一度アプリにサインインすると、ヘルプセンターなどの関連するすべての機能にアクセスしたいと思うでしょう。1つの認証情報でアプリケーションにサインインした後、別の認証情報を使用して、ヘルプセンターにサインインしなくてはならない（各サービスが別の認証方法を使用しているため）としたら、エンドユーザーにとっては大変不便です。そこで、JSON Webトークン（JWT）の登場です。

JWTベースのユーザー認証は、Zoho Deskポータルでシングルサインオン（SSO）が有効になっている場合にのみ可能です。SSOを使用すると、エンドユーザーが様々なサポートシステムにアクセスするために、複数のサインイン認証情報を使用する必要がなくなります。SSOが有効になっていない場合、エンドユーザーはゲストユーザーとしてのみ、ASAPアドオンにアクセスできます。
ポータル内のマルチブランドのヘルプセンターではなく、初期設定のヘルプセンターでシングルサインオン（SSO）が有効になっていることをご確認ください。

JWTとは？

JWT標準を作成した The Internet Engineering Task Forceという団体によると、JWTは「2つの当事者間で転送されるclaimを表す、コンパクトでURLセーフな手段2」と定義されています。

ASAPアドオンにおいては、JWTはメインアプリのユーザーの信頼性を検証し、ASAP主導のヘルプセンターを同じ認証情報で利用する許可を与える仕組みです。

図1：ASAPアドオンでのJWTの実装

JWTを有効にするための前提条件

JWTベースの認証には、次の2つの要素が不可欠です：

JWTエンドポイント
JWTシークレット

JWTエンドポイント ：ASAPアドオンのサーバーエンドポイントであり、JWT認証の設定前に設定する必要があります。このエンドポイントには、JWTを生成するコードが含まれている必要があります。このエンドポイントに、IAMサーバーがユーザートークンを含むGETリクエストを送信します。Zoho Deskでアドオンを設定するときは必ず、JWTエンドポイントの有効なURLを入力してください。

JWTのリダイレクトURLの例：https://safe-forest-77068.herokuapp.com/getjwt?user_token=token

JWTエンドポイントは、アドオン用に生成されたJWTシークレットを使用して、次のプログラムを常に実行する必要があります。

import io.jsonwebtoken.SignatureAlgorithm;
import javax.crypto.spec.SecretKeySpec;
import java.security.Key;
import io.jsonwebtoken.JwtBuilder;
import io.jsonwebtoken.Jwts;
import java.io.UnsupportedEncodingException;

public static String generateJwt(String userToken) throws UnsupportedEncodingException{
String secretKey = "; //この値はアドオンが作成された後に付与されます。次に、こちらで指定された値を置き換えます
long notBeforeMillis = System.currentTimeMillis();
long notAfterMillis = notBeforeMillis + 300000;

SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256;

byte[] apiKeySecretBytes = secretKey.getBytes();
Key signingKey = new SecretKeySpec(apiKeySecretBytes, signatureAlgorithm.getJcaName());

JwtBuilder builder = Jwts.builder().signWith(signatureAlgorithm, signingKey);

String jwt = builder.claim("email_verified", true)
.claim("not_after", notAfterMillis)
.claim("not_before", notBeforeMillis)
.claim("email", <user_email_address_from_user_token>).compact();
return jwt;
}

userToken は、アプリから受信したユーザートークンを入力するパラメーターです。このパラメーターには、アプリにサインインしているユーザーの詳細が表示されます。したがって、ユーザートークンが、アプリからZohoのIAMサーバーを経由してJWTエンドポイントに送信されるときに、暗号化されていることを確認してください。JWTエンドポイントでは、ユーザートークンを復号し、信頼性を確認する必要があります。
email のパラメーターは、ユーザーのメールアドレスを返します。
email_verified は、メールアドレスが認証されているかどうかを返す、ブーリアン型（論理型）のパラメーターです。その後、OAuthのトークンをASAPアドオンに送信します。
not_before と not_after パラメーターは、JWTの期限が切れるまでの期間を定義します。これらのパラメーターの値は、協定世界時（UTC：Coordinated Universal Time）形式で、ミリ秒単位で指定する必要があります。
強力なセキュリティを確保するために、not_beforeパラメーターとnot_afterパラメーターの時間差が、600,000ミリ秒（10分）を超えないようにしてください。

JWTシークレット ：JWTシークレットは、Zoho DeskでASAPアドオンを設定したときに共有される固有のコードです。JWTエンドポイントが、IAMサーバーから受信したユーザートークンを検証した後に、JWTシークレットがユーザー詳細の署名用に使用されます。この署名済みのデータは、JWTレスポンスと呼ばれます。

JWTシークレットは、アドオンの登録時に一度だけ共有されます。シークレットは、安全な場所で保管し、信頼できない相手とは共有しないでください。

JWTの仕組みとは？

ユーザーが、メインアプリの認証情報を使用して、ASAPアドオンにログインしようとする際、アプリが、認証のために、そのクライアントID、クライアントシークレット、ユーザートークンを、ZohoのIAMサーバーに送信します。

IAMサーバーが、認証情報が有効であると判断した場合、JWTリダイレクトURLを経由して、ユーザートークンとGETユーザーリクエストをJWTエンドポイントに送信します。

次に、JWTエンドポイントは、ユーザートークンの信頼性を確認します。この認証の後：

ユーザートークンが有効な場合、ユーザーの詳細（ユーザーのメールアドレス、メール認証のステータス、サインイン間隔）を含むJWTレスポンスが、JWTシークレットで署名され、IAMサーバーに返送されます。

ユーザートークンが無効な場合は、JWTレスポンスが、 email_verified パラメーターの値がfalseに設定されたまま、返送されます。
IAMサーバーが、有効なJWTレスポンスを受信すると、エンドユーザーをヘルプデスクポータルのユーザーとみなすOAuth2トークンを送信します。

ASAPアドオンの場合、JWTを取得するためには、セキュリティ上の理由から、GETメソッドを使用する必要があります。

留意事項

JWTのURLは、設定ページでいつでも変更できます。
URLには、ユーザー情報をJWTサーバーに渡すための「user_token」というパラメーターを含める必要があります。
JWTレスポンスは、プレーンな文字列として返される必要があります。
JWTレスポンスには、 email 、 email_verified 、 not_before 、 not_after の各パラメーターを含める必要があります。
アプリサーバー時間の変更は、 not_before と not_after パラメーターで設定した値に影響を与える可能性があります。そのため、アプリケーションサーバーの時刻が変更された場合は、JWTコードを必ず修正してください。
現在、署名にはHMACSHA256アルゴリズムのみがサポートされています。