どこでもサポートのアドオンにおけるJWTによるユーザー認証

どこでもサポートのアドオンにおけるJWTによるユーザー認証

はじめに

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

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

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

JWTが必要な理由とは？

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

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

JWTとは？

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

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

図1：どこでもサポートのアドオンでのJWTの実装

JWTを有効にするための前提条件
JWTベースの認証には、次の2つの要素が不可欠です：
  • JWTエンドポイント
  • JWTシークレット
JWTエンドポイント ：どこでもサポートのアドオンのサーバーエンドポイントであり、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のトークンをどこでもサポートのアドオンに送信します。 
  • not_before と not_after パラメーターは、JWTの期限が切れるまでの期間を定義します。これらのパラメーターの値は、協定世界時（UTC：Coordinated Universal Time）形式で、ミリ秒単位で指定する必要があります。 
  • 強力なセキュリティを確保するために、not_beforeパラメーターとnot_afterパラメーターの時間差が、600,000ミリ秒（10分）を超えないようにしてください。 

JWTシークレット ：JWTシークレットは、Zoho Deskでどこでもサポートのアドオンを設定したときに共有される固有のコードです。JWTエンドポイントが、IAMサーバーから受信したユーザートークンを検証した後に、JWTシークレットがユーザー詳細の署名用に使用されます。この署名済みのデータは、JWTレスポンスと呼ばれます。 
 
JWTシークレットは、アドオンの登録時に一度だけ共有されます。シークレットは、安全な場所で保管し、信頼できない相手とは共有しないでください。

JWTの仕組みとは？

ユーザーが、メインアプリの認証情報を使用して、どこでもサポートのアドオンにログインしようとする際、アプリが、認証のために、そのクライアントID、クライアントシークレット、ユーザートークンを、ZohoのIAMサーバーに送信します。 
 
IAMサーバーが、認証情報が有効であると判断した場合、JWTリダイレクトURLを経由して、ユーザートークンとGETユーザーリクエストをJWTエンドポイントに送信します。 
 
次に、JWTエンドポイントは、ユーザートークンの信頼性を確認します。この認証の後： 
ユーザートークンが有効な場合、ユーザーの詳細（ユーザーのメールアドレス、メール認証のステータス、サインイン間隔）を含むJWTレスポンスが、JWTシークレットで署名され、IAMサーバーに返送されます。
  • ユーザートークンが無効な場合は、JWTレスポンスが、 email_verified パラメーターの値がfalseに設定されたまま、返送されます。
  • IAMサーバーが、有効なJWTレスポンスを受信すると、エンドユーザーをヘルプデスクポータルのユーザーとみなすOAuth2トークンを送信します。 
どこでもサポートのアドオンの場合、JWTを取得するためには、セキュリティ上の理由から、GETメソッドを使用する必要があります。

留意事項

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





関連情報：