どこでもサポートのアドオンにおけるJWTによるユーザー認証(新しい認証フロー)

どこでもサポートのアドオンにおけるJWTによるユーザー認証(新しい認証フロー)

はじめに   

どこでもサポートのアドオンのユーザーには、 ゲストユーザー 認証ユーザー の2種類があります。どちらのユーザーであるかは、どこでもサポートのアドオンにサインインするか、しないかで決まります。
  1. ゲストユーザー
    1. ゲストユーザーとは、サインインせずに、どこでもサポートのアドオンの機能を利用するユーザーのことです。
    2. ゲストユーザーによって実行できる操作は、ナレッジベースへのアクセス、問い合わせの送信、ユーザーコミュニティでの投稿の表示、担当者とのチャットに限定されます。  

  2. 認証ユーザー
    1. 認証ユーザーとは、サインインを行ってどこでもサポートのアドオンの機能を利用するユーザーのことです。  
    2. 認証ユーザーによって実行できる操作には、ナレッジベースへのアクセス、問い合わせの送信、自分が送信した問い合わせの表示、担当者とのチャット、ユーザーコミュニティでの活動への参加(トピックのフォロー、トピックの追加、既存トピックへコメントの投稿など)などがあります。
メモ:
  1. どこでもサポートのアドオンでは、ゲストユーザーと認証ユーザーのそれぞれに対して、どの要素やコンテンツを表示するかを指定できます。
  2. Web用のどこでもサポートのアドオンを有効にする方法についての詳細は、 こちら をご参照ください。

JWT(JSON Web Token)とシングルサインオン(SSO)   

JWT (ジョット:JSON Web Token)とは、JSON形式の認証データを安全にやりとりするための方法です。IETF(インターネット技術特別調査委員会)によって標準規格として定められています。JWTでは、JSON形式で記述された認証データを一定の形式に変換してから、署名や暗号化を行います。このように、署名を行うことによってデータが改ざんされていないかどうかを確かめ、暗号化を行うことによってデータ保護することができます。 
 
JWTを使用した認証により、シングルサインオン(SSO:1つの認証情報で複数のサービスにアクセスすること)が可能になります。どこでもサポートのアドオンは、Zoho Deskを通じて提供されていますが、単独で使用するものではありません。Zoho Deskと他のアプリケーションと連携し、連携対象のアプリケーションにヘルプセンターの機能を組み込むために使用します。  

このようなことを考慮すると、連携対象のアプリケーションに一度サインインしたら、その認証情報によってどこでもサポートのアドオンにも同時にサインインできると便利です。連携対象のアプリケーションにサインインした後、どこでもサポートのアドオン用の認証情報でもサインインを行わなくてはならないとしたら時間や手間がかかります。JWTを使用したシングルサインオン(SSO)により、こうした課題を解決できます。

メモ:
  1. JWTに基づくユーザー認証は、Zoho Deskの設定で シングルサインオン(SSO) が有効になっている場合にのみ利用できます。シングルサインオンを有効にすると、1つのサービスに一度サインインするだけで、他のさまざまなサービスにもアクセスできるようになります。 シングルサインオンが有効になっていない場合、どこでもサポートのアドオンには、ゲストユーザーとしてのみアクセス可能です。
  2. 複数のヘルプセンター を設置している場合、シングルサインオンの設定は標準のヘルプセンターで有効にする必要があります。

JWTの有効化

JWTによる認証に欠かせないものとして、JWTシークレットがあります。JWTシークレットは、Zoho Deskでどこでもサポートのアドオンを設定したときに取得できる専用のコードで、ユーザー情報の署名に使用されます(JWTシークレットによって署名されたデータはJWTレスポンスと呼ばれます)。

JWTシークレットは、どこでもサポートのアドオンの登録時に一度だけ取得可能です。必ず安全な場所に保管し、不用意に共有しないようにしてください。

JWTによる認証の仕組み

JWTによる認証の仕組みは以下のとおりです。

認証フロー(認証の流れ)

  1. ユーザーが、どこでもサポートのアドオンが組み込まれているアプリケーションにサインインします。
  2. どこでもサポートのアドオンが組み込まれているアプリケーションから、クライアントID、クライアントシークレット、JWTの署名済みトークンが、ZohoのIAM(IDを認証、管理するためのシステム)のサーバー宛てに送信されます。この際、送信されるトークンには、ユーザーのメールアドレス、認証ステータス、サインインの時間間隔などのユーザー情報が含まれます。 
  3. IAMサーバーでは、JWTシークレットキーの暗号を解読して、以下のような認証処理を行います。
    1. サインインしたユーザーが有効な既存ユーザーであることが確認できた場合、ユーザーがどこでもサポートのアドオンにサインインできるように認証用のOAuthトークンを生成します。
    2. サインインしたユーザーが有効な新規ユーザーであることが確認できた場合、まずユーザーを追加してから、OAuthトークンを生成します。
    3. サインインしたユーザーが無効なユーザーである場合、エラーメッセージを送信します。

