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

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

はじめに

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

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

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

JWTが必要な理由とは?

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

  1. JWTベースのユーザー認証は、Zoho Deskポータルでシングルサインオン(SSO)が有効になっている場合にのみ可能です。SSOを使用すると、エンドユーザーが様々なサポートシステムにアクセスするために、複数のサインイン認証情報を使用する必要がなくなります。SSOが有効になっていない場合、エンドユーザーはゲストユーザーとしてのみ、ASAPアドオンにアクセスできます。
                      
  2. ポータル内のマルチブランドのヘルプセンターではなく、初期設定のヘルプセンターでシングルサインオン(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エンドポイントは、アドオン用に生成された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アルゴリズムのみがサポートされています。 






    Zoho CRM 管理者向けトレーニング

    「導入したばかりで基本操作や設定に不安がある」、「短期間で集中的に運用開始できる状態にしたい」、「運用を開始しているが再度学び直したい」 といった課題を抱えられているユーザーさまに向けた少人数制のオンライントレーニングです。

    日々の営業活動を効率的に管理し、導入効果を高めるための方法を学びましょう。

    Zoho CRM Training










                          Resources

                          Videos

                          Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                          eBooks

                          Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                          Webinars

                          Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                          CRM Tips

                          Make the most of Zoho CRM with these useful tips.