どこでもサポートのアドオンでのJWTの仕組み








JWTエンドポイントの役割  

JWTによる認証によってどこでもサポートのアドオンにサインインできるようにするには、JWTの認証設定の前に接続先のサーバー(連携対象のアプリケーションのサーバー)の設定を行う必要があります。このサーバーがJWTエンドポイントと呼ばれます。JWTエンドポイントでは、JWTを生成するコードが実行されている必要があります。

 
JWTエンドポイントでは、アドオン用に生成されたJWTシークレットを使用して、以下のようなコードが常時実行されている必要があります(以下はJavaの例です)。
                        
                           
                              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
アプリケーションにサインインしたユーザーの情報を、アプリケーションから取得するためのパラメーターです。
email
ユーザーのメールアドレスを返すためのパラメーターです。
email_verified
メールアドレスが認証されているかどうかを返す、真偽値(true/false)のパラメーターです。その後、OAuthのトークンをどこでもサポートのアドオンに送信します。
not_before not_after
JWTの期限が切れるまでの時間を表します。これらのパラメーターの値は、協定世界時(UTC:Coordinated Universal Time)形式によって、ミリ秒単位で指定する必要があります。

セキュリティ強度を確保するため、not_beforeパラメーターとnot_afterパラメーターの時間差は、600,000ミリ秒(10分)を超えないようにしてください。

どこでもサポートでJWTによるユーザー認証を行うためのコード

IAMサーバーにおいて、JWTトークンに含まれるユーザー情報が認証されると、認証用のOAuthトークンが生成され、クライアントに送信されます。クライアントでは、IAMサーバーから送信されたOAuthトークンを用いて、サインインしたユーザーが有効なZohoユーザーであることを認証できるようになります。
Web
生成されたJWTトークンをZohoのIAMサーバーに共有するために使用するため、クライアントで設定するコードは以下のとおりです。
                                    
                                       
                                          window.ZohoHCAsapSettings={
                                          userInfo :{
                                          jwtToken : "generated-jwt-token"
                                          }
                                          }
                                       
                                    
                                 

Android

setUserTokenメソッドでは、送信対象のトークンがユーザートークンであるかJWTトークンであるかを、真偽値(trueまたはfalse)のパラメーターによって指定します。
MyApplication.deskInstance.setUserToken(String jwtToken, ZDPortalCallback.SetUserCallback callback, boolean isJWT);

iOS

以下のメソッドでは、送信対象のトークンとしてJWTトークンを指定しています。
ZohoDeskPortalKit.login(withJWTToken: token, onCompletion: handler)
どこでもサポートのJWT設定において、userInfoスクリプトは、アプリのスクリプトを読み込む前に実行する必要があります。
JWTトークンの解読



留意事項   
  1. JWTレスポンスは、プレーンテキストとして返される必要があります。  
  2. JWTレスポンスには、 email email_verified not_before not_after の各パラメーターを含める必要があります。
  3. アプリケーションサーバーで時刻を変更すると、 not_before not_after のパラメーターで設定した値に影響を与える可能性があります。そのため、アプリケーションサーバーの時刻が変更された場合は、JWTコードを必ず修正してください。  
  4. 現在、署名はHMACSHA256アルゴリズムにのみ対応しています。 

どこでもサポートSDK(Web用/モバイル用)の既存ユーザー向けの注意事項

1) Zoho DeskでWeb/モバイル用のどこでもサポートのアドオンをすでに有効にしている場合、新しい認証フローの影響を受けません。引き続き、 従来のフロー による認証が行われます。
2)  Zoho DeskでWeb/モバイル用のどこでもサポートのアドオンを新たに、または追加で設定した場合は、新しい認証フローに基づいて認証が行われます。

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

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

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

    Zoho CRM Training



              Zoho WorkDrive Resources



                Zoho Desk Resources

                • Desk Community Learning Series


                • Digest


                • Functions


                • Meetups


                • Kbase


                • Resources


                • Glossary


                • Desk Marketplace


                • MVP Corner


                • Word of the Day









                                  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